다음을 통해 공유

Pod 관리 ID에서 워크로드 ID로 마이그레이션

  • 아티클

이 문서에서는 AKS(Azure Kubernetes Service) 클러스터에 대한 Pod 관리 ID에서 Microsoft Entra 워크로드 ID로 마이그레이션하는 데 중점을 둡니다. 또한 컨테이너 기반 애플리케이션에서 사용하는 Azure ID 클라이언트 라이브러리 버전에 따라 지침을 제공합니다.

Microsoft Entra 워크로드 ID에 익숙하지 않은 경우 다음 개요 문서를 참조하세요.

시작하기 전에

Azure CLI 버전, 2.47.0 이상. az --version을 실행하여 버전을 찾고 az upgrade를 실행하여 버전을 업그레이드합니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.

마이그레이션 시나리오

이 섹션에서는 설치된 Azure ID SDK 버전에 따라 사용 가능한 마이그레이션 옵션에 대해 설명합니다.

두 시나리오 모두 워크로드 ID를 사용하도록 애플리케이션을 업데이트하기 전에 페더레이션 트러스트를 설정해야 합니다. 다음은 필요한 최소 단계입니다.

최신 버전에서 마이그레이션

애플리케이션이 이미 최신 버전의 Azure ID SDK를 사용하고 있는 경우 다음 단계를 수행하여 인증 구성을 완료합니다.

  • Pod 관리 ID와 병렬로 워크로드 ID를 배포합니다. 애플리케이션 배포를 다시 시작하여 OIDC 주석을 애플리케이션에 자동으로 삽입하는 워크로드 ID 사용을 시작할 수 있습니다.
  • 애플리케이션이 성공적으로 인증할 수 있는지 확인한 후 애플리케이션에서 Pod 관리 ID를 제거한 다음 Pod 관리 ID 추가 기능을 제거할 수 있습니다.

이전 버전에서 마이그레이션

애플리케이션이 최신 버전의 Azure ID SDK를 사용하지 않는 경우 다음 두 가지 옵션이 있습니다.

  • Linux 애플리케이션 내에서 제공되는 마이그레이션 사이드카를 사용할 수 있습니다. 이는 애플리케이션이 수행하는 IMDS 트랜잭션을 OIDC(OpenID Connect)로 프록시합니다. 마이그레이션 사이드카는 장기적인 솔루션이 아니라 워크로드 ID에서 빠르게 시작하고 실행할 수 있는 방법입니다. 다음 단계를 수행합니다.

    • 마이그레이션 사이드카로 워크로드를 배포하여 애플리케이션 IMDS 트랜잭션을 프록시합니다.
    • 인증 트랜잭션이 성공적으로 완료되었는지 확인합니다.
    • SDK를 지원되는 버전으로 업데이트하도록 애플리케이션 작업을 예약합니다.
    • SDK가 지원되는 버전으로 업데이트되면 프록시 사이드카를 제거하고 애플리케이션을 다시 배포할 수 있습니다.

    참고 항목

    마이그레이션 사이드카는 프로덕션 용도로 지원되지 않습니다. 이 기능은 애플리케이션 SDK를 지원되는 버전으로 마이그레이션할 시간을 제공하기 위한 것이며 장기적인 솔루션을 의미하거나 의도한 것은 아닙니다. 마이그레이션 사이드카는 Linux 노드 풀에서만 Pod 관리 ID를 제공하므로 Linux 컨테이너에서만 사용할 수 있습니다.

  • 최신 버전의 Azure ID 클라이언트 라이브러리를 지원하도록 애플리케이션을 다시 작성합니다. 이후 다음 단계를 수행합니다.

    • 워크로드 ID를 사용하여 인증을 시작하려면 애플리케이션 배포를 다시 시작합니다.
    • 인증 트랜잭션이 성공적으로 완료되었는지 확인하면 애플리케이션에서 Pod 관리 ID 주석을 제거한 다음 Pod 관리 ID 추가 기능을 제거할 수 있습니다.

관리 ID 만들기

