자습서: Azure App Service 및 PostgreSQL에 Quarkus 웹앱 배포

이 자습서에서는 Azure Database for PostgreSQL 관계형 데이터베이스 서비스를 사용하여 데이터 기반 Quarkus 웹 애플리케이션을 Azure App Service에 배포합니다. Azure App Service는 Windows 또는 Linux 서버 환경에서 Java SE(Java Standard Edition)를 지원합니다.

PostgreSQL에 데이터를 저장하는 Quarkus 애플리케이션의 스크린샷.

이 튜토리얼에서는 다음을 배우게 됩니다:

Azure App Service 및 Azure Database for PostgreSQL 유연한 서버에 대한 기본 보안 아키텍처를 만듭니다.
관리 ID 및 Key Vault 참조를 사용하여 연결 비밀을 보호합니다.
GitHub 리포지토리에서 App Service에 샘플 Quarkus 앱을 배포합니다.
애플리케이션 코드에서 App Service 앱 설정에 액세스합니다.
업데이트를 하고 애플리케이션 코드를 다시 배포합니다.
데이터베이스 마이그레이션을 실행하여 데이터베이스 스키마를 생성합니다.
Azure에서 진단 로그를 스트리밍합니다.
Azure Portal에서 앱을 관리합니다.
Azure Developer CLI를 사용하여 동일한 아키텍처를 프로비전하고 배포합니다.
GitHub Codespaces와 GitHub Copilot으로 개발 워크플로를 최적화합니다.

필수 조건

활성 구독이 있는 Azure 계정. Azure 계정이 없으면 무료 계정을 만들 수 있습니다.
GitHub 계정. 무료로 하나를 받을 수도 있습니다.
Quarkus 개발을 사용한 Java에 대한 지식.
(선택 사항) GitHub Copilot을 시도하려면 GitHub Copilot 계정이 필요합니다. 30일 평가판을 사용할 수 있습니다.

활성 구독이 있는 Azure 계정. Azure 계정이 없으면 무료 계정을 만들 수 있습니다.
GitHub 계정. 무료로 하나를 받을 수도 있습니다.
Azure 개발자 CLI를 설치해야 합니다. Azure Developer CLI가 이미 설치되어 있으므로 Azure Cloud Shell을 사용하여 단계를 수행할 수 있습니다.
Quarkus 개발을 사용한 Java에 대한 지식.
(선택 사항) GitHub Copilot을 시도하려면 GitHub Copilot 계정이 필요합니다. 30일 평가판을 사용할 수 있습니다.

Azure에서 실행되는 이 자습서에서 샘플 앱을 보려면 Azure Cloud Shell에서 다음 명령을 실행하고 프롬프트를 따릅니다.

mkdir msdocs-quarkus-postgresql-sample-app
cd msdocs-quarkus-postgresql-sample-app
azd init --template msdocs-quarkus-postgresql-sample-app
azd up

1. 샘플 실행

먼저 샘플 데이터 기반 앱을 시작점으로 설정합니다. 사용자 편의를 위해 샘플 리포지토리인 Hibernate ORM(Panache, RESTEasy 사용)에는 개발 컨테이너 구성이 포함됩니다. 개발 컨테이너에는 데이터베이스, 캐시 및 샘플 애플리케이션에 필요한 모든 환경 변수를 포함하여 애플리케이션을 개발하는 데 필요한 모든 것이 있습니다. 개발 컨테이너는 GitHub codespace에서 실행할 수 있습니다. 즉, 웹 브라우저를 사용하여 모든 컴퓨터에서 샘플을 실행할 수 있습니다.

1단계: 새 브라우저 창에서 다음을 수행합니다.

GitHub 계정에 로그인합니다.
https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app/fork로 이동합니다.
기본 분기만 복사를 선택 취소합니다. 모든 분기를 선택해야 하기 때문입니다.
포크 만들기를 선택합니다.

Step 2: GitHub 포크에서:

시작 분기에 대한 기본>시작-인프라 없음을 선택합니다. 이 분기는 샘플 프로젝트만 포함하고 Azure 관련 파일이나 구성은 포함하지 않습니다.
코드>starter-no-infra에서 코드스페이스 생성을 선택합니다. 코드스페이스를 설정하는 데 몇 분 정도 걸립니다.

3단계: codespace 터미널에서 다음을 수행합니다.

mvn quarkus:dev을 실행합니다.
알림 무시 Your application running on port 5005 is available.
Your application running on port 8080 is available.이라는 알림이 표시되면 브라우저에서 열기를 선택합니다. 새 브라우저 탭에서 샘플 애플리케이션을 볼 수 있습니다. Quarkus 개발 서버를 중지하려면 Ctrl+C를 입력합니다.

Quarkus 샘플 애플리케이션을 만드는 방법에 대한 자세한 내용은 Quarkus 설명서 Simplified Hibernate ORM with Panache(Panache를 사용하여 Hibernate ORM 간소화) 및 Configure data sources in Quarkus(Quarkus에서 데이터 원본 구성)를 참조하세요.

팁

이 리포지토리에 대해 GitHub Copilot에 요청할 수 있습니다. 예를 들면 다음과 같습니다.

@workspace 이 프로젝트의 용도를 알려 줘.
@workspace .devcontainer 폴더의 기능을 알려 줘.

문제가 있나요? 문제 해결 섹션을 확인하세요.

2. App Service 및 PostgreSQL 만들기

이 단계에서는 Azure 리소스를 만듭니다. 이 자습서에 사용된 단계에서는 App Service 및 Azure Database for PostgreSQL을 포함하는 기본 보안 리소스 세트를 만듭니다. 만들기 프로세스의 경우 다음을 지정합니다.

