빠른 시작: Azure Kubernetes Service에서 Azure App Configuration 사용

Kubernetes에서는 ConfigMaps의 구성을 사용하도록 Pod를 설정합니다. 그러면 컨테이너 이미지에서 구성을 분리하여 애플리케이션을 쉽게 이식할 수 있습니다. Azure App Configuration Kubernetes Provider는 Azure App Configuration의 키-값과 Key Vault 참조에서 ConfigMaps 및 비밀을 생성할 수 있습니다. 이렇게 하면 애플리케이션 코드를 변경하지 않고도 Azure App Configuration을 중앙 집중식 스토리지 및 구성 관리에 활용할 수 있습니다.

ConfigMap은 환경 변수 또는 탑재된 파일로 사용할 수 있습니다. 이 빠른 시작에서는 Azure Kubernetes Service 워크로드에 Azure App Configuration Kubernetes Provider를 통합하고 JSON 파일의 구성을 사용하는 간단한 ASP.NET Core 앱을 실행합니다.

팁

Azure App Configuration에 액세스하려면 Kubernetes에서 호스트되는 워크로드에 대한 옵션을 참조하세요.

참고 항목

이 빠른 시작에서는 Azure App Configuration Kubernetes 공급자를 설정하는 과정을 안내합니다. 선택적으로 azure-appconfig-aks 템플릿과 함께 다음 Azure Developer CLI 명령을 사용하여 Azure 리소스를 프로비전하고 이 빠른 시작에서 사용되는 샘플 애플리케이션을 배포할 수 있습니다. 이 템플릿에 대한 자세한 내용을 보려면 GitHub의 azure-appconfig-aks 리포지토리를 참조하세요.

azd init -t azure-appconfig-aks
azd up

필수 조건

• App Configuration 저장소. 저장소를 만듭니다.
• Azure Container Registry. 레지스트리를 만듭니다.
• Azure Container Registry에서 이미지를 끌어올 수 있는 권한이 부여된 AKS(Azure Kubernetes Service) 클러스터. AKS 클러스터 만들기.
• .NET SDK 6.0 이상
• Azure CLI
• Docker Desktop
• helm
• kubectl

AKS에서 실행되는 애플리케이션 만들기

이 섹션에서는 AKS(Azure Kubernetes Service)에서 실행되는 간단한 ASP.NET Core 웹 애플리케이션을 만듭니다. 이 애플리케이션은 로컬 JSON 파일에서 구성을 읽습니다. 다음 섹션에서는 애플리케이션 코드를 변경하지 않고 Azure App Configuration의 구성을 사용하도록 이 애플리케이션을 설정합니다. 파일에서 구성을 읽는 AKS 애플리케이션이 이미 있는 경우 이 섹션을 건너뛰고 App Configuration Kubernetes Provider 사용으로 건너뛰세요. 공급자가 생성한 구성 파일이 애플리케이션에서 사용하는 파일 경로와 일치하는지만 확인하면 됩니다.

애플리케이션 만들기

1. .NET CLI(명령줄 인터페이스)에서 다음 명령을 실행하여 새 MyWebApp 디렉터리에 새 ASP.NET Core 웹앱 프로젝트를 만듭니다.

   dotnet new webapp --output MyWebApp --framework net6.0
   

2. Pages 디렉터리에서 Index.cshtml 파일을 열고 콘텐츠를 다음 코드로 업데이트합니다.

   @page
   @model IndexModel
   @using Microsoft.Extensions.Configuration
   @inject IConfiguration Configuration
   @{
       ViewData["Title"] = "Home page";
   }
   
   <style>
       h1 {
           color: @Configuration["Settings:FontColor"];
       }
   </style>
   
   <div class="text-center">
       <h1>@Configuration["Settings:Message"]</h1>
   </div>
   

3. 프로젝트 루트에 config 디렉터리를 만들고 다음 콘텐츠와 함께 mysettings.json 파일을 추가합니다.

   {
     "Settings": {
       "FontColor": "Black",
       "Message": "Message from the local configuration"
     }
   }
   