Pod에 생성 및 할당된 관리 ID가 없는 경우 다음 단계를 수행하여 스토리지, Key Vault 또는 애플리케이션이 Azure에서 인증하는 데 필요한 모든 리소스에 필요한 권한을 생성하고 부여합니다.

  1. Azure CLI az account set 명령을 사용하여 특정 구독을 현재 활성 구독으로 설정합니다. 그런 다음, 관리 ID를 만들려면 az identity create 명령을 사용합니다.

    az account set --subscription "subscriptionID"

    az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"

    export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "resourceGroupName" --name "userAssignedIdentityName" --query 'clientId' -otsv)"

  2. 필요한 Azure의 리소스에 액세스하는 데 필요한 권한을 관리 ID에 부여합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 리소스에 관리 ID 액세스 할당을 참조하세요.

  3. OIDC 발급자 URL을 가져와서 환경 변수에 저장하려면 다음 명령을 실행합니다. 클러스터 이름 및 리소스 그룹 이름의 기본값을 바꿉니다.

    export AKS_OIDC_ISSUER="$(az aks show --name myAKSCluster --resource-group myResourceGroup --query "oidcIssuerProfile.issuerUrl" -o tsv)"

    변수에는 다음 예제와 유사한 발급자 URL이 포함되어야 합니다.

    https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/

    기본적으로 발급자는 기준 URL https://{region}.oic.prod-aks.azure.com/{uuid}를 사용하도록 설정됩니다. 여기서 {region}의 값은 AKS 클러스터가 배포된 위치와 일치합니다. 값 {uuid}은(는) OIDC 키를 나타냅니다.

Kubernetes 서비스 계정 만들기

이 애플리케이션에 대해 만들어진 전용 Kubernetes 서비스 계정이 없는 경우 다음 단계를 수행하여 만든 다음 이전 단계에서 만든 관리 ID의 클라이언트 ID로 주석을 답니다. az aks get-credentials 명령을 사용하고 클러스터 이름과 리소스 그룹 이름의 값을 바꿉니다.

az aks get-credentials --name myAKSCluster --resource-group "${RESOURCE_GROUP}"

Azure CLI에서 다음 여러 줄 입력을 복사하여 붙여넣습니다.

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    azure.workload.identity/client-id: ${USER_ASSIGNED_CLIENT_ID}
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF

다음 출력은 성공적인 ID 만들기와 유사합니다.

Serviceaccount/workload-identity-sa created

페더레이션 ID 자격 증명 트러스트 설정

az identity federated-credential create 명령을 사용하여 관리 ID, 서비스 계정 발급자 및 주체 간에 페더레이션 ID 자격 증명을 만듭니다. 값 resourceGroupName, userAssignedIdentityName, federatedIdentityName, serviceAccountNamespace 및 serviceAccountName를 바꿉니다.

az identity federated-credential create --name federatedIdentityName --identity-name userAssignedIdentityName --resource-group resourceGroupName --issuer ${AKS_OIDC_ISSUER} --subject system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME} --audience api://AzureADTokenExchange

참고 항목

페더레이션 ID 자격 증명이 처음 추가된 후 전파되는 데 몇 초 정도 걸립니다. 페더레이션 ID 자격 증명을 추가한 직후에 토큰 요청이 이루어진 경우 캐시가 이전 데이터와 디렉터리에 채워지기 때문에 몇 분 동안 실패할 수 있습니다. 이 문제를 방지하려면 페더레이션 ID 자격 증명을 추가한 후 약간의 지연을 추가하면 됩니다.

마이그레이션 사이드카로 워크로드 배포

참고 항목

마이그레이션 사이드카는 프로덕션 용도로 지원되지 않습니다. 이 기능은 애플리케이션 SDK를 지원되는 버전으로 마이그레이션할 시간을 제공하기 위한 것이며 장기적인 솔루션을 의미하거나 의도한 것은 아닙니다. Pod 관리 ID는 Linux 노드 풀에서만 사용할 수 있으므로 마이그레이션 사이드카는 Linux 컨테이너에만 적용됩니다.

애플리케이션이 관리 ID를 사용하고 있지만 여전히 IMDS를 사용하여 액세스 토큰을 가져오는 경우 워크로드 ID 마이그레이션 사이드카를 사용하여 워크로드 ID로의 마이그레이션을 시작할 수 있습니다. 이 사이드카는 마이그레이션 솔루션이며 장기 애플리케이션에서는 클라이언트 어설션을 지원하는 최신 Azure ID SDK를 사용하도록 해당 코드를 수정해야 합니다.

