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

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

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

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 설치를 참조하세요.
• kubectl1.18.1 또는 kubelogin. 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 자격 증명의 기본 형식은 exec실행 PATH에서 이진이 필요합니다 kubelogin . 비 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. AKS 클러스터를 만들고 명령을 사용하여 az aks create Microsoft Entra 그룹에 대한 관리 액세스를 사용하도록 설정합니다.

   az aks create -g myResourceGroup -n 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"
   }
   

기존 클러스터 사용

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

az aks update -g MyResourceGroup -n 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 통합을 사용하는 경우 명령을 통해 AKS 관리형 Microsoft Entra 통합으로 업그레이드할 az aks update 수 있습니다.

Warning

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

az aks update -g myResourceGroup -n 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 자격 증명의 기본 형식은 exec실행 PATH에서 이진이 필요합니다 kubelogin . 비 Microsoft Entra 클러스터 또는 1.24 이전 버전을 실행하는 Microsoft Entra ID 클러스터에는 동작이 변경되지 않습니다. 다운로드한 기존 항목은 kubeconfig 계속 작동합니다. 기본 동작 변경을 덮어쓰기 위해 clusterUser 자격 증명을 가져오는 경우 선택적 쿼리 매개 변수 형식 이 포함됩니다. 이전 kubeconfig 형식을 기본 지정해야 하는 경우 azure에 형식을 명시적으로 지정할 수 있습니다.

• clusterUser 자격 증명을 가져오는 경우 쿼리 매개 변수를 format 사용하여 기본 동작을 덮어쓸 수 있습니다. 원래 kubeconfig 형식을 사용하도록 값을 azure 설정할 수 있습니다.

  az aks get-credentials --format azure
  

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

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

참고 항목

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

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

액세스 문제 해결

Important

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

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

다음 단계

• Kubernetes RBAC와 Microsoft Entra 통합에 대해 알아봅니다.
• AKS 및 Kubernetes ID 개념에 대해 자세히 알아봅니다.
• AKS에서 지원되는 모든 Microsoft Entra 인증 방법에 kubelogin을 사용하는 방법을 알아봅니다.
• ARM(Azure Resource Manager) 템플릿을 사용하여 AKS 관리형 Microsoft Entra ID 사용 클러스터를 만듭니다.