4. Program.cs 파일을 열고 AddJsonFile 메서드를 호출하여 JSON 파일을 구성 원본에 추가합니다.

   // Existing code in Program.cs
   // ... ...
   
   // Add a JSON configuration source 
   builder.Configuration.AddJsonFile("config/mysettings.json", reloadOnChange: true, optional: false);
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

애플리케이션 컨테이너화

1. dotnet publish 명령을 실행하여 릴리스 모드에서 앱을 빌드하고 게시된 디렉터리에 자산을 만듭니다.

   dotnet publish -c Release -o published
   

2. 프로젝트 디렉터리의 루트에 Dockerfile 파일을 만들고, 텍스트 편집기에서 이 파일을 열고, 다음 콘텐츠를 입력합니다. Dockerfile은 확장명이 없고 컨테이너 이미지를 만드는 데 사용되는 텍스트 파일입니다.

   FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
   WORKDIR /app
   COPY published/ ./
   ENTRYPOINT ["dotnet", "MyWebApp.dll"]
   

3. 다음 명령을 실행하여 aspnetapp이라는 컨테이너 이미지를 빌드합니다.

   docker build --tag aspnetapp .
   

Azure Container Registry로 이미지 푸시

1. az acr login 명령을 실행하여 컨테이너 레지스트리에 로그인합니다. 다음 예제에서는 myregistry라는 레지스트리에 로그인합니다. 레지스트리 이름을 해당하는 이름으로 바꿉니다.

   az acr login --name myregistry
   

   로그인에 성공하면 이 명령에서 Login Succeeded를 반환합니다.

2. Docker 태그를 사용하여 aspnetapp 이미지에 대한 myregistry.azurecr.io/aspnetapp:v1 태그를 만듭니다.

   docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
   

   팁

   기존 Docker 이미지 및 태그 목록을 검토하려면 docker image ls 명령을 실행합니다. 이 시나리오에서는 최소한 두 개의 이미지(aspnetapp 및 myregistry.azurecr.io/aspnetapp)가 표시됩니다.

3. docker push 명령을 사용하여 컨테이너 레지스트리에 이미지를 푸시합니다. 예를 들어 다음 명령은 myregistry 레지스트리에 있는 v1 태그가 달린 aspnetapp이라는 리포지토리에 이미지를 푸시합니다.

   docker push myregistry.azurecr.io/aspnetapp:v1
   

애플리케이션 배포

1. 프로젝트의 루트 디렉터리에 Deployment 디렉터리를 만듭니다.

2. 아래와 같이 deployment.yaml 파일을 Deployment 디렉터리에 추가하여 배포를 만듭니다. template.spec.containers.image 값을 이전 단계에서 만든 이미지로 바꿉니다.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: aspnetapp-demo
     labels:
       app: aspnetapp-demo
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: aspnetapp-demo
     template:
       metadata:
         labels:
           app: aspnetapp-demo
       spec:
         containers:
         - name: aspnetapp
           image: myregistry.azurecr.io/aspnetapp:v1
           ports:
           - containerPort: 80
   

3. 아래와 같이 service.yaml 파일을 Deployment 디렉터리에 추가하여 LoadBalancer 서비스를 만듭니다.

   apiVersion: v1
   kind: Service
   metadata:
     name: aspnetapp-demo-service
   spec:
     type: LoadBalancer
     ports:
     - port: 80
     selector:
       app: aspnetapp-demo
   

4. 다음 명령을 실행하여 AKS 클러스터에 애플리케이션을 배포합니다.

   kubectl create namespace appconfig-demo
   kubectl apply -f ./Deployment -n appconfig-demo
   

5. 다음 명령을 실행하고 LoadBalancer 서비스에서 노출하는 외부 IP 주소를 가져옵니다.

   kubectl get service aspnetapp-demo-service -n appconfig-demo
   

6. 브라우저 창을 열고, 이전 단계에서 얻은 IP 주소로 이동합니다. 웹 페이지는 다음과 같습니다.

   

