AKS(Azure Kubernetes Service)에서 서비스 주체 사용

  • 아티클

Azure Load Balancer 또는 ACR(Azure Container Registry)과 같은 다른 Azure 리소스를 동적으로 만들고 관리하려면 AKS 클러스터에 Microsoft Entra 서비스 주체 또는 관리 ID가 필요합니다.

참고 항목

관리 ID를 사용하여 Azure의 다른 리소스로 인증하는 것이 좋으며 이 방법은 AKS 클러스터의 기본 인증 방법입니다. 클러스터에서 관리 ID를 사용하는 방법에 대한 자세한 내용은 시스템 할당 관리 ID 사용을 참조하세요.

이 문서에서는 AKS 클러스터의 서비스 주체를 만들고 사용하는 방법을 보여줍니다.

시작하기 전에

Microsoft Entra 서비스 주체를 만들려면 Microsoft Entra 테넌트에 애플리케이션을 등록하고 애플리케이션을 구독의 역할에 할당할 수 있는 권한이 있어야 합니다. 필요한 권한이 없으면 Microsoft Entra ID 또는 구독 관리자에게 필요한 권한을 할당하거나 AKS 클러스터에서 사용할 수 있는 서비스 주체를 미리 만들어 달라고 요청해야 합니다.

다른 Microsoft Entra 테넌트의 서비스 주체를 사용하는 경우 클러스터를 배포할 때 사용할 수 있는 권한에 대한 다른 고려 사항이 있습니다. 디렉터리 정보를 읽고 쓸 수 있는 적절한 권한이 없을 수 있습니다. 자세한 내용은 Microsoft Entra ID의 기본 사용자 권한은 무엇인가요?를 참조하세요.

필수 조건

  • Azure CLI를 사용할 경우 Azure CLI 버전 2.0.59 이상이 필요합니다. az --version을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.
  • Azure PowerShell을 사용할 경우 Azure PowerShell 버전 5.0.0 이상이 필요합니다. Get-InstalledModule -Name Az을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure Az PowerShell 모듈 설치를 참조하세요.