웹앱의 이름입니다. 이는 https://<app-name>-<hash>.<region>.azurewebsites.net 형식의 앱에 대한 DNS 이름의 일부로 사용됩니다.
전 세계에서 앱을 물리적으로 실행할 지역입니다. 사용자 앱의 DNS 이름의 일부로도 사용됩니다.
앱의 런타임 스택입니다. 여기에서 앱에 사용할 Java 버전을 선택합니다.
앱에 대한 호스팅 계획입니다. 앱에 대한 기능 및 크기 조정 용량 세트를 포함하는 가격 책정 계층입니다.
앱의 리소스 그룹입니다. 리소스 그룹을 사용하면 애플리케이션에 필요한 모든 Azure 리소스를 논리 컨테이너에 그룹화할 수 있습니다.

Azure Portal에 로그인하고 다음 단계에 따라 Azure App Service 리소스를 만듭니다.

1단계: Azure Portal에서:

위쪽 검색 창에 App Service를 입력합니다.
서비스 제목 아래에 있는 App Service 레이블이 지정된 항목을 선택합니다.
웹앱 만들기 마법사로 직접 이동할 수도 있습니다.

2단계: 새 앱 구성 다음과 같이 양식을 작성합니다.

이름: msdocs-quarkus-postgres. msdocs-quarkus-postgres_group 리소스 그룹이 자동으로 생성됩니다.
런타임 스택: Java 21.
Java 웹 서버 스택: Java SE(포함 웹 서버).
운영 체제: Linux.
지역: 가까운 모든 Azure 지역입니다.
Linux 계획: 새로 만들고msdocs-quarkus-postgres라는 이름을 사용합니다.
가격 책정 계획: 기본 B1. 준비가 되면 다른 가격 책정 계층으로 확장할 수 있습니다.

3단계: 데이터베이스 추가

데이터베이스 탭을 선택합니다.
데이터베이스 만들기를 선택합니다.
엔진에서 PostgreSQL - 유연한 서버를 선택합니다. 서버 이름과 데이터베이스 이름은 기본적으로 적절한 값으로 설정됩니다.

4단계: GitHub 배포 구성

배포 탭을 선택합니다.
연속 배포를 선택합니다.
App Service에서 GitHub 배포를 처음으로 구성하는 경우 GitHub 계정으로 권한 부여 및 인증을 선택합니다.
조직에서 GitHub 별칭을 선택합니다.
리포지토리에서 msdocs-quarkus-postgresql-sample-app을 선택합니다.
분기에서 starter-no-infra를 선택합니다.
검토 + 만들기를 선택합니다.
유효성 검사가 완료되면 만들기를 선택합니다. 기본적으로 만들기 마법사는 Microsoft Entra(OIDC 인증)를 사용하여 인증할 워크플로에 대한 사용자 할당 ID를 만듭니다 . 대체 인증 옵션은 GitHub Actions를 사용하여 App Service에 배포를 참조하세요.

3단계: 배포를 완료하는 데 몇 분 정도 걸립니다. 배포가 완료되면 리소스로 이동 단추를 선택합니다. App Service 앱으로 직접 이동하지만 다음 리소스가 생성됩니다.

리소스 그룹: 생성된 모든 리소스에 대한 컨테이너입니다.
App Service 계획: App Service에 대한 컴퓨팅 리소스를 정의합니다. 기본 계층의 Linux 계획이 만들어집니다.
App Service: 앱을 나타내고 App Service 계획에서 실행됩니다.
가상 네트워크: App Service 앱과 통합되고 백 엔드 네트워크 트래픽을 격리합니다.
Azure Database for PostgreSQL 유연한 서버: 가상 네트워크 내에서만 액세스할 수 있습니다. 서버에 데이터베이스와 사용자가 만들어집니다.
프라이빗 DNS 영역: 가상 네트워크에서 키 자격 증명 모음과 데이터베이스 서버의 DNS 확인을 사용하도록 설정합니다.

3. 보안 연결 비밀

생성 마법사는 이미 앱 설정으로 연결 변수를 생성했습니다. 그러나 보안을 위한 가장 좋은 방법은 App Service에서 비밀을 완전히 보호하는 것입니다. 서비스 커넥터의 도움으로 비밀을 키 자격 증명 보관소로 옮기고 앱 설정을 키 자격 증명 보관소 참조로 변경합니다.

1단계: 기존 연결 문자열 검색

App Service 페이지의 왼쪽 메뉴에서 설정 > 환경 변수를 선택합니다.
연결 문자열을 선택합니다.
AZURE_POSTGRESQL_CONNECTIONSTRING을 선택합니다.
애플리케이션 추가/편집 설정의 값 필드에서 문자열 끝에 있는 사용자 ID= 및 암호= 부분을 찾습니다.
나중에 사용할 사용자 ID= 및 암호= 후에 사용자 이름 및 암호 문자열을 복사합니다. 이 앱 설정을 사용하면 프라이빗 엔드포인트 뒤에서 보호되는 Postgres 데이터베이스에 연결할 수 있습니다. 하지만 비밀은 App Service 앱에 직접 저장되며, 이는 최선이 아닙니다. 당신은 이것을 변경할 것입니다.

2단계: Key Vault 보안을 위한 서브넷 만들기 가상 네트워크에는 이미 두 개의 기존 서브넷이 있지만 하나는 App Service에 이미 위임되어 있고 다른 하나는 이미 Azure Database for PostgreSQL에 위임되어 있습니다. 프라이빗 엔드포인트를 사용하여 Key Vault에 안전하게 액세스하기 위해 다른 엔드포인트를 만듭니다(자세한 내용은 Azure Key Vault에 대한 네트워크 보안 참조).