App Configuration Kubernetes Provider 사용

AKS에서 실행되는 애플리케이션이 생겼으므로, kubernetes 컨트롤러로 실행되는 AKS 클러스터에 App Configuration Kubernetes Provider를 배포합니다. 이 공급자는 App Configuration 저장소에서 데이터를 검색하고, 데이터 볼륨에 탑재된 JSON 파일로 사용할 수 있는 ConfigMap을 만듭니다.

Azure App Configuration 저장소 설정

App Configuration 저장소에 다음 키-값을 추가하고 레이블 및 콘텐츠 형식은 기본값으로 둡니다. Azure Portal 또는 CLI를 사용하여 저장소에 키-값을 추가하는 방법에 대한 자세한 내용은 키-값 만들기로 이동합니다.

Key	값
Settings:FontColor	녹색
Settings:Message	Hello from Azure App Configuration

App Configuration Kubernetes Provider 설정

1. AKS 클러스터에 대한 액세스 자격 증명을 얻으려면 다음 명령을 실행합니다. name 및 resource-group 매개 변수의 값을 AKS 인스턴스로 바꿉니다.

   az aks get-credentials --name <your-aks-instance-name> --resource-group <your-aks-resource-group>
   

2. helm을 사용하여 AKS 클러스터에 Azure App Configuration Kubernetes Provider를 설치합니다.

   helm install azureappconfiguration.kubernetesprovider \
        oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
        --namespace azappconfig-system \
        --create-namespace
   

   팁

   App Configuration Kubernetes 공급자는 AKS 확장으로도 사용할 수 있습니다. 이 통합을 통해 Azure CLI, ARM 템플릿 또는 Bicep 템플릿을 통해 원활한 설치 및 관리가 가능합니다. AKS 확장을 활용하면 자동 부/패치 버전 업데이트가 쉬워져 시스템이 항상 최신 상태로 유지됩니다. 자세한 설치 지침은 Azure Kubernetes Service용 Azure App Configuration 확장을 참조하세요.

3. 아래와 같이 appConfigurationProvider.yaml 파일을 Deployment 디렉터리에 추가하여 AzureAppConfigurationProvider 리소스를 만듭니다. AzureAppConfigurationProvider는 Azure App Configuration 저장소에서 다운로드할 데이터를 정의하고 ConfigMap을 만드는 사용자 지정 리소스입니다.

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     endpoint: <your-app-configuration-store-endpoint>
     target:
       configMapName: configmap-created-by-appconfig-provider
       configMapData: 
         type: json
         key: mysettings.json
     auth:
       workloadIdentity:
         serviceAccountName: <your-service-account-name>
   

   endpoint 필드의 값을 Azure App Configuration 저장소의 엔드포인트로 바꿉니다. 다음 단계로 진행하여 인증 정보로 auth 섹션을 업데이트합니다.

   참고 항목

   AzureAppConfigurationProvider는 선언적 API 개체입니다. 이 개체는 다음 동작을 사용하여 App Configuration 저장소에 들어 있는 데이터로 만든 ConfigMap의 원하는 상태를 정의합니다.

   • 이름이 같은 ConfigMap이 동일한 네임스페이스에 이미 있는 경우 ConfigMap을 만들 수 없습니다.
   • App Configuration 저장소가 다른 방법으로 삭제되거나 수정된 경우 ConfigMap은 App Configuration 저장소의 현재 데이터를 기반으로 초기화됩니다.
   • App Configuration Kubernetes Provider를 제거하면 ConfigMap이 삭제됩니다.

4. 워크로드 ID를 사용하기 위한 지침에 따라 App Configuration 저장소에 인증합니다. serviceAccountName 필드를 만든 서비스 계정의 이름으로 바꿔 appConfigurationProvider.yaml 파일을 업데이트합니다. 다른 인증 방법에 대한 자세한 내용은 인증 섹션의 예를 참조하세요.