수동으로 서비스 주체 만들기

  1. az ad sp create-for-rbac 명령을 사용하여 서비스 주체를 만듭니다.

    az ad sp create-for-rbac --name myAKSClusterServicePrincipal

    출력은 다음 출력 예와 유사해야 합니다.

    {
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

  2. 출력에서 appId 및 password 값을 복사합니다. 다음 섹션에서 AKS 클러스터를 만들 때 사용합니다.

AKS 클러스터에 대한 서비스 주체 지정

  • az aks create 명령을 사용하여 새 AKS 클러스터의 기존 서비스 주체를 사용하고 --service-principal 및 --client-secret 매개 변수를 사용하여 이전 섹션을 받은 출력에서 appId 및 password를 지정합니다.

    az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

    참고 항목

    사용자 지정 비밀로 기존 서비스 주체를 사용하는 경우 비밀이 190바이트보다 길지 않은지 확인합니다.

다른 Azure 리소스에 대한 액세스 권한 위임

AKS 클러스터의 서비스 주체를 사용하여 다른 리소스에 액세스할 수 있습니다. 예를 들어 AKS 클러스터를 기존 Azure 가상 네트워크 서브넷에 배포하거나 ACR(Azure Container Registry)에 연결하려면 해당 리소스에 대한 액세스를 서비스 주체에 위임해야 합니다. 시스템 할당 관리 ID를 사용하여 클러스터에 부여된 권한은 채우는 데 최대 60분이 걸릴 수 있습니다.

  • az role assignment create 명령을 사용하여 역할 할당을 만듭니다. appId를 리소스 그룹 또는 가상 네트워크 리소스와 같은 특정 범위에 할당합니다. 역할은 서비스 주체가 리소스에 대해 가지고 있는 권한을 정의합니다.

    참고 항목

    리소스에 대한 --scope은 전체 리소스 ID여야 합니다(예: /subscriptions/<guid>/resourceGroups/myResourceGroup 또는 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet).

    az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

다음 섹션에서는 할당해야 하는 일반적인 위임에 대해 자세히 설명합니다.

Azure Container Registry

ACR(Azure Container Registry)을 컨테이너 이미지 스토리지로 사용하는 경우 이미지를 읽고 끌어오기 위해서는 AKS 클러스터에 대한 사용 권한을 서비스 주체에 부여해야 합니다. az aks create 또는 az aks update 명령을 사용하여 레지스트리와 통합하고 서비스 주체에 적절한 역할을 할당하는 것이 좋습니다. 자세한 단계는 Azure Kubernetes Service의 Azure Container Registry를 사용하여 인증을 참조하세요.

네트워킹

가상 네트워크와 서브넷 또는 공용 IP 주소가 다른 리소스 그룹에 있는 고급 네트워킹을 사용할 수 있습니다. 또는 가상 네트워크 내에서 서브넷에 네트워크 기여자 기본 제공 역할을 할당합니다. 또는 해당 리소스 그룹의 네트워크 리소스에 액세스할 수 있는 권한이 있는 사용자 지정 역할을 만들 수 있습니다. 자세한 내용은 AKS 서비스 권한을 참조하세요.

스토리지

다른 리소스 그룹의 기존 디스크 리소스에 액세스해야 하는 경우 다음 역할 권한 세트 중 하나를 할당합니다.

Azure Container Instances

Virtual Kubelet을 사용하여 AKS와 통합하고 AKS 클러스터와 별도로 리소스 그룹에서 ACI(Azure Container Instances)를 실행하도록 선택하는 경우, AKS 클러스터 서비스 주체에 ACI 리소스 그룹에 대한 Contributor 권한을 부여해야 합니다.

기타 고려 사항

AKS 및 Microsoft Entra 서비스 주체를 사용하는 경우 다음을 고려합니다.

  • Kubernetes의 서비스 주체는 클러스터 구성의 일부이지만 이 ID를 사용하여 클러스터를 배포하지 마세요.
  • 기본적으로 서비스 주체 자격 증명은 1년 동안 유효합니다. 언제든지 서비스 주체 자격 증명을 업데이트 또는 회전할 수 있습니다.
  • 모든 서비스 주체는 Microsoft Entra 애플리케이션과 연결됩니다. Kubernetes 클러스터의 서비스 주체를 유효한 모든 Microsoft Entra 애플리케이션 이름(예: https://www.contoso.org/example)과 연결할 수 있습니다. 애플리케이션에 대한 URL은 실제 엔드포인트일 필요가 없습니다.
  • 서비스 주체 클라이언트 ID를 지정할 때 appId 값을 사용합니다.
  • Kubernetes 클러스터의 에이전트 노드 VM에서 서비스 주체 자격 증명은 /etc/kubernetes/azure.json 파일에 저장됩니다.
  • az aks create 명령을 사용하여 만든 AKS 클러스터를 삭제해도 생성된 서비스 주체는 자동으로 삭제되지 않습니다.

    • 서비스 주체를 삭제하려면 클러스터의 servicePrincipalProfile.clientId를 쿼리하고 az ad sp delete 명령을 사용하여 삭제합니다. 리소스 그룹 이름에 대한 -g 매개 변수 값과 클러스터 이름에 대한 -n 매개 변수 값을 바꿉니다.

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

문제 해결

Azure CLI는 AKS 클러스터의 서비스 주체 자격 증명을 캐시합니다. 이러한 자격 증명이 만료되면 AKS 클러스터 배포 중에 오류가 발생합니다. az aks create 명령을 실행하고 다음과 유사한 오류 메시지를 수신하면 캐시된 서비스 주체 자격 증명에 문제가 있을 수 있습니다.

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

"[].endDateTime" 쿼리와 함께 az ad app credential list 명령을 사용하여 서비스 주체 자격 증명 만료 날짜를 확인할 수 있습니다.

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

서비스 주체 자격 증명은 보통 1년 뒤에 만료됩니다. 자격 증명이 1년보다 오래된 경우 기존 자격 증명을 다시 설정하거나 새 서비스 주체를 만들 수 있습니다.

일반적인 Azure CLI 문제 해결

Azure CLI는 여러 셸 환경에서 실행할 수 있지만 약간의 형식 변형이 있습니다. Azure CLI 명령으로 예기치 않은 결과가 발생하는 경우 Azure CLI를 성공적으로 사용하는 방법을 참조하세요.

다음 단계

Microsoft Entra 서비스 주체에 대한 자세한 내용은 애플리케이션 개체 및 서비스 주체 개체를 참조하세요.

자격 증명을 업데이트하는 방법에 대한 자세한 내용은 AKS의 서비스 주체에 대한 자격 증명 업데이트 또는 회전을 참조하세요.