App Service 페이지의 왼쪽 메뉴에서 개요 탭을 선택합니다.
앱의 리소스 그룹을 선택합니다.
리소스 그룹에서 가상 네트워크를 선택합니다.
가상 네트워크의 왼쪽 메뉴에서 설정 > 서브넷을 선택합니다.
+ 서브넷을 선택합니다.
이름에 subnet-keyvault를 입력합니다. 기본값을 그대로 적용합니다.
추가를 선택합니다.

3단계: 비밀의 안전한 관리를 위한 키 자격 증명 저장소 만들기

위쪽 검색 창에 "키 볼트"을 입력한 다음, 마켓플레이스>키 볼트를 선택합니다.
리소스 그룹에서msdocs-quarkus-postgres_group 선택합니다.
Key Vault 이름에서 문자와 숫자로만 구성된 이름을 입력합니다.
지역에서 리소스 그룹과 동일한 위치로 설정합니다.

4단계: 프라이빗 엔드포인트를 사용하여 키 자격 증명 모음 보호

네트워킹 탭을 선택합니다.
공용 액세스 사용을 선택 취소합니다.
프라이빗 엔드포인트 만들기를 선택합니다.
리소스 그룹에서msdocs-quarkus-postgres_group 선택합니다.
대화 상자의 위치에서 App Service 앱과 동일한 위치를 선택합니다.
이름에 msdocs-quarkus-postgresVaultEndpoint를 입력합니다.
가상 네트워크에서vnet-xxxxxxx를 선택합니다.
서브넷에서 서브넷-키 저장소.
확인을 선택합니다.
검토 + 생성를 선택한 다음, 생성를 선택합니다. 키 자격 증명 모음 배포가 완료될 때까지 기다립니다. “배포가 완료되었습니다”라고 표시됩니다.

5단계: PostgreSQL 커넥터 만들기

위쪽 검색 창에서 msdocs-quarkus-postgres를 입력한 다음 msdocs-quarkus-postgres라는 App Service 리소스를 선택합니다.
App Service 페이지의 왼쪽 메뉴에서 [설정 > 서비스 커넥터 > 만들기]를 선택합니다.
서비스 유형에서 PostgreSQL 유연한 서버용 DB를 선택합니다.
PostgreSQL 유연한 서버에서 msdocs-quarkus-postgres-server는 이미 선택되어 있어야 합니다.
PostgreSQL 데이터베이스에서 msdocs-quarkus-postgres-database를 선택합니다.
클라이언트 유형에서 Java를 선택합니다.

6단계: 키 자격 증명 모음에 비밀 저장

인증 탭을 선택합니다.
연결 문자열을 선택합니다.
사용자 이름 및 암호에 이전에 복사한 암호를 붙여넣습니다.
Key Vault에 비밀 저장을 선택합니다.
Key Vault 연결에서 새로 만들기를 선택하세요. 연결 만들기 대화 상자가 편집 대화 상자의 맨 위에 열립니다.

7단계: Key Vault 연결 설정

Key Vault 연결을 위한 연결 만들기 대화 상자에서 Key Vault에서 이전에 만든 Key Vault를 선택합니다.
클라이언트 유형에서 일관성을 위해 Java를 선택합니다. 애플리케이션 코드는 실제로 키 자격 증명 모음을 직접 사용하지 않습니다.
검토 + 생성를 선택합니다.
유효성 검사가 완료되면 만들기를 선택합니다.

8단계: PostgreSQL 커넥터 설정 완료

PostgreSQL 커넥터에 대한 편집 대화 상자로 돌아왔습니다. 인증 탭에서 키 볼트 커넥터가 만들어질 때까지 기다립니다. 완료되면 Key Vault 연결 드롭다운에서 자동으로 선택합니다.
검토 + 생성를 선택합니다.
유효성 검사가 완료되면 만들기를 선택합니다. 만들기 성공 알림이 나타날 때까지 기다립니다.

9단계: Key Vault 통합 확인

왼쪽 메뉴에서 설정 > 환경 변수를 다시 선택합니다.
AZURE_POSTGRESQL_CONNECTIONSTRING 옆에 있는 값 표시를 선택합니다. 값은 @Microsoft.KeyVault(...)이어야 합니다. 이는 비밀이 이제 키 저장소에서 관리되기 때문에 키 저장소 참조임을 의미합니다.

10단계: App Service에서 데이터베이스 자격 증명 삭제

연결 문자열 탭을 선택합니다.
AZURE_POSTGRESQL_CONNECTIONSTRING 오른쪽에서 삭제를 선택합니다. 만들기 마법사는 처음에 이 연결 문자열을 만들었습니다.

요약하자면, 관련된 연결 비밀을 보호하는 프로세스는 다음과 같습니다.

App Service 앱의 환경 변수에서 연결 비밀을 검색합니다.
프라이빗 엔드포인트로 키 자격 증명 모음을 만듭니다.
시스템 할당 관리 ID를 사용하여 Key Vault 연결을 만듭니다.
키 자격 증명 모음에 연결 비밀을 저장하기 위해 서비스 커넥터를 만듭니다.
App Service 앱에서 이전 연결 비밀을 삭제합니다.

문제가 있나요? 문제 해결 섹션을 확인하세요.

4. 샘플 코드 배포