5. configmap-created-by-appconfig-provider ConfigMap을 탑재된 데이터 볼륨으로 사용하도록 Deployment 디렉터리의 deployment.yaml 파일을 업데이트합니다. volumeMounts.mountPath가 Dockerfile 및 이전에 만들어진 config 디렉터리에 지정된 WORKDIR과 일치하는지 확인해야 합니다.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: aspnetapp-demo
     labels:
       app: aspnetapp-demo
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: aspnetapp-demo
     template:
       metadata:
         labels:
           app: aspnetapp-demo
       spec:
         containers:
         - name: aspnetapp
           image: myregistry.azurecr.io/aspnetapp:v1
           ports:
           - containerPort: 80
           volumeMounts:
           - name: config-volume
             mountPath: /app/config
         volumes:
         - name: config-volume 
           configMap: 
             name: configmap-created-by-appconfig-provider
   

6. 다음 명령을 실행하여 변경 내용을 배포합니다. 기존 AKS 애플리케이션을 사용하는 경우 네임스페이스를 바꿉니다.

   kubectl apply -f ./Deployment -n appconfig-demo
   

7. 브라우저를 새로 고칩니다. 페이지에 업데이트된 콘텐츠가 표시됩니다.

   

문제 해결

애플리케이션이 App Configuration 저장소에서 데이터를 선택하는 것이 보이지 않으면 다음 명령을 실행하여 ConfigMap이 제대로 만들어졌는지 확인합니다.

kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo

ConfigMap이 만들어지지 않았으면 다음 명령을 실행하여 데이터 검색 상태를 가져옵니다.

kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

Azure App Configuration Kubernetes Provider가 App Configuration 저장소의 데이터를 성공적으로 검색했다면 다음 예제와 같이 출력의 상태 섹션에 있는 phase 속성은 COMPLETE여야 합니다.

$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2023-04-06T06:17:06Z"
  lastSyncTime: "2023-04-06T06:17:06Z"
  message: Complete sync settings to ConfigMap or Secret
  phase: COMPLETE

상태가 COMPLETE가 아니면 App Configuration 저장소에서 데이터가 제대로 다운로드되지 않은 것입니다. 다음 명령을 실행하여 Azure App Configuration Kubernetes Provider의 로그를 표시합니다.

kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system

이 로그를 추가 문제 해결에 사용합니다. 일반적인 문제는 FAQ 섹션을 참조하세요.

FAQ

ConfigMap 또는 Secret이 생성되지 않는 이유는 무엇인가요?

문제 해결 가이드의 단계에 따라 자세한 오류 정보를 얻기 위해 로그를 수집할 수 있습니다. 몇 가지 일반적인 원인은 다음과 같습니다.

• 응답 403: 403 사용할 수 없음: 구성된 ID에 App Configuration 저장소에 액세스하는 데 필요한 권한이 없습니다. 사용하는 ID와 일치하는 예를 보려면 인증 섹션을 참조하세요.
• App Configuration에서 Key Vault 참조가 발견되었지만 'spec.secret'이 구성되지 않음: 선택한 키 값에 하나 이상의 Key Vault 참조가 포함되어 있지만 Key Vault에 대한 인증 정보가 제공되지 않습니다. 구성의 무결성을 유지하기 위해 전체 구성이 로드되지 않습니다. spec.secret 섹션을 구성하여 필요한 인증 정보를 제공합니다. 예 및 자세한 내용은 Key Vault 참조를 참조하세요.

생성된 ConfigMap에 예상된 데이터가 포함되지 않는 이유는 무엇인가요?

예상 데이터와 일치하도록 올바른 키-값 선택기를 지정했는지 확인합니다. 선택기를 지정하지 않으면 레이블이 없는 모든 키-값은 App Configuration 저장소에서 다운로드됩니다. 키 필터를 사용할 때 예상 키-값의 접두사와 일치하는지 확인합니다. 키-값에 레이블이 있는 경우 선택기에서 레이블 필터를 지정해야 합니다. 더 많은 예를 보려면 키-값 선택 설명서를 참조하세요.

Azure App Configuration Kubernetes 공급자 설치를 사용자 지정하려면 어떻게 해야 하나요?

