Azure Kubernetes Service 클러스터에서 Quarkus를 사용하여 Java 애플리케이션 배포
이 문서에서는 간단한 CRUD 애플리케이션을 사용하여 AKS(Azure Kubernetes Service)에 Red Hat Quarkus를 신속하게 배포하는 방법을 보여 줍니다. 이 애플리케이션은 JavaScript 프런트 엔드 및 REST 엔드포인트가 있는 "할 일 목록"입니다. Azure Database for PostgreSQL 유연한 서버는 앱에 대한 지속성 계층을 제공합니다. 이 문서에서는 앱을 로컬로 테스트하고 AKS에 배포하는 방법을 보여 줍니다.
필수 조건
- Azure를 구독하고 있지 않다면 시작하기 전에 Azure 체험 계정을 만듭니다.
- Unix와 비슷한 운영 체제가 설치된 로컬 컴퓨터를 준비합니다(예: Ubuntu, macOS 또는 Linux용 Windows 하위 시스템).
- Java SE 구현 버전 17 이상(예: OpenJDK의 Microsoft 빌드)을 설치합니다.
- Maven 버전 3.9.8 이상을 설치합니다.
- 해당 OS용 Docker를 설치합니다.
- jq를 설치합니다.
- cURL을 설치합니다.
- Quarkus CLI 버전 3.12.1 이상을 설치합니다.
- Unix와 유사한 환경을 위한 Azure CLI. 이 문서에는 Azure CLI의 Bash 변형만 필요합니다.
- 이 문서에는 Azure CLI 버전 2.61.0 이상이 필요합니다.
앱 프로젝트 만들기
다음 명령을 사용하여 이 문서의 샘플 Java 프로젝트를 복제합니다. 샘플은 GitHub에 있습니다.
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure
git checkout 2024-12-16
cd aks-quarkus
분리된 HEAD 상태에 있다는 메시지가 표시되면 이 메시지는 무시해도 안전합니다. 이 문서에는 커밋이 필요하지 않으므로 분리된 HEAD 상태가 적절합니다.
Quarkus 앱을 로컬로 테스트
이 섹션의 단계에서는 앱을 로컬로 실행하는 방법을 보여 줍니다.
Quarkus는 개발 및 테스트 모드에서 구성되지 않은 서비스의 자동 프로비전을 지원합니다. Quarkus는 이 기능을 개발 서비스라고 합니다. 데이터베이스 서비스에 연결 같은 Quarkus 기능을 포함한다고 가정해 보겠습니다. 앱을 테스트하려고 하지만 아직 실제 데이터베이스에 대한 연결을 완전히 구성하지 않았습니다. Quarkus는 컨테이너화된 스텁 버전의 관련 서비스를 자동으로 시작하고 애플리케이션을 연결합니다. 자세한 내용은 Quarkus 설명서의 개발 서비스 개요 를 참조하세요.
컨테이너 환경이 실행 중인지 확인하고 다음 명령을 사용하여 Quarkus 개발 모드로 전환합니다.
quarkus dev
quarkus dev 대신 mvn quarkus:dev를 사용하여 Maven에서 동일한 작업을 수행할 수 있습니다.
Quarkus 개발 모드 사용량에 대한 원격 분석을 보낼 것인지 묻는 메시지가 표시될 수 있습니다. 표시되면 원하는 대로 대답합니다.
Quarkus 개발 모드를 사용하면 백그라운드 컴파일을 사용하여 라이브로 다시 로드할 수 있습니다. 앱 소스 코드의 측면을 수정하고 브라우저를 새로 고치면 변경 내용을 볼 수 있습니다. 컴파일 또는 배포에 문제가 있는 경우 오류 페이지에 표시됩니다. Quarkus 개발 모드는 포트 5005에서 디버거를 수신 대기합니다. 실행하기 전에 디버거가 연결되기를 기다리려면 명령줄에서 -Dsuspend를 전달합니다. 디버거를 전혀 사용하지 않으려면 -Ddebug=false를 사용할 수 있습니다.
출력은 다음 예제와 같아야 합니다.
__ ____ __ _____ ___ __ ____ ______
--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
INFO [io.quarkus] (Quarkus Main Thread) quarkus-todo-demo-app-aks 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.2.0.Final) started in 3.377s. Listening on: http://localhost:8080
INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
INFO [io.quarkus] (Quarkus Main Thread) Installed features: [agroal, cdi, hibernate-orm, hibernate-orm-panache, hibernate-validator, jdbc-postgresql, narayana-jta, resteasy-reactive, resteasy-reactive-jackson, smallrye-context-propagation, vertx]
--
Tests paused
Press [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [:] for the terminal, [h] for more options>
Quarkus 개발 모드가 실행 중인 터미널에서 w 키를 누릅니다. w 키는 기본 웹 브라우저를 열고 Todo 애플리케이션을 표시합니다. http://localhost:8080에서 애플리케이션 GUI에 직접 액세스할 수도 있습니다.
할 일 목록에서 몇 가지 할 일 항목을 선택해 보세요. UI는 취소선 텍스트 스타일을 사용하여 선택 영역을 나타냅니다. 다음 스크린샷과 같이 Todo 확인 앱을 입력하고 Enter 키를 눌러 할 일 목록에 새 할 일 항목을 추가할 수도 있습니다.
RESTful API(/api)에 액세스하여 로컬 PostgreSQL 데이터베이스에 저장하는 모든 할 일 항목을 가져옵니다.
curl --verbose http://localhost:8080/api | jq .
출력은 다음 예제와 같아야 합니다.
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /api HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.88.1
> Accept: */*
>
< HTTP/1.1 200 OK
< content-length: 664
< Content-Type: application/json;charset=UTF-8
<
{ [664 bytes data]
100 664 100 664 0 0 13278 0 --:--:-- --:--:-- --:--:-- 15441
* Connection #0 to host localhost left intact
[
{
"id": 1,
"title": "Introduction to Quarkus Todo App",
"completed": false,
"order": 0,
"url": null
},
{
"id": 2,
"title": "Quarkus on Azure App Service",
"completed": false,
"order": 1,
"url": "https://learn.microsoft.com/en-us/azure/developer/java/eclipse-microprofile/deploy-microprofile-quarkus-java-app-with-maven-plugin"
},
{
"id": 3,
"title": "Quarkus on Azure Container Apps",
"completed": false,
"order": 2,
"url": "https://learn.microsoft.com/en-us/training/modules/deploy-java-quarkus-azure-container-app-postgres/"
},
{
"id": 4,
"title": "Quarkus on Azure Functions",
"completed": false,
"order": 3,
"url": "https://learn.microsoft.com/en-us/azure/azure-functions/functions-create-first-quarkus"
},
{
"id": 5,
"title": "Verify Todo apps",
"completed": false,
"order": 5,
"url": null
}
]
q 키를 눌러 Quarkus 개발 모드를 종료합니다.
Quarkus 앱을 실행하는 Azure 리소스 만들기
이 섹션의 단계에서는 Quarkus 샘플 앱을 실행하기 위해 다음 Azure 리소스를 만드는 방법을 보여 줍니다.
- Azure Database for PostgreSQL 유연한 서버
- Azure Container Registry
- AKS(Azure Kubernetes Service)
참고 항목
이 문서에서는 PostgreSQL 인증을 사용하지 않도록 설정하여 보안 모범 사례를 보여 줍니다. Microsoft Entra ID는 서버에 대한 연결을 인증하는 데 사용됩니다. PostgreSQL 인증을 사용하도록 설정해야 하는 경우 빠른 시작을 참조하세요. Azure Database for PostgreSQL - 유연한 서버에서 Java 및 JDBC를 사용하고 암호 탭을 선택합니다.
이러한 리소스 중 일부는 Azure 구독의 범위 내에서 고유한 이름이 있어야 합니다. 이 고유성을 보장하기 위해 ‘이니셜, 시퀀스, 날짜, 접미사’ 패턴을 사용할 수 있습니다. 이 패턴을 적용하려면 이니셜, 일부 시퀀스 번호, 오늘 날짜, 리소스 관련 접미사(예를 들어 “리소스 그룹”을 뜻하는 rg)를 나열하여 리소스의 이름을 지정합니다. 다음 환경 변수는 이 패턴을 사용합니다. 자리 표시자 값을 사용자 고유의 값 UNIQUE_VALUE LOCATION 으로 바꾼 다음 터미널에서 다음 명령을 실행합니다.
export UNIQUE_VALUE=<your unique value, such as ejb010717>
export RESOURCE_GROUP_NAME=${UNIQUE_VALUE}rg
export LOCATION=<your desired Azure region for deploying your resources - for example, northeurope>
export REGISTRY_NAME=${UNIQUE_VALUE}reg
export DB_SERVER_NAME=${UNIQUE_VALUE}db
export DB_NAME=demodb
export CLUSTER_NAME=${UNIQUE_VALUE}aks
export AKS_NS=${UNIQUE_VALUE}ns
Azure Database for PostgreSQL 유연한 서버 만들기
Azure Database for PostgreSQL 유연한 서버는 데이터베이스 관리 기능 및 구성 설정에 대한 보다 세부적인 제어와 유연성을 제공하도록 설계된 완전 관리형 데이터베이스 서비스입니다. 이 섹션에서는 Azure CLI를 사용하여 Azure Database for PostgreSQL 유연한 서버 인스턴스를 만드는 방법을 보여 줍니다.
먼저 다음 명령을 사용하여 데이터베이스 서버 및 기타 리소스를 포함할 리소스 그룹을 만듭니다.
az group create \
--name $RESOURCE_GROUP_NAME \
--location $LOCATION
다음으로, 다음 명령을 사용하여 Azure Database for PostgreSQL 유연한 서버 인스턴스를 만듭니다.
az postgres flexible-server create \
--name $DB_SERVER_NAME \
--database-name $DB_NAME \
--resource-group $RESOURCE_GROUP_NAME \
--location $LOCATION \
--public-access 0.0.0.0 \
--sku-name Standard_B1ms \
--tier Burstable \
--active-directory-auth Enabled \
--yes
서버, 데이터베이스, 관리자 사용자 및 방화벽 규칙을 만드는 데 몇 분 정도 걸립니다. 명령이 성공하면 출력은 다음 예제와 유사합니다.
{
"connectionString": "postgresql://REDACTED@ejb011212qdb.postgres.database.azure.com/demodb?sslmode=require",
"databaseName": "demodb",
"firewallName": "AllowAllAzureServicesAndResourcesWithinAzureIps_2024-12-12_14-30-22",
"host": "ejb011212qdb.postgres.database.azure.com",
"id": "/subscriptions/c7844e91-b11d-4a7f-ac6f-996308fbcdb9/resourceGroups/ejb011211sfi/providers/Microsoft.DBforPostgreSQL/flexibleServers/ejb011212qdb",
"location": "East US 2",
"password": "REDACTED",
"resourceGroup": "ejb011211sfi",
"skuname": "Standard_B1ms",
"username": "sorrycamel2",
"version": "16"
}
Azure Database for PostgreSQL 유연한 서버를 사용하여 로컬로 앱 테스트
이전 섹션에서는 Docker 컨테이너로 프로비전된 PostgreSQL 데이터베이스를 사용하여 개발 모드에서 Quarkus 앱을 로컬로 테스트했습니다. 이제 Azure Database for PostgreSQL 유연한 서버 인스턴스에 대한 연결을 로컬로 테스트합니다.
먼저 다음 명령을 사용하여 현재 로그인한 사용자를 Microsoft Entra Admin으로 Azure Database for PostgreSQL 유연한 서버 인스턴스에 추가합니다.
ENTRA_ADMIN_NAME=$(az account show --query user.name --output tsv)
az postgres flexible-server ad-admin create \
--resource-group $RESOURCE_GROUP_NAME \
--server-name $DB_SERVER_NAME \
--display-name $ENTRA_ADMIN_NAME \
--object-id $(az ad signed-in-user show --query id --output tsv)
성공한 출력은 속성을 "type": "Microsoft.DBforPostgreSQL/flexibleServers/administrators"포함하는 JSON 개체입니다.
다음으로, 다음 단계를 수행하여 Azure Database for PostgreSQL 유연한 서버 인스턴스 방화벽 규칙에 로컬 IP 주소를 추가합니다.
Quarkus 앱을 로컬로 실행하는 컴퓨터의 로컬 IP 주소를 가져옵니다. 예를 들어 공용 IP v4 주소를 얻으려면 방문 https://whatismyipaddress.com 하세요.
이전 단계에서 얻은 로컬 IP 주소를 사용하여 환경 변수를 정의합니다.
export AZ_LOCAL_IP_ADDRESS=<your local IP address>다음 명령을 실행하여 Azure Database for PostgreSQL 유연한 서버 인스턴스 방화벽 규칙에 로컬 IP 주소를 추가합니다.
az postgres flexible-server firewall-rule create \ --resource-group $RESOURCE_GROUP_NAME \ --name $DB_SERVER_NAME \ --rule-name $DB_SERVER_NAME-database-allow-local-ip \ --start-ip-address $AZ_LOCAL_IP_ADDRESS \ --end-ip-address $AZ_LOCAL_IP_ADDRESS
그런 다음 이전 터미널에서 다음 환경 변수를 설정합니다. 이러한 환경 변수는 로컬로 실행되는 Quarkus 앱에서 Azure Database for PostgreSQL 유연한 서버 인스턴스에 연결하는 데 사용됩니다.
export AZURE_POSTGRESQL_HOST=${DB_SERVER_NAME}.postgres.database.azure.com
export AZURE_POSTGRESQL_PORT=5432
export AZURE_POSTGRESQL_DATABASE=${DB_NAME}
export AZURE_POSTGRESQL_USERNAME=${ENTRA_ADMIN_NAME}
참고 항목
환경 변수AZURE_POSTGRESQL_HOSTAZURE_POSTGRESQL_PORTAZURE_POSTGRESQL_DATABASE의 값 , 및 AZURE_POSTGRESQL_USERNAME 이전 섹션에서 도입된 src/main/resources/application.properties 파일에 정의된 데이터베이스 구성 속성에서 읽습니다. 이러한 값은 이 문서의 뒷부분에 있는 AKS 클러스터에 Quarkus 앱을 배포할 때 Service Connector 암호 없는 확장을 사용하여 런타임에 앱에 자동으로 삽입됩니다.
이제 Quarkus 앱을 로컬로 실행하여 Azure Database for PostgreSQL 유연한 서버 인스턴스에 대한 연결을 테스트합니다. 다음 명령을 사용하여 프로덕션 모드에서 앱을 시작합니다.
quarkus build
java -jar target/quarkus-app/quarkus-run.jar
참고 항목
앱이 유사한 ERROR [org.hib.eng.jdb.spi.SqlExceptionHelper] (JPA Startup Thread) Acquisition timeout while waiting for new connection오류 메시지로 시작하지 못하는 경우 로컬 컴퓨터의 네트워크 설정으로 인해 앱이 시작되지 않을 가능성이 큽니다. Azure Portal에서 현재 클라이언트 IP 주소 추가를 다시 선택합니다. 자세한 내용은 Azure Portal을 사용하여 Azure Database for PostgreSQL - 유연한 서버에 대한 방화벽 규칙 만들기 및 관리에서 서버를 만든 후 방화벽 규칙 만들기 섹션을 참조하세요. 그런 다음, 앱을 다시 실행합니다.
새 웹 브라우저를 열어 http://localhost:8080 Todo 애플리케이션에 액세스합니다. 개발 모드에서 로컬로 앱을 실행했을 때 본 것과 비슷한 Todo 앱이 표시됩니다.
Azure Container Registry 인스턴스 만들기
Quarkus는 클라우드 네이티브 기술이므로 Kubernetes에서 실행되는 컨테이너 만들기를 기본적으로 지원합니다. Kubernetes는 실행할 컨테이너 이미지를 찾는 컨테이너 레지스트리가 반드시 있어야 합니다. AKS는 Azure Container Registry를 기본적으로 지원합니다.
az acr create 명령을 사용하여 컨테이너 레지스트리 인스턴스를 만듭니다. 다음 예제에서는 환경 변수 ${REGISTRY_NAME}의 값으로 명명된 컨테이너 레지스트리 인스턴스를 만듭니다.
az acr create \
--resource-group $RESOURCE_GROUP_NAME \
--location ${LOCATION} \
--name $REGISTRY_NAME \
--sku Basic
잠시 후 다음 줄을 포함하는 JSON 출력이 표시됩니다.
"provisioningState": "Succeeded",
"publicNetworkAccess": "Enabled",
"resourceGroup": "<YOUR_RESOURCE_GROUP>",
다음 명령을 사용하여 Container Registry 인스턴스에 대한 로그인 서버를 가져옵니다.
export LOGIN_SERVER=$(az acr show \
--name $REGISTRY_NAME \
--query 'loginServer' \
--output tsv)
echo $LOGIN_SERVER
Docker를 컨테이너 레지스트리 인스턴스에 연결
컨테이너 레지스트리 인스턴스에 로그인합니다. 로그인하면 이미지를 푸시할 수 있습니다. 다음 명령을 사용하여 레지스트리에 로그인합니다.
az acr login --name $REGISTRY_NAME
컨테이너 레지스트리 인스턴스에 성공적으로 로그인한 경우 명령 출력의 끝에 표시됩니다 Login Succeeded .
AKS 클러스터 만들기
az aks create 명령을 사용하여 AKS 클러스터를 만듭니다. 다음 예제는 환경 변수 ${CLUSTER_NAME} 값으로 명명된 클러스터를 만듭니다. 클러스터는 이전 단계에서 만든 컨테이너 레지스트리 인스턴스에 연결됩니다. 이 명령을 완료하는 데 몇 분 정도 걸립니다. 클러스터는 관리 ID를 사용하도록 설정하여 시작됩니다. 이 단계는 암호 없는 데이터베이스 연결에 필요합니다.
az aks create \
--resource-group $RESOURCE_GROUP_NAME \
--name $CLUSTER_NAME \
--attach-acr $REGISTRY_NAME \
--node-count 1 \
--generate-ssh-keys \
--enable-managed-identity
몇 분 후 명령이 완료되면 다음 출력을 포함하여 클러스터에 대한 JSON 형식 정보가 반환됩니다.
"nodeResourceGroup": "MC_<your resource_group_name>_<your cluster name>_<your region>",
"privateFqdn": null,
"provisioningState": "Succeeded",
"resourceGroup": "<your resource group name>",
AKS 클러스터에 연결
Kubernetes 클러스터를 관리하려면 Kubernetes 명령줄 클라이언트 kubectl을 사용합니다. kubectl을 로컬로 설치하려면 다음 예제와 같이 az aks install-cli 명령을 사용합니다.
az aks install-cli
kubectl에 대한 자세한 내용은 Kubernetes 설명서의 명령줄 도구(kubectl)를 참조하세요.
Kubernetes 클러스터에 연결하도록 kubectl을 구성하려면 다음 예제에 나온 것처럼 az aks get-credentials 명령을 사용합니다. 이 명령은 자격 증명을 다운로드하고 Kubernetes CLI가 해당 자격 증명을 사용하도록 구성합니다.
az aks get-credentials \
--resource-group $RESOURCE_GROUP_NAME \
--name $CLUSTER_NAME \
--overwrite-existing \
--admin
성공하면 출력에 다음 예제와 비슷한 텍스트가 포함됩니다.
Merged "ejb010718aks-admin" as current context in /Users/edburns/.kube/config
k를 kubectl의 별칭으로 지정하는 것이 유용할 수 있습니다. 이 경우 다음 명령을 사용하세요.
alias k=kubectl
클러스터에 대한 연결을 확인하려면 다음 예제에 나온 것처럼 kubectl get 명령을 사용하여 클러스터 노드 목록을 반환합니다.
kubectl get nodes
다음 예제 출력은 이전 단계에서 만든 단일 노드를 보여줍니다. 노드 상태가 준비인지 확인합니다.
NAME STATUS ROLES AGE VERSION
aks-nodepool1-xxxxxxxx-yyyyyyyyyy Ready agent 76s v1.28.9
AKS에 새 네임스페이스 만들기
다음 명령을 사용하여 Kubernetes 서비스에 Quarkus 앱의 새 네임스페이스를 만듭니다.
kubectl create namespace ${AKS_NS}
출력은 다음 예제와 같아야 합니다.
namespace/<your namespace> created
서비스 커넥터를 사용하여 AKS에서 서비스 연결 만들기
이 섹션에서는 서비스 커넥터와 함께 Microsoft Entra 워크로드 ID 사용하여 AKS 클러스터와 Azure Database for PostgreSQL 유연한 서버 간에 서비스 연결을 만듭니다. 이 연결을 통해 AKS 클러스터는 SQL 인증을 사용하지 않고 Azure Database for PostgreSQL 유연한 서버에 액세스할 수 있습니다.
다음 명령을 실행하여 Service Connector에서 Microsoft Entra 워크로드 ID 사용하여 AKS 클러스터와 PostgreSQL 데이터베이스 간에 연결을 만듭니다.
# Register the Service Connector and Kubernetes Configuration resource providers
az provider register --namespace Microsoft.ServiceLinker --wait
az provider register --namespace Microsoft.KubernetesConfiguration --wait
# Install the Service Connector passwordless extension
az extension add --name serviceconnector-passwordless --upgrade --allow-preview true
# Retrieve the AKS cluster and Azure SQL Server resource IDs
export AKS_CLUSTER_RESOURCE_ID=$(az aks show \
--resource-group $RESOURCE_GROUP_NAME \
--name $CLUSTER_NAME \
--query id \
--output tsv)
export AZURE_POSTGRESQL_RESOURCE_ID=$(az postgres flexible-server show \
--resource-group $RESOURCE_GROUP_NAME \
--name $DB_SERVER_NAME \
--query id \
--output tsv)
# Create a user-assigned managed identity used for workload identity
export USER_ASSIGNED_IDENTITY_NAME=workload-identity-uami
az identity create \
--resource-group ${RESOURCE_GROUP_NAME} \
--name ${USER_ASSIGNED_IDENTITY_NAME}
# Retrieve the user-assigned managed identity resource ID
export UAMI_RESOURCE_ID=$(az identity show \
--resource-group ${RESOURCE_GROUP_NAME} \
--name ${USER_ASSIGNED_IDENTITY_NAME} \
--query id \
--output tsv)
# Create a service connection between your AKS cluster and your PostgreSQL database using Microsoft Entra Workload ID
az aks connection create postgres-flexible \
--connection akspostgresconn \
--kube-namespace $AKS_NS \
--source-id $AKS_CLUSTER_RESOURCE_ID \
--target-id $AZURE_POSTGRESQL_RESOURCE_ID/databases/$DB_NAME \
--workload-identity $UAMI_RESOURCE_ID
이전 단계의 최종 명령에서 출력에 다음 JSON이 있는 것은 서비스 커넥터를 성공적으로 설치했음을 나타냅니다.
"name": "akspostgresconn",
"provisioningState": "Succeeded",
참고 항목
사용자 이름/암호 인증을 사용하지 않고 Azure Database for PostgreSQL 유연한 서버에 안전하게 액세스하기 위해 Microsoft Entra 워크로드 ID 사용하는 것이 좋습니다. 사용자 이름/암호 인증을 사용해야 하는 경우 이 섹션의 이전 단계를 무시하고 사용자 이름과 암호를 사용하여 데이터베이스에 연결합니다.
서비스 커넥터에서 만든 서비스 계정 및 비밀 가져오기
Azure Database for PostgreSQL 유연한 서버에 인증하려면 서비스 커넥터에서 만든 서비스 계정 및 Kubernetes 비밀을 가져와야 합니다. 자습서의 컨테이너 업데이트 섹션에 있는 지침을 따릅니다. AKS 앱을 Azure SQL Database에 연결합니다. 제공된 YAML 샘플 코드 조각을 사용하여 배포를 직접 만들고 다음 단계를 사용합니다.
샘플 Kubernetes 배포 YAML의 강조 표시된 섹션에서 다음 예제와 같이
<service-account-name><secret-name>표시된 값을serviceAccountName복사합니다secretRef.name.serviceAccountName: <service-account-name> containers: - name: raw-linux envFrom: - secretRef: name: <secret-name>이러한 값은 다음 섹션에서 AkS 클러스터에 Quarkus 애플리케이션을 배포하는 데 사용됩니다.
클라우드 네이티브 구성 사용자 지정
클라우드 네이티브 기술인 Quarkus는 표준 Kubernetes, Red Hat OpenShift, Knative의 리소스를 자동으로 구성하는 기능을 제공합니다. 자세한 내용은 Quarkus Kubernetes 가이드, Quarkus OpenShift 가이드 및 Quarkus Knative 가이드를 참조하세요. 개발자는 생성된 매니페스트를 적용하여 대상 Kubernetes 클러스터에 애플리케이션을 배포할 수 있습니다.
적절한 Kubernetes 리소스를 생성하려면 다음 명령을 사용하여 로컬 터미널에서 quarkus-kubernetes 및 container-image-jib 확장을 추가합니다.
quarkus ext add kubernetes container-image-jib
Quarkus는 POM을 수정하여 이러한 확장이 <dependencies>로 나열되도록 합니다. JBang이라는 항목을 설치하라는 메시지가 표시되면 ‘예’ 라고 대답하고 설치를 허용합니다.
출력은 다음 예제와 같아야 합니다.
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been installed
[SUCCESS] ✅ Extension io.quarkus:quarkus-container-image-jib has been installed
확장이 추가되었는지 확인하려면 git diff를 실행하고 출력을 검사할 수 있습니다.
클라우드 네이티브 기술인 Quarkus는 구성 프로필의 개념을 지원합니다. Quarkus에는 다음과 같은 세 가지 기본 제공 프로필이 있습니다.
dev- 개발 모드에 있을 때 활성화됨test- 테스트를 실행할 때 활성화됨prod- 개발 또는 테스트 모드에서 실행하지 않을 때 기본 프로필
Quarkus는 필요에 따라 임의의 수의 명명된 프로필을 지원합니다.
이 섹션의 나머지 단계에서는 src/main/resources/application.properties 파일의 값을 사용자 지정하도록 안내합니다.
prod. 접두사는 prod 프로필에서 실행할 때 이러한 속성이 활성 상태임을 나타냅니다. 구성 프로필에 대한 자세한 내용은 Quarkus 설명서를 참조하세요.
데이터베이스 구성
다음 데이터베이스 구성 변수를 검사합니다. 데이터베이스 연결 관련 속성 %prod.quarkus.datasource.jdbc.url 및 %prod.quarkus.datasource.username 환경 변수AZURE_POSTGRESQL_HOSTAZURE_POSTGRESQL_PORTAZURE_POSTGRESQL_DATABASE, 및 AZURE_POSTGRESQL_USERNAME각각에서 값을 읽습니다. 이러한 환경 변수는 데이터베이스 연결 정보를 저장하는 비밀 값에 매핑됩니다. 보안상의 이유로 이 문서의 다른 위치에 표시된 것처럼 서비스 커넥터 암호 없는 확장을 사용하여 자동으로 생성됩니다.
# Database configurations
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://${AZURE_POSTGRESQL_HOST}:${AZURE_POSTGRESQL_PORT}/${AZURE_POSTGRESQL_DATABASE}?\
authenticationPluginClassName=com.azure.identity.extensions.jdbc.postgresql.AzurePostgresqlAuthenticationPlugin\
&sslmode=require
%prod.quarkus.datasource.username=${AZURE_POSTGRESQL_USERNAME}
%prod.quarkus.datasource.jdbc.acquisition-timeout=10
%prod.quarkus.hibernate-orm.database.generation=drop-and-create
%prod.quarkus.hibernate-orm.sql-load-script=import.sql
Kubernetes 구성
다음 Kubernetes 구성 변수를 검사합니다. service-type 는 외부에서 앱에 액세스하도록 load-balancer 설정되어 있습니다. 이전 섹션에서 복사한 실제 값 <service-account-name> <secret-name> 의 값 및 값을 바꿉합니다.
# Kubernetes configurations
%prod.quarkus.kubernetes.deployment-target=kubernetes
%prod.quarkus.kubernetes.service-type=load-balancer
%prod.quarkus.kubernetes.labels."azure.workload.identity/use"=true
%prod.quarkus.kubernetes.service-account=<service-account-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_CLIENT_ID.from-secret=<secret-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_CLIENT_ID.with-key=AZURE_POSTGRESQL_CLIENTID
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_HOST.from-secret=<secret-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_HOST.with-key=AZURE_POSTGRESQL_HOST
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_PORT.from-secret=<secret-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_PORT.with-key=AZURE_POSTGRESQL_PORT
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_DATABASE.from-secret=<secret-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_DATABASE.with-key=AZURE_POSTGRESQL_DATABASE
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_USERNAME.from-secret=<secret-name>
%prod.quarkus.kubernetes.env.mapping.AZURE_POSTGRESQL_USERNAME.with-key=AZURE_POSTGRESQL_USERNAME
다른 Kubernetes 구성은 Quarkus 애플리케이션의 환경 변수에 대한 비밀 값의 매핑을 지정합니다. <secret-name> 비밀에는 데이터베이스 연결 정보가 포함됩니다. 비밀의 키AZURE_POSTGRESQL_HOST, , AZURE_POSTGRESQL_PORT및 AZURE_POSTGRESQL_USERNAME AZURE_POSTGRESQL_DATABASE키는 AZURE_POSTGRESQL_CLIENTID각각 , AZURE_POSTGRESQL_HOST, AZURE_POSTGRESQL_PORTAZURE_POSTGRESQL_DATABASE및 AZURE_POSTGRESQL_USERNAME 환경 변수에 매핑AZURE_CLIENT_ID됩니다.
kubectl을 사용하여 비밀을 직접 검사하려면 다음 예제와 유사한 명령을 사용합니다.
kubectl -n ${AKS_NS} get secret <secret-name> -o jsonpath="{.data.AZURE_POSTGRESQL_USERNAME}" | base64 --decode
컨테이너 이미지 구성
클라우드 네이티브 기술인 Quarkus는 Docker와 호환되는 OCI 컨테이너 이미지 생성을 지원합니다. 값을 환경 변수의 <LOGIN_SERVER_VALUE> 실제 값으로 ${LOGIN_SERVER} 바꿉습니다.
# Container Image Build
%prod.quarkus.container-image.build=true
%prod.quarkus.container-image.image=<LOGIN_SERVER_VALUE>/todo-quarkus-aks:1.0
최종 확인으로 application.properties에서 필요한 모든 대체를 완료하는 경우 문자가 발생하지 < 않아야 합니다. 있는 경우 필요한 모든 대체를 완료했는지 다시 확인합니다.
컨테이너 이미지를 빌드하고 컨테이너 레지스트리에 푸시
이제 다음 명령을 사용하여 애플리케이션 자체를 빌드합니다. 이 명령은 Kubernetes 및 Jib 확장을 사용하여 컨테이너 이미지를 빌드합니다.
quarkus build --no-tests
출력은 BUILD SUCCESS로 끝나야 합니다. Kubernetes 매니페스트 파일은 다음 예제에 나온 것처럼 target/kubernetes에 생성됩니다.
tree target/kubernetes
target/kubernetes
├── kubernetes.json
└── kubernetes.yml
0 directories, 2 files
CLI(명령줄)를 사용하여 docker 컨테이너 이미지가 생성되는지 여부를 확인할 수 있습니다. 출력은 다음 예제와 유사합니다.
docker images | grep todo-quarkus-aks
<LOGIN_SERVER_VALUE>/todo-quarkus-aks 1.0 b13c389896b7 18 minutes ago 422MB
다음 명령을 사용하여 컨테이너 이미지를 컨테이너 레지스트리에 푸시합니다.
export TODO_QUARKUS_TAG=$(docker images | grep todo-quarkus-aks | head -n1 | cut -d " " -f1)
echo ${TODO_QUARKUS_TAG}
docker push ${TODO_QUARKUS_TAG}:1.0
출력은 다음 예시와 유사하게 표시됩니다.
The push refers to repository [<LOGIN_SERVER_VALUE>/todo-quarkus-aks]
dfd615499b3a: Pushed
56f5cf1aa271: Pushed
4218d39b228e: Pushed
b0538737ed64: Pushed
d13845d85ee5: Pushed
60609ec85f86: Pushed
1.0: digest: sha256:0ffd70d6d5bb3a4621c030df0d22cf1aa13990ca1880664d08967bd5bab1f2b6 size: 1995
이제 컨테이너 레지스트리에 앱을 푸시했으므로 AKS에 앱을 실행하도록 지시할 수 있습니다.
AKS에 Quarkus 앱 배포
이 섹션의 단계에서는 만든 Azure 리소스에서 Quarkus 샘플 앱을 실행하는 방법을 보여 줍니다.
kubectl apply를 사용하여 AKS에 Quarkus 앱 배포
다음 예제에 나온 것처럼 명령줄에서 kubectl을 사용하여 Kubernetes 리소스를 배포합니다.
kubectl apply -f target/kubernetes/kubernetes.yml -n ${AKS_NS}
출력은 다음 예제와 같아야 합니다.
service/quarkus-todo-demo-app-aks created
deployment.apps/quarkus-todo-demo-app-aks created
다음 명령을 사용하여 앱이 실행 중인지 확인합니다.
kubectl -n $AKS_NS get pods
STATUS 필드의 값에 Running이 아닌 값이 표시되면 계속하기 전에 문제를 해결합니다. 다음 명령을 사용하여 Pod 로그를 검사하는 데 도움이 될 수 있습니다.
kubectl -n $AKS_NS logs $(kubectl -n $AKS_NS get pods | grep quarkus-todo-demo-app-aks | cut -d " " -f1)
다음 명령을 사용하여 Todo 애플리케이션에 액세스하려면 EXTERNAL-IP를 가져옵니다.
kubectl get svc -n ${AKS_NS}
출력은 다음 예제와 같아야 합니다.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
quarkus-todo-demo-app-aks LoadBalancer 10.0.236.101 20.12.126.200 80:30963/TCP 37s
다음 명령을 사용하여 EXTERNAL-IP 값을 환경 변수에 정규화된 URL로 저장할 수 있습니다.
export QUARKUS_URL=http://$(kubectl get svc -n ${AKS_NS} | grep quarkus-todo-demo-app-aks | cut -d " " -f10)
echo $QUARKUS_URL
새 웹 브라우저를 ${QUARKUS_URL} 값으로 엽니다. 그런 다음 텍스트가 Deployed the Todo app to AKS인 새 할 일 항목을 추가합니다. 또한 Introduction to Quarkus Todo App 항목을 완료로 선택합니다.
다음 예제와 같이 RESTful API(/api)에 액세스하여 Azure PostgreSQL 데이터베이스에 저장된 모든 할 일 항목을 가져옵니다.
curl --verbose ${QUARKUS_URL}/api | jq .
출력은 다음 예제와 같아야 합니다.
* Connected to 20.237.68.225 (20.237.68.225) port 80 (#0)
> GET /api HTTP/1.1
> Host: 20.237.68.225
> User-Agent: curl/7.88.1
> Accept: */*
>
< HTTP/1.1 200 OK
< content-length: 828
< Content-Type: application/json;charset=UTF-8
<
[
{
"id": 2,
"title": "Quarkus on Azure App Service",
"completed": false,
"order": 1,
"url": "https://learn.microsoft.com/en-us/azure/developer/java/eclipse-microprofile/deploy-microprofile-quarkus-java-app-with-maven-plugin"
},
{
"id": 3,
"title": "Quarkus on Azure Container Apps",
"completed": false,
"order": 2,
"url": "https://learn.microsoft.com/en-us/training/modules/deploy-java-quarkus-azure-container-app-postgres/"
},
{
"id": 4,
"title": "Quarkus on Azure Functions",
"completed": false,
"order": 3,
"url": "https://learn.microsoft.com/en-us/azure/azure-functions/functions-create-first-quarkus"
},
{
"id": 5,
"title": "Deployed the Todo app to AKS",
"completed": false,
"order": 5,
"url": null
},
{
"id": 1,
"title": "Introduction to Quarkus Todo App",
"completed": true,
"order": 0,
"url": null
}
]
데이터베이스가 업데이트되었는지 확인
다음 명령을 실행하여 데이터베이스가 올바르게 업데이트되었는지 확인합니다.
ACCESS_TOKEN=$(az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken)
az postgres flexible-server execute \
--admin-user $ENTRA_ADMIN_NAME \
--admin-password $ACCESS_TOKEN \
--name $DB_SERVER_NAME \
--database-name $DB_NAME \
--querytext "select * from todo;"
확장을 설치하라는 메시지가 표시되면 Y에 응답합니다.
출력은 다음 예제와 유사해야 하며 Todo 앱 GUI에 동일한 항목과 이전 명령의 curl 출력을 포함해야 합니다.
Successfully connected to <DB_SERVER_NAME>.
Ran Database Query: 'select * from todo;'
Retrieving first 30 rows of query output, if applicable.
Closed the connection to <DB_SERVER_NAME>
[
{
"completed": false,
"id": 2,
"ordering": 1,
"title": "Quarkus on Azure App Service",
"url": "https://learn.microsoft.com/en-us/azure/developer/java/eclipse-microprofile/deploy-microprofile-quarkus-java-app-with-maven-plugin"
},
{
"completed": false,
"id": 3,
"ordering": 2,
"title": "Quarkus on Azure Container Apps",
"url": "https://learn.microsoft.com/en-us/training/modules/deploy-java-quarkus-azure-container-app-postgres/"
},
{
"completed": false,
"id": 4,
"ordering": 3,
"title": "Quarkus on Azure Functions",
"url": "https://learn.microsoft.com/en-us/azure/azure-functions/functions-create-first-quarkus"
},
{
"completed": false,
"id": 5,
"ordering": 5,
"title": "Deployed the Todo app to AKS",
"url": null
},
{
"completed": true,
"id": 1,
"ordering": 0,
"title": "Introduction to Quarkus Todo App",
"url": null
}
]
완료되면 다음 명령을 사용하여 로컬 IP 주소가 Azure Database for PostgreSQL 유연한 서버 인스턴스에 액세스할 수 있도록 하는 방화벽 규칙을 삭제합니다.
az postgres flexible-server firewall-rule delete \
--resource-group $RESOURCE_GROUP_NAME \
--name $DB_SERVER_NAME \
--rule-name $DB_SERVER_NAME-database-allow-local-ip \
--yes
리소스 정리
Azure 요금을 방지하려면 불필요한 리소스를 정리해야 합니다. 클러스터가 더 이상 필요하지 않은 경우 az group delete 명령을 사용하여 리소스 그룹, 컨테이너 서비스, 컨테이너 레지스트리 및 모든 관련 리소스를 제거합니다.
git reset --hard
docker rmi ${TODO_QUARKUS_TAG}:1.0
docker rmi postgres
az identity delete --ids ${UAMI_RESOURCE_ID}
az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait
컨테이너 이미지를 postgres 삭제하고 testcontainers Quarkus 개발 모드에서 생성하는 데 사용할 docker rmi 수도 있습니다.
다음 단계
Azure Kubernetes Service