만들기 마법사에서 GitHub Actions를 사용하여 샘플 GitHub 리포지토리에서 연속 배포를 이미 구성했습니다. 이는 App Service에 배포하는 여러 방법 중 하나일 뿐 아니라 배포 프로세스에서 연속적으로 통합할 수 있는 좋은 방법이기도 합니다. 기본적으로 GitHub 리포지토리에 대한 모든 git push는 빌드 및 배포 작업을 시작합니다.

다음 사항에 유의하세요.

Quarkus는 기본적으로 포트 8080을 수신 대기합니다. 프로덕션 환경에서는 App Service의 환경 변수에 지정된 PORT 포트를 수신 대기하도록 구성해야 합니다.
배포된 Java 패키지는 Uber-Jar여야 합니다.
자습서를 단순화하기 위해 배포 프로세스 중에는 테스트를 사용하지 않습니다. GitHub Actions 실행기는 Azure의 PostgreSQL 데이터베이스에 액세스할 수 없으므로, Quarkus 샘플 애플리케이션의 경우와 같이 데이터베이스에 액세스해야 하는 모든 통합 테스트가 실패합니다.

1단계: 샘플 포크의 GitHub 코드스페이스로 돌아가서 실행 git pull origin starter-no-infra합니다. 이렇게 하면 새로 커밋된 GitHub 워크플로 파일이 코드스페이스로 가져와집니다.

2단계(옵션 1: GitHub Copilot 사용):

채팅 보기를 선택한 다음 +을 선택하여 새 채팅 세션을 시작합니다.
"@workspace 앱이 데이터베이스에 어떻게 연결됩니까?" Copilot는 Quarkus 데이터 원본 설정이 src/main/resources/application.properties에서 구성된 방법에 대한 몇 가지 설명을 제공할 수 있습니다.
"@workspace Java 클라이언트 유형을 사용하여 Azure App Service에서 PostgreSQL 서비스 커넥터를 만들었으며 앱 설정 이름이 AZURE_POSTGRESQL_CONNECTIONSTRING. 앱이 프로덕션 환경에서 실행 중일 때 이 연결 문자열을 사용하려고 합니다." Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
탐색 기에서 src/main/resources/application.properties 를 열고 코드 제안을 추가합니다.
"@workspace Uber Jar를 만들도록 이 프로젝트를 구성하려면 어떻게 해야 하나요?" Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
탐색 기에서 src/main/resources/application.properties 를 열고 코드 제안을 추가합니다.
"@workspace App Service 포트를 어떻게 사용합니까?" Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
탐색 기에서 src/main/resources/application.properties 를 열고 코드 제안을 추가합니다. GitHub Copilot은 매번 동일한 응답을 제공하지 않으며 항상 정확하지는 않습니다. 응답을 미세 조정하려면 더 많은 질문을 해야 할 수도 있습니다. 팁을 보려면 내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?를 참조하세요.

2단계(옵션 2: GitHub Copilot 제외):

탐색기에서 src/main/resources/application.properties를 엽니다. Quarkus는 이 파일을 사용하여 Java 속성을 로드합니다.
10-12줄을 주석 해제합니다. 이러한 설정은 PostgreSQL 커넥터로 만든 앱 설정을 사용하고, Uber Jar를 만들고, App Service에서 사용하는 포트로 포트를 설정합니다.

3단계(옵션 1: GitHub Copilot 사용):

"@workspace GitHub Actions 배포의 경우 데이터베이스 관련 오류를 방지하기 위해 테스트를 건너뛰고 싶습니다." Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 .github/workflows/starter-no-infra_msdocs-quarkus-postgres.yml 파일을 변경하라고 지시할 수도 있습니다.
탐색기에서 .github/workflows/starter-no-infra_msdocs-quarkus-postgres.yml 열고 코드 제안을 추가합니다. 팁을 보려면 내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?를 참조하세요.

3단계(옵션 2: GitHub Copilot 제외):

탐색기에서 .github/workflows/starter-no-infra_msdocs-quarkus-postgres.yml 엽니다. 이 워크플로는 만들기 마법사가 사용자를 위해 만든 GitHub Actions 워크플로입니다.
Build with Maven 단계를 찾아보고, run 명령을 mvn clean install -DskipTests로 수정합니다. -DskipTests 는 데이터베이스 오류에서 배포가 실패하지 않도록 Maven에 테스트를 건너뛰도록 지시합니다. GitHub Actions 컨테이너는 PostgreSQL 서버에 연결할 수 없습니다.

4단계:

원본 제어 확장을 선택합니다.
텍스트 상자에 Configure DB and deployment 같은 커밋 메시지를 입력합니다. 또는 을 선택하고 GitHub Copilot이 커밋 메시지를 생성하도록 합니다.
커밋을 선택한 다음 예를 눌러 확인합니다.
동기화 변경 내용 1을 선택한 다음 확인을 눌러 확인합니다.

5단계:

왼쪽 메뉴에서 배포>센터>로그를 선택합니다.
배포 실행에 대한 로그 항목에서 최신 타임스탬프를 사용하여 로그 빌드/배포 항목을 선택합니다.

6단계: GitHub 리포지토리로 이동하여 GitHub 작업이 실행 중인지 확인합니다. 워크플로 파일은 빌드 및 배포라는 두 가지 개별 단계를 정의합니다. GitHub 실행이 성공 상태를 표시할 때까지 기다립니다. 약 5분 정도 소요됩니다.

문제가 있나요? 문제 해결 섹션을 확인하세요.

5. 앱으로 이동

1단계: App Service 페이지에서 다음을 수행합니다.

왼쪽 메뉴에서 개요를 선택합니다.
앱의 URL을 선택합니다.