워크로드를 업데이트하거나 배포하려면 마이그레이션 사이드카를 사용하려는 경우에만 이러한 Pod 주석을 추가합니다. Pod 사양에서 사이드카를 사용하려면 다음 주석 값을 삽입합니다.

  • azure.workload.identity/inject-proxy-sidecar - 값은 true 또는 false입니다.
  • azure.workload.identity/proxy-sidecar-port - 값은 프록시 사이드카에 대해 원하는 포트입니다. 기본값은 8000입니다.

위의 주석이 있는 Pod가 만들어지면 Azure 워크로드 ID 변형 웹후크가 자동으로 초기화 컨테이너 및 프록시 사이드카를 Pod 사양에 삽입합니다.

이미 실행 중인 웹후크는 Pod 배포에 다음 YAML 코드 조각을 추가합니다. 다음은 변경된 Pod 사양의 예입니다.

apiVersion: v1
kind: Pod
metadata:
  name: httpbin-pod
  labels:
    app: httpbin
    azure.workload.identity/use: "true"
  annotations:
    azure.workload.identity/inject-proxy-sidecar: "true"
spec:
  serviceAccountName: workload-identity-sa
  initContainers:
  - name: init-networking
    image: mcr.microsoft.com/oss/azure/workload-identity/proxy-init:v1.1.0
    securityContext:
      capabilities:
        add:
        - NET_ADMIN
        drop:
        - ALL
      privileged: true
      runAsUser: 0
    env:
    - name: PROXY_PORT
      value: "8000"
  containers:
  - name: nginx
    image: nginx:alpine
    ports:
    - containerPort: 80
  - name: proxy
    image: mcr.microsoft.com/oss/azure/workload-identity/proxy:v1.1.0
    ports:
    - containerPort: 8000

이 구성은 Pod가 만들어지는 모든 구성에 적용됩니다. 애플리케이션을 업데이트하거나 배포한 후 kubectl describe pod 명령을 사용하여 Pod가 실행 상태인지 확인할 수 있습니다. 값 podName를 배포된 Pod의 이미지 이름으로 바꿉니다.

kubectl describe pods podName

Pod가 IMDS 트랜잭션을 전달하는지 확인하려면 kubectl logs 명령을 사용합니다. 값 podName를 배포된 Pod의 이미지 이름으로 바꿉니다.

kubectl logs podName

다음 로그 출력은 프록시 사이드카를 통한 성공적인 통신과 유사합니다. 로그에 토큰이 성공적으로 획득되고 GET 작업이 성공했다고 표시되는지 확인합니다.

I0926 00:29:29.968723       1 proxy.go:97] proxy "msg"="starting the proxy server" "port"=8080 "userAgent"="azure-workload-identity/proxy/v0.13.0-12-gc8527f3 (linux/amd64) c8527f3/2022-09-26-00:19"
I0926 00:29:29.972496       1 proxy.go:173] proxy "msg"="received readyz request" "method"="GET" "uri"="/readyz"
I0926 00:29:30.936769       1 proxy.go:107] proxy "msg"="received token request" "method"="GET" "uri"="/metadata/identity/oauth2/token?resource=https://management.core.windows.net/api-version=2018-02-01&client_id=<client_id>"
I0926 00:29:31.101998       1 proxy.go:129] proxy "msg"="successfully acquired token" "method"="GET" "uri"="/metadata/identity/oauth2/token?resource=https://management.core.windows.net/api-version=2018-02-01&client_id=<client_id>"

Pod 관리 ID 제거

테스트를 완료하고 애플리케이션이 프록시 사이드카를 사용하여 성공적으로 토큰을 가져올 수 있으면 클러스터에서 Pod에 대한 Microsoft Entra Pod 관리 ID 매핑을 제거한 다음 ID를 제거할 수 있습니다.

  1. az aks pod-identity delete 명령을 실행하여 Pod에서 ID를 제거합니다. 이는 Pod 관리 ID 매핑을 사용하는 네임스페이스의 모든 Pod가 사이드카를 사용하도록 마이그레이션된 후에만 수행해야 합니다.

    az aks pod-identity delete --name podIdentityName --namespace podIdentityNamespace --resource-group myResourceGroup --cluster-name myAKSCluster

다음 단계

이 문서에서는 워크로드 ID를 마이그레이션 옵션으로 사용하여 인증하도록 Pod를 설정하는 방법을 보여 주었습니다. Microsoft Entra 워크로드 ID에 대한 자세한 내용은 다음 개요 문서를 참조하세요.