다음을 통해 공유

kubelogin을 사용하여 Kubernetes 클러스터에서 Azure 관리 ID 인증 사용

  • 아티클

AKS 관리형 Microsoft Entra 통합은 Microsoft Entra 통합 프로세스를 간소화합니다. 이전에는 클라이언트 및 서버 앱을 만들어야 했고, Microsoft Entra 테넌트는 디렉터리 읽기 권한자 역할 권한을 할당해야 했습니다. 이제는 AKS 리소스 공급자가 클라이언트 및 서버 앱을 자동으로 관리합니다.

클러스터 관리자는 사용자의 ID 또는 디렉터리 그룹 구성원 자격에 따라 Kubernetes RBAC(Kubernetes 역할 기반 액세스 제어)를 구성할 수 있습니다. OpenID Connect를 사용하는 AKS 클러스터에 Microsoft Entra 인증이 제공됩니다. OpenID Connect는 OAuth 2.0 프로토콜을 기반으로 하는 ID 계층입니다. OpenID Connect에 대한 자세한 내용은 OpenID Connect 설명서를 참조하세요.

Microsoft Entra 설명서에서 Microsoft Entra 통합 흐름에 대해 자세히 알아보세요.

이 문서에서는 AKS 클러스터를 통해 Azure 리소스에 대한 관리 ID를 지원하고 사용하는 방법에 대해 자세히 설명합니다.

제한 사항

다음은 AKS에서 Azure 관리 ID 인증을 통합하는 제약 조건입니다.

  • 추가한 후에는 통합을 사용할 수 없습니다.
  • 통합된 클러스터에서 레거시 Microsoft Entra ID 클러스터로의 다운그레이드는 지원되지 않습니다.
  • Kubernetes RBAC가 지원되지 않는 클러스터는 통합을 추가할 수 없습니다.

시작하기 전에

관리 ID에 대한 AKS 추가 항목을 적절히 설치하려면 다음 요구 사항을 충족해야 합니다.

  • Azure CLI 버전 2.29.0 이상이 설치 및 구성되어 있습니다. az --version을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.
  • 최소 버전이 1.18.1 또는 kubelogin인 kubectl이 필요합니다. Azure CLI 및 Azure PowerShell 모듈을 사용하면 이러한 두 명령이 포함되고 자동으로 관리됩니다. 즉, 기본적으로 업그레이드되며 az aks install-cli 실행은 필요하지 않거나 권장되지 않습니다. 자동화된 파이프라인을 사용하는 경우 올바른 버전 또는 최신 버전의 업그레이드를 관리해야 합니다. Kubernetes와 kubectl의 부 버전 간 차이가 한 버전을 초과하면 안 됩니다. 그렇지 않으면 잘못된 버전에서 인증 문제가 발생합니다.
  • helm을 사용하는 경우 최소 helm 3.3이 필요합니다.
  • 이 구성을 사용하려면 클러스터용 Microsoft Entra 그룹이 있어야 합니다. 이 그룹은 관리자 권한을 부여하기 위해 클러스터에 관리자 그룹으로 등록됩니다. 기존 Microsoft Entra 그룹이 없는 경우 az ad group create 명령을 사용하여 그룹을 만들 수 있습니다.

참고 항목

버전 1.24보다 최신 버전의 Kubernetes를 사용하는 Microsoft Entra 통합 클러스터는 kubelogin 형식을 자동으로 사용합니다. Kubernetes 버전 1.24부터 Microsoft Entra ID 클러스터에 대한 clusterUser 자격 증명의 기본 형식은 실행 PATH에 kubelogin 이진이 필요한 exec입니다. Microsoft Entra가 아닌 클러스터 또는 1.24 이전 버전을 실행하는 Microsoft Entra ID 클러스터에서는 동작이 변경되지 않습니다. 다운로드한 기존 kubeconfig는 계속 작동합니다. clusterUser 자격 증명을 가져와 기본 동작 변경을 덮어쓰는 경우 선택적 쿼리 매개 변수 형식 이 포함됩니다. 이전 kubeconfig 형식을 유지해야 하는 경우 azure에 형식을 명시적으로 지정할 수 있습니다.

AKS 클러스터에서 통합 사용