2단계: 목록에 몇 가지 과일을 추가합니다. 축하합니다. Azure Database for PostgreSQL에 연결하여 Azure App Service의 웹앱을 실행하고 있습니다.

6. 진단 로그 스트림

Azure App Service는 애플리케이션 문제를 진단하는 데 도움이 되도록 콘솔에 모든 메시지 출력을 캡처합니다. 샘플 애플리케이션에는 아래와 같이 이 기능을 설명하는 표준 JBoss 로깅 문이 포함되어 있습니다.

private static final Logger LOGGER = Logger.getLogger(FruitEntityResource.class.getName());

@GET
public List<FruitEntity> get() {
    LOGGER.info("In FruitEntityResource.get()");
    return FruitEntity.listAll(Sort.by("name"));
}

1단계: App Service 페이지에서 다음을 수행합니다.

왼쪽 메뉴에서 모니터링>App Service 로그를 선택합니다.
애플리케이션 로깅에서 파일 시스템을 선택합니다.
상단 메뉴에서 저장을 선택합니다.

2단계: 왼쪽 메뉴에서 로그 스트림을 선택합니다. 플랫폼 로그 및 컨테이너 내부의 로그를 포함하여 앱에 대한 로그가 표시됩니다.

.NET, Node.js, Python 및 Java 애플리케이션에 대한 Azure Monitor OpenTelemetry 사용 시리즈의 Java 앱에서 로깅에 대해 자세히 알아보세요.

7. 리소스 정리

완료되면 리소스 그룹을 삭제하여 Azure 구독에서 모든 리소스를 삭제할 수 있습니다.

1단계: Azure Portal 상단의 검색 창에서:

리소스 그룹 이름을 입력합니다.
리소스 그룹을 선택합니다.

2단계: 리소스 그룹 페이지에서 리소스 그룹 삭제를 선택합니다.

3단계:

리소스 그룹 이름을 입력하여 삭제를 확인합니다.
삭제를 선택합니다.
Delete를 눌러 다시 확인합니다.

2. Azure 리소스 만들기 및 샘플 앱 배포

이 단계에서는 Azure 리소스를 만들고 Linux의 App Service에 샘플 앱을 배포합니다. 이 자습서에 사용된 단계에서는 App Service 및 Azure Database for PostgreSQL을 포함하는 기본 보안 리소스 세트를 만듭니다.

개발 컨테이너에는 이미 AZD(Azure Developer CLI)가 있습니다.

GitHub 코드스페이스의 리포지토리 루트에서 azd init을(를) 실행합니다.
```
azd init --template javase-app-service-postgresql-infra
```

메시지가 표시되면 다음 답변을 제공합니다.

질문	Answer
현재 디렉터리는 비어 있지 않습니다. '<your-directory>'에서 프로젝트를 초기화하시겠습니까?	예
이러한 파일로 어떤 작업을 하고 싶나요?	기존 파일을 변경하지 않은 상태로 유지
새 환경 이름 입력	고유한 이름을 입력합니다. AZD 템플릿은 Azure(`<app-name>-<hash>.azurewebsites.net`)에서 웹앱의 DNS 이름의 일부로 이 이름을 사용합니다. 영숫자 및 하이픈은 허용됩니다.

azd auth login 명령을 실행하고 프롬프트에 따라 Azure에 로그인합니다.
```
azd auth login
```
명령을 사용하여 필요한 Azure 리소스를 만듭니다 azd provision . 프롬프트에 따라 Azure 리소스에 대해 원하는 구독 및 위치를 선택합니다.
```
azd provision
```
azd provision 명령을 완료하는 데 약 15분이 걸립니다(Redis Cache에 가장 많은 시간이 소요됨). 나중에 App Service에서 작동하도록 코드를 수정하고 변경 내용을 azd deploy배포합니다. 실행되는 동안 명령은 Azure 배포에 대한 링크를 포함하여 프로비전 및 배포 프로세스에 대한 메시지를 제공합니다.

이 AZD 템플릿에는 다음 Azure 리소스를 사용하여 기본 보안 아키텍처를 생성하는 파일(azure.yaml 및 인프라 디렉터리)이 포함되어 있습니다.
- 리소스 그룹: 생성된 모든 리소스에 대한 컨테이너입니다.
- App Service 계획: App Service에 대한 컴퓨팅 리소스를 정의합니다. 기본 계층의 Linux 계획이 만들어집니다.
- App Service: 앱을 나타내고 App Service 계획에서 실행됩니다.
- 가상 네트워크: App Service 앱과 통합되고 백 엔드 네트워크 트래픽을 격리합니다.
- 프라이빗 엔드포인트: 가상 네트워크의 키 자격 증명 모음과 Redis Cache에 대한 엔드포인트에 액세스합니다.
- 네트워크 인터페이스: 각 프라이빗 엔드포인트에 대해 하나씩 개인 IP 주소를 나타냅니다.
- Azure Database for PostgreSQL 유연한 서버: 가상 네트워크 내에서만 액세스할 수 있습니다. 서버에 데이터베이스와 사용자가 만들어집니다.
- 프라이빗 DNS 영역: 가상 네트워크에서 PostgreSQL 서버의 DNS 확인을 사용하도록 설정합니다.
- log Analytics 작업 영역: 로그를 쿼리할 수도 있는 로그를 발송하기 위한 앱의 대상 컨테이너 역할을 합니다.
- Azure Managed Redis: 개인 엔드포인트 뒤에서만 접근 가능합니다.
- Key Vault: 프라이빗 엔드포인트를 통해서만 액세스할 수 있습니다. App Service 앱의 비밀을 관리하는 데 사용됩니다.
프로비전이 완료되면 AZD 출력에서 설정을 AZURE_POSTGRESQL_CONNECTIONSTRING 찾습니다. 비밀을 안전하게 유지하기 위해 설정 이름만 표시됩니다. AZD 출력에서 다음과 같이 표시됩니다.
```
 App Service app has the following connection settings:
         - AZURE_POSTGRESQL_CONNECTIONSTRING
         - AZURE_REDIS_CONNECTIONSTRING
         - AZURE_KEYVAULT_RESOURCEENDPOINT
         - AZURE_KEYVAULT_SCOPE
 
```
사용하는 AZD 템플릿은 앱 설정으로 이미 연결 변수를 생성하고 편의를 위해 터미널에 출력합니다. 앱 설정은 코드 리포지토리에서 연결 비밀을 유지하는 좋은 방법입니다. 만든 App Service 앱의 앱 설정 페이지에 대한 직접 링크를 찾을 수도 있습니다.