Azure App Configuration Kubernetes 공급자를 설치할 때 추가적인 Helm 값을 제공하여 설치를 사용자 지정할 수 있습니다. 예를 들어, 로그 수준을 설정하고, 공급자가 특정 노드에서 실행되도록 구성하거나, 워크로드 ID를 사용하지 않도록 설정할 수 있습니다. 자세한 내용은 설치 가이드를 참조하세요.

공급자를 버전 2.0.0으로 업그레이드한 후 워크로드 ID를 사용하여 Azure App Configuration에서 인증할 수 없는 이유는 무엇인가요?

버전 2.0.0부터 워크로드 ID를 사용하여 Azure App Configuration을 인증하려면 사용자가 제공한 서비스 계정이 필요합니다. 이 변경은 네임스페이스 격리를 통해 보안을 강화합니다. 이전에는 Kubernetes 공급자의 서비스 계정이 모든 네임스페이스에 사용되었습니다. 업데이트된 지침은 워크로드 ID 사용에 대한 설명서를 참조하세요. 버전 2.0.0으로 업그레이드할 때 마이그레이션할 시간이 필요한 경우 공급자 설치 중에 일시적으로 workloadIdentity.globalServiceAccountEnabled=true를 설정할 수 있습니다. 향후 릴리스에서는 공급자의 서비스 계정 사용에 대한 지원이 중단될 예정입니다.

리소스 정리

AKS 클러스터를 유지하려면 AKS 클러스터에서 App Configuration Kubernetes Provider를 제거합니다.

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

이 문서에서 만든 리소스를 계속 사용하지 않으려면 여기서 만든 리소스 그룹을 삭제하여 요금이 부과되지 않도록 합니다.

Important

리소스 그룹을 삭제하면 다시 되돌릴 수 없습니다. 리소스 그룹 및 포함된 모든 리소스가 영구적으로 삭제됩니다. 잘못된 리소스 그룹 또는 리소스를 자동으로 삭제하지 않도록 합니다. 유지하려는 다른 리소스가 포함된 리소스 그룹 내에서 이 문서에 대한 리소스를 만든 경우 리소스 그룹을 삭제하는 대신 해당 창에서 각 리소스를 개별적으로 삭제합니다.

1. Azure Portal에 로그인하고 리소스 그룹을 선택합니다.
2. 이름으로 필터링 상자에서 리소스 그룹의 이름을 입력합니다.
3. 결과 목록에서 리소스 그룹 이름을 선택하여 개요를 확인합니다.
4. 리소스 그룹 삭제를 선택합니다.
5. 리소스 그룹 삭제를 확인하는 메시지가 표시됩니다. 리소스 그룹의 이름을 입력하여 확인하고 삭제를 선택합니다.

잠시 후, 리소스 그룹 및 모든 해당 리소스가 삭제됩니다.

참고 항목

Azure Developer CLI를 사용하여 리소스를 설정하는 경우 azd down 명령을 실행하여 azure-appconfig-aks 템플릿에서 만들어진 모든 리소스를 삭제할 수 있습니다.

다음 단계

이 빠른 시작에서 관련 정보는 다음과 같습니다.

• AKS(Azure Kubernetes Service)에서 실행되는 애플리케이션을 만들었습니다.
• App Configuration Kubernetes Provider를 사용하여 AKS 클러스터를 App Configuration 저장소에 연결했습니다.
• App Configuration 저장소의 데이터로 ConfigMap을 만들었습니다.
• 애플리케이션 코드를 변경하지 않고 App Configuration 저장소의 구성을 사용하여 애플리케이션을 실행했습니다.

구성을 동적으로 새로 고치도록 AKS 워크로드를 업데이트하는 방법을 알아보려면 다음 자습서를 계속 진행하세요.

Azure Kubernetes Service에서 동적 구성 사용

Azure App Configuration Kubernetes 공급자에 대한 자세한 내용은 Azure App Configuration Kubernetes 공급자 참조를 참조하세요.