새 클러스터 만들기

  1. az group create 명령을 사용하여 Azure 리소스 그룹을 만듭니다.

    az group create --name myResourceGroup --location centralus

  2. az aks create 명령을 사용하여 AKS 클러스터를 만들고 Microsoft Entra 그룹에 대한 관리 액세스를 사용합니다.

    az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --enable-aad \
    --aad-admin-group-object-ids <id> [--aad-tenant-id <id>] \
    --generate-ssh-keys

    AKS 관리형 Microsoft Entra ID 클러스터가 만들어지면 응답 본문에 다음 섹션이 포함됩니다.

    "AADProfile": {
    "adminGroupObjectIds": [
    "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
}

기존 클러스터 사용

az aks update 명령을 사용하여 기존 Kubernetes RBAC 지원 클러스터에서 AKS 관리형 Microsoft Entra 통합을 사용합니다. 클러스터에 대한 액세스를 유지하려면 관리자 그룹을 설정해야 합니다.

az aks update --resource-group MyResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]

AKS 관리형 Microsoft Entra ID 클러스터가 활성화되면 응답 본문에 다음 섹션이 포함됩니다

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

통합으로 레거시 클러스터 마이그레이션

클러스터에서 레거시 Microsoft Entra 통합을 사용하는 경우 az aks update 명령을 통해 AKS 관리형 Microsoft Entra 통합으로 업그레이드할 수 있습니다.

Warning

업그레이드하는 동안 무료 계층 클러스터에서 API 서버 가동이 중지될 수도 있습니다. 업무 시간이 아닐 때 업그레이드하는 것이 좋습니다. 업그레이드하고 나면 kubeconfig 콘텐츠가 변경됩니다. az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name>을 실행하여 새 자격 증명을 kubeconfig 파일에 병합해야 합니다.

az aks update --resource-group myResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

AKS 관리형 Microsoft Entra ID 클러스터가 마이그레이션되면 응답 본문에 다음 섹션이 포함됩니다

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

지원 클러스터에 액세스

  1. az aks get-credentials 명령을 사용하여 클러스터에 액세스하기 위한 사용자 자격 증명을 가져옵니다.

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

  2. 지침에 따라 로그인합니다.

  3. Azure CLI를 사용하도록 kubelogin을 설정합니다.

    kubelogin convert-kubeconfig -l azurecli

  4. kubectl get nodes 명령을 사용하여 클러스터의 노드를 확인합니다.

    kubectl get nodes

kubelogin을 사용한 비대화형 로그인

kubectl을 지원하지 않는 비대화형 시나리오가 몇 가지 있습니다. 이러한 경우 kubelogin을 사용해 비대화형 서비스 사용자 자격 증명으로 클러스터에 로그인하여 연속 통합 파이프라인을 수행합니다.

참고 항목

버전 1.24보다 최신 버전의 Kubernetes를 사용하는 Microsoft Entra 통합 클러스터는 kubelogin 형식을 자동으로 사용합니다. Kubernetes 버전 1.24부터 Microsoft Entra ID 클러스터에 대한 clusterUser 자격 증명의 기본 형식은 실행 PATH에 kubelogin 이진이 필요한 exec입니다. Microsoft Entra가 아닌 클러스터 또는 1.24 이전 버전을 실행하는 Microsoft Entra ID 클러스터에서는 동작이 변경되지 않습니다. 다운로드한 기존 kubeconfig는 계속 작동합니다. clusterUser 자격 증명을 가져와 기본 동작 변경을 덮어쓰는 경우 선택적 쿼리 매개 변수 형식 이 포함됩니다. 이전 kubeconfig 형식을 유지해야 하는 경우 azure에 형식을 명시적으로 지정할 수 있습니다.

  • clusterUser 자격 증명을 가져올 때 format 쿼리 매개 변수를 사용하면 기본 동작을 덮어쓸 수 있습니다. 값을 azure로 설정하면 원래 kubeconfig 형식을 사용할 수 있습니다.

    az aks get-credentials --format azure

  • Microsoft Entra 통합 클러스터에서 Kubernetes 버전 1.24 이하를 사용하는 경우 kubeconfig 형식을 수동으로 변환해야 합니다.

    export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

참고 항목

오류: Azure 인증 플러그 인이 제거되었습니다.라는 메시지가 표시되면 kubelogin convert-kubeconfig 명령을 실행하여 kubeconfig 형식을 수동으로 변환해야 합니다.

자세한 내용은 Azure Kubelogin 알려진 문제를 참조하세요.

액세스 문제 해결

Important

이 섹션에 설명된 단계에서는 일반 Microsoft Entra 그룹 인증과 비교하여 대체 인증 방법을 제안합니다. 긴급 상황에서만 이 옵션을 사용하세요.

유효한 Microsoft Entra 그룹에 대한 관리 액세스 권한이 없는 경우 이 해결 방법을 따를 수 있습니다. Azure Kubernetes Service 클러스터 관리자 역할의 멤버인 계정으로 로그인하고 그룹 또는 테넌트 관리자 자격 증명을 부여하여 클러스터에 액세스합니다.

다음 단계