문제가 있나요? 문제 해결 섹션을 확인하세요.

3. 샘플 코드 수정 및 다시 배포

App Service에서 작동하려면 애플리케이션 코드를 몇 가지 변경해야 합니다.

Quarkus는 기본적으로 포트 8080을 수신 대기합니다. 프로덕션 환경에서는 App Service의 환경 변수에 지정된 PORT 포트를 수신 대기하도록 구성해야 합니다.
배포된 Java 패키지는 Uber-Jar여야 합니다.
자습서를 단순화하기 위해 배포 프로세스 중에는 테스트를 사용하지 않습니다. GitHub Actions 실행기는 Azure의 PostgreSQL 데이터베이스에 액세스할 수 없으므로, Quarkus 샘플 애플리케이션의 경우와 같이 데이터베이스에 액세스해야 하는 모든 통합 테스트가 실패합니다.

GitHub Copilot 사용
GitHub Copilot 사용 안 함

GitHub codespace에서 채팅 보기를 선택한 다음, +을 선택하여 새 채팅 세션을 시작합니다.
"@workspace 앱이 데이터베이스에 어떻게 연결됩니까?" Copilot는 src/main/resources/application.properties에서 쿼쿠스 데이터 원본 설정이 구성된 방법에 대한 몇 가지 설명을 제공할 수 있습니다.
"@workspace Java 클라이언트 유형을 사용하여 Azure App Service에서 PostgreSQL 서비스 커넥터를 만들었으며 앱 설정 이름이 AZURE_POSTGRESQL_CONNECTIONSTRING. 앱이 프로덕션 환경에서 실행 중일 때 이 연결 문자열을 사용하려고 합니다." Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
src/main/resources/application.properties에 코드 제안을 추가합니다.
"@workspace Uber Jar를 만들도록 이 프로젝트를 구성하려면 어떻게 해야 하나요?" Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
src/main/resources/application.properties에 코드 제안을 추가합니다.
"@workspace App Service 포트를 어떻게 사용합니까?" Copilot는 아래 GitHub Copilot 단계 없이 옵션 2의 코드 제안과 유사한 코드 제안을 제공하고 src/main/resources/application.properties 파일을 변경하라고 지시할 수도 있습니다.
src/main/resources/application.properties에 코드 제안을 추가합니다.

GitHub Copilot은 매번 동일한 응답을 제공하지 않으며 항상 정확하지는 않습니다. 응답을 미세 조정하려면 더 많은 질문을 해야 할 수도 있습니다. 팁을 보려면 내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?를 참조하세요.
터미널에서 azd deploy을 실행합니다.
```
azd deploy
```

탐색기에서 src/main/resources/application.properties를 엽니다. Quarkus는 이 파일을 사용하여 Java 속성을 로드합니다.
10-12줄을 주석 해제합니다. 이러한 설정은 PostgreSQL 커넥터로 만든 앱 설정을 사용하고, Uber Jar를 만들고, App Service에서 사용하는 포트로 포트를 설정합니다.
터미널에서 azd deploy을 실행합니다.
```
azd deploy
```

비고

azd up을(를) 실행하면 azd package, azd provision, 및 azd deploy을(를) 결합합니다. 처음에 이 작업을 수행하지 않은 이유는 아직 코드를 수정할 PostgreSQL 연결 설정이 없기 때문입니다. 실행한 경우 azd up Quarkus 앱이 여기에서 변경한 내용 없이는 시작할 수 없으므로 배포 단계가 중단됩니다.

문제가 있나요? 문제 해결 섹션을 확인하세요.

5. 앱으로 이동

AZD 출력에서 앱의 URL을 찾아 브라우저에서 탐색합니다. URL은 AZD 출력에서 다음과 같습니다.

 Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: https://<app-name>.azurewebsites.net/

목록에 몇 가지 과일을 추가합니다.

축하합니다. Azure Database for PostgreSQL에 연결하여 Azure App Service의 웹앱을 실행하고 있습니다.

문제가 있나요? 문제 해결 섹션을 확인하세요.

6. 진단 로그 스트림

Azure App Service는 애플리케이션 문제를 진단하는 데 도움이 되는 콘솔 로그를 캡처할 수 있습니다. 편의를 위해 AZD 템플릿은 이미 로컬 파일 시스템에 로깅을 사용하도록 설정하고 로그를 Log Analytics 작업 영역으로 전달하고 있습니다.

샘플 애플리케이션에는 아래와 같이 이 기능을 설명하는 표준 JBoss 로깅 문이 포함되어 있습니다.

private static final Logger LOGGER = Logger.getLogger(FruitEntityResource.class.getName());

@GET
public List<FruitEntity> get() {
    LOGGER.info("In FruitEntityResource.get()");
    return FruitEntity.listAll(Sort.by("name"));
}

AZD 출력에서 App Service 로그를 스트리밍하는 링크를 찾아 브라우저에서 탐색합니다. 링크는 AZD 출력에서 다음과 같습니다.

Stream App Service logs at: https://portal.azure.com/#@/resource/subscriptions/<subscription-guid>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name>/logStream

.NET, Node.js, Python 및 Java 애플리케이션에 대한 Azure Monitor OpenTelemetry 사용 시리즈의 Java 앱에서 로깅에 대해 자세히 알아보세요.

문제가 있나요? 문제 해결 섹션을 확인하세요.

7. 리소스 정리

현재 배포 환경에서 모든 Azure 리소스를 삭제하려면 azd down을(를) 실행하고 프롬프트를 따릅니다.

azd down

문제 해결

빌드 단계에서 GitHub Actions 실행이 실패했습니다.

실패한 빌드 단계를 선택하여 실패한 단계를 확인합니다. Maven을 사용한 빌드 단계인 경우 단계를 확장하여 옵션이 사용되는지 -DskipTests 확인합니다. 그렇지 않은 경우 4로 돌아갑니다 . 샘플 코드를 배포 하고 지침에 따라 GitHub 워크플로 파일을 수정합니다.

앱이 시작되지 않았고 로그 스트림에 다음 오류가 표시됩니다. "모델 클래스는 기본 지속성 단위 <기본값> 에 대해 정의되지만 구성된 데이터 원본 <기본값> 을 찾을 수 없습니다. 기본 EntityManagerFactory는 생성되지 않습니다."

앱에서 Azure 데이터베이스에 연결할 수 없기 때문에 이 Quarkus 오류가 발생할 가능성이 높습니다. AZURE_POSTGRESQL_CONNECTIONSTRING 앱 설정이 변경되지 않았는지, application.properties가 앱 설정을 제대로 사용하고 있는지 확인합니다.

앱이 시작되지 않았고 로그 스트림에 "컨테이너에 대한 준비 요청에 대한 응답 대기 중"이 표시됩니다.

애플리케이션은 App Service PORT 환경 변수로 지정된 포트를 수신 대기하도록 구성되지 않았으므로 요청에 응답할 수 없습니다. App Service가 애플리케이션에서 응답을 받지 못하면 애플리케이션을 시작하지 못했다고 가정합니다. 4로 돌아갑니다 . 샘플 코드를 배포 하고 application.properties 가 제대로 구성되었는지 확인합니다.

앱이 작동하지만 오류 로그 "ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource](vert.x-eventloop-thread-0)가 요청을 처리하지 못했습니다. jakarta.ws.rs.NotFoundException: HTTP 404 찾을 수 없음"이 표시됩니다.

클라이언트가 알 수 없는 경로를 요청했음을 나타내는 Vert.x 오류(Quarkus Reactive Architecture 참조)입니다. 최대 절전 모드 데이터베이스 마이그레이션이 발생하기 전에 클라이언트가 REST API를 요청할 때 앱이 처음 시작될 때 발생할 수 있습니다.

App Service에서는 GET에 /robots933456.txt 요청을 보내 앱이 시작되는지를 확인하기 때문에, 모든 앱 시작 시에도 이 오류가 발생합니다.

질문과 대답

이 설정 비용은 얼마인가요?
다른 도구를 사용하여 가상 네트워크 뒤에서 보호되는 PostgreSQL 서버에 연결하려면 어떻게 해야 하나요?
로컬 앱 개발은 GitHub Actions에서 어떻게 작동하나요?
GitHub 워크플로 중에 PostgreSQL로 테스트를 실행하려면 어떻게 하나요?
나는 사용자 할당 ID를 만들 수 있는 권한이 없습니다
내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?

이 설정 비용은 얼마인가요?

리소스 만들기 가격 책정은 다음과 같습니다.

App Service 요금제는 Basic 계층에서 만들어지며 스케일 업 또는 스케일 다운할 수 있습니다. App Service 가격 책정을 참조하세요.
PostgreSQL 유연한 서버는 확장 또는 축소할 수 있는 최소 스토리지 크기로 버스트 가능한 최저 계층 Standard_B1ms에 만들어집니다. Azure Database for PostgreSQL 가격 책정을 참조하세요.
피어링과 같은 추가 기능을 구성하지 않는 한 가상 네트워크에는 요금이 발생하지 않습니다. Azure Virtual Network 가격 책정을 참조하세요.
프라이빗 DNS 영역에는 약간의 요금이 청구됩니다. Azure DNS 가격 책정을 참조하세요.

다른 도구를 사용하여 가상 네트워크 뒤에서 보호되는 PostgreSQL 서버에 연결하려면 어떻게 해야 하나요?

명령줄 도구에서 기본 액세스의 경우 앱의 SSH 터미널에서 psql을 실행할 수 있습니다.
데스크톱 도구에서 연결하려면 컴퓨터가 가상 네트워크 내에 있어야 합니다. 예를 들어 서브넷 중 하나에 연결된 Azure VM이거나 Azure Virtual Network와 사이트 간 VPN 연결이 있는 온-프레미스 네트워크의 컴퓨터일 수 있습니다.
가상 네트워크와 Azure Cloud Shell을 통합할 수도 있습니다.

로컬 앱 개발은 GitHub Actions와 어떻게 작동하나요?

App Service에서 자동 생성된 워크플로 파일을 예로 들면 각 git push는 새 빌드 및 배포 실행을 시작합니다. GitHub 리포지토리의 로컬 클론에서 원하는 업데이트를 GitHub로 푸시합니다. 예를 들면 다음과 같습니다.

git add .
git commit -m "<some-message>"
git push origin main

GitHub 워크플로 중에 PostgreSQL로 테스트를 실행하려면 어떻게 하나요?

기본 Quarkus 샘플 애플리케이션에는 데이터베이스 연결 테스트가 포함됩니다. 연결 오류를 방지하기 위해 -skipTests 속성을 추가했습니다. 원하는 경우 PostgreSQL 서비스 컨테이너에 대해 테스트를 실행할 수 있습니다. 예를 들어 GitHub 포크(.github/workflows/main_cephalin-quarkus.yml)에 자동으로 생성된 워크플로 파일의 내용을 다음과 같이 변경합니다.

다음 코드 조각과 같이 PostgreSQL 컨테이너용 YAML 코드를 build 작업에 추가합니다.

...
jobs:
  build:
    runs-on: ubuntu-latest

    # BEGIN CODE ADDITION
    container: ubuntu
    services:
      # Hostname for the PostgreSQL container
      postgresdb:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_USER: postgres
          POSTGRES_DB: postgres
        # Set health checks to wait until postgres has started
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    # END CODE ADDITION

    steps:
      - uses: actions/checkout@v4
      ...

container: ubuntu는 컨테이너에서 build 작업을 실행하도록 GitHub에 지시합니다. 이렇게 하면 jdbc:postgresql://postgresdb:5432/postgres 개발 환경의 연결 문자열이 워크플로 실행 시 그대로 작동할 수 있습니다. GitHub Actions의 PostgreSQL 연결에 대한 자세한 내용은 Creating PostgreSQL 서비스 컨테이너 만들기를 참조하세요.

Build with Maven 단계에서 -DskipTests를 제거합니다. 예를 들면 다음과 같습니다.

      - name: Build with Maven
        run: mvn clean install -Dquarkus.package.type=uber-jar

사용자 할당 ID를 만들 수 있는 권한이 없습니다.

배포 센터 GitHub Actions 배포 설정을 참조하세요.

내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?

codespace를 만들 때 GitHub Copilot 채팅 보기가 이미 있다는 것을 확인할 수 있습니다. 하지만 GitHub Copilot 계정이 필요합니다(30일 평가판 사용 가능).

GitHub Copilot과 대화할 때 도움이 되는 몇 가지 팁:

단일 채팅 세션에서 질문과 답변은 서로 연관되어 있으며, 질문을 조정하여 원하는 답변을 얻을 수 있습니다.
기본적으로 GitHub Copilot은 리포지토리의 어떤 파일에도 액세스할 수 없습니다. 파일에 대해 질문하려면 먼저 편집기에서 파일을 엽니다.
답변을 준비할 때 GitHub Copilot이 리포지토리의 모든 파일에 액세스할 수 있도록 하려면 질문을 @workspace로 시작합니다. 자세한 내용은 Use the @workspace agent를 참조하세요.
채팅 세션에서 GitHub Copilot은 변경 내용을 제안할 수 있으며(@workspace 사용) 심지어 변경 내용을 적용할 위치까지 제안할 수 있지만 사용자를 대신하여 변경하는 것은 허용되지 않습니다. 제안된 변경 내용을 추가하고 테스트하는 것은 사용자의 몫입니다.

다음 단계

개발자 가이드에서 App Service의 Java 앱을 실행하는 방법에 대해 자세히 알아봅니다.

Azure App Service에서 Java 앱 구성

사용자 지정 도메인 및 인증서를 사용하여 앱을 보호하는 방법을 알아봅니다.

사용자 지정 도메인 및 인증서를 사용하여 보안

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-06-05

자습서: Azure App Service 및 PostgreSQL에 Quarkus 웹앱 배포

필수 조건

끝까지 건너뛰기

1. 샘플 실행

2. App Service 및 PostgreSQL 만들기

3. 보안 연결 비밀

4. 샘플 코드 배포

5. 앱으로 이동

6. 진단 로그 스트림

7. 리소스 정리

2. Azure 리소스 만들기 및 샘플 앱 배포

3. 샘플 코드 수정 및 다시 배포

5. 앱으로 이동

6. 진단 로그 스트림

7. 리소스 정리

문제 해결

빌드 단계에서 GitHub Actions 실행이 실패했습니다.

앱이 시작되지 않았고 로그 스트림에 다음 오류가 표시됩니다. "모델 클래스는 기본 지속성 단위 <기본값> 에 대해 정의되지만 구성된 데이터 원본 <기본값> 을 찾을 수 없습니다. 기본 EntityManagerFactory는 생성되지 않습니다."

앱이 시작되지 않았고 로그 스트림에 "컨테이너에 대한 준비 요청에 대한 응답 대기 중"이 표시됩니다.

앱이 작동하지만 오류 로그 "ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource](vert.x-eventloop-thread-0)가 요청을 처리하지 못했습니다. jakarta.ws.rs.NotFoundException: HTTP 404 찾을 수 없음"이 표시됩니다.

질문과 대답

이 설정 비용은 얼마인가요?

다른 도구를 사용하여 가상 네트워크 뒤에서 보호되는 PostgreSQL 서버에 연결하려면 어떻게 해야 하나요?

로컬 앱 개발은 GitHub Actions와 어떻게 작동하나요?

GitHub 워크플로 중에 PostgreSQL로 테스트를 실행하려면 어떻게 하나요?

사용자 할당 ID를 만들 수 있는 권한이 없습니다.

내 codespace에서 GitHub Copilot으로 무엇을 할 수 있나요?

다음 단계

피드백

추가 리소스