Azure CLI(레거시)를 사용하여 AKS(Azure Kubernetes Service)와 Microsoft Entra ID 통합
Warning
이 문서에 설명된 기능인 Microsoft Entra Integration(레거시)은 2023년 6월 1일에 더 이상 사용되지 않습니다. 현재 Microsoft Entra Integration(레거시)을 사용하여 새 클러스터를 만들 수 없습니다.
AKS에는 서버 또는 클라이언트 애플리케이션을 관리할 필요가 없는 AKS 관리형 Microsoft Entra ID 환경이 새롭게 개선되었습니다. 마이그레이션하려면 여기에 있는 지침을 따릅니다.
AKS(Azure Kubernetes Service)는 사용자 인증에 Microsoft Entra ID를 사용하도록 구성할 수 있습니다. 이 구성에서는 Microsoft Entra 인증 토큰을 사용하여 AKS 클러스터에 로그인할 수 있습니다. 클러스터 운영자는 사용자의 ID 또는 디렉터리 그룹 멤버 자격에 따라 Kubernetes RBAC(Kubernetes 역할 기반 액세스 제어)를 구성할 수도 있습니다.
이 문서에서는 필요한 Microsoft Entra 구성 요소를 만든 다음 Microsoft Entra ID 사용 클러스터를 배포하고 AKS 클러스터에서 기본 Kubernetes 역할을 만드는 방법을 보여 줍니다.
제한 사항
- Microsoft Entra ID는 Kubernetes RBAC 사용 클러스터에서만 사용하도록 설정할 수 있습니다.
- Microsoft Entra 레거시 통합은 클러스터를 만드는 동안에만 사용하도록 설정할 수 있습니다.
시작하기 전에
Azure CLI 버전 2.0.61 이상이 설치되고 구성되어 있어야 합니다. az --version을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.
브라우저에서 https://shell.azure.com Cloud Shell을 열려면 이동합니다.
일관성을 위해 이 문서의 명령을 실행하는 데 도움이 되도록 원하는 AKS 클러스터 이름에 대한 변수를 만듭니다. 다음 예제에서는 myakscluster라는 이름을 사용합니다.
aksname="myakscluster"
Microsoft Entra 인증 개요
Microsoft Entra 인증은 OpenID 커넥트 사용하여 AKS 클러스터에 제공됩니다. OpenID Connect는 OAuth 2.0 프로토콜을 기반으로 하는 ID 계층입니다. OpenID 커넥트 대한 자세한 내용은 OpenID 커넥트 설명서를 참조하세요.
Kubernetes 클러스터 내부에서 인증 토큰을 확인하는 데 Webhook 토큰 인증이 사용됩니다. 웹후크 토큰 인증은 AKS 클러스터의 일부로 구성되고 관리됩니다. 웹후크 토큰 인증에 대한 자세한 내용은 웹후크 인증 설명서를 참조 하세요.
참고 항목
AKS 인증을 위해 Microsoft Entra ID를 구성할 때 두 개의 Microsoft Entra 애플리케이션이 구성됩니다. 이 작업은 Azure 테넌트 관리자가 완료해야 합니다.
Microsoft Entra 서버 구성 요소 만들기
AKS와 통합하려면 ID 요청에 대한 엔드포인트 역할을 하는 Microsoft Entra 애플리케이션을 만들고 사용합니다. 필요한 첫 번째 Microsoft Entra 애플리케이션은 사용자에 대한 Microsoft Entra 그룹 멤버 자격을 가져옵니다.
az ad app create 명령을 사용하여 서버 애플리케이션 구성 요소를 만든 다음 az ad app update 명령을 사용하여 그룹 멤버 자격 클레임을 업데이트 합니다. 다음 예제에서는 시작하기 전에 섹션에 정의된 aksname 변수를 사용하고 변수를 만듭니다.
# Create the Azure AD application
serverApplicationId=$(az ad app create \
--display-name "${aksname}Server" \
--identifier-uris "https://${aksname}Server" \
--query appId -o tsv)
# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All
이제 az ad sp create 명령을 사용하여 서버 앱에 대한 서비스 주체를 만듭니 다. 이 서비스 주체는 Azure 플랫폼 내에서 자신을 인증하는 데 사용됩니다. 그런 다음 az ad sp credential reset 명령을 사용하여 서비스 주체 비밀을 가져와서 다음 단계 중 하나에서 사용할 serverApplicationSecret이라는 변수에 할당합니다.
# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId
# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
--name $serverApplicationId \
--credential-description "AKSPassword" \
--query password -o tsv)
Microsoft Entra 서비스 주체는 다음 작업을 수행할 수 있는 권한이 필요합니다.
- 디렉터리 데이터 읽기
- 로그인 및 사용자 프로필 읽기
az ad app permission add 명령을 사용하여 다음 권한을 할당합니다.
az ad app permission add \
--id $serverApplicationId \
--api 00000003-0000-0000-c000-000000000000 \
--api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role
마지막으로, az ad app permission grant 명령을 사용하여 서버 애플리케이션에 대한 이전 단계에서 할당된 사용 권한을 부여 합니다. 현재 계정이 테넌트 관리자가 아닌 경우 이 단계가 실패합니다. 또한 az ad app permission admin-consent를 사용하여 관리 동의가 필요할 수 있는 정보를 요청하려면 Microsoft Entra 애플리케이션에 대한 권한을 추가해야 합니다.
az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id $serverApplicationId
Microsoft Entra 클라이언트 구성 요소 만들기
두 번째 Microsoft Entra 애플리케이션은 사용자가 Kubernetes CLI(kubectl)를 사용하여 AKS 클러스터에 로그할 때 사용됩니다. 이 클라이언트 애플리케이션은 사용자의 인증 요청을 받아 자격 증명 및 권한을 확인합니다. az ad app create 명령을 사용하여 클라이언트 구성 요소에 대한 Microsoft Entra 앱을 만듭니 다.
clientApplicationId=$(az ad app create \
--display-name "${aksname}Client" \
--native-app \
--reply-urls "https://${aksname}Client" \
--query appId -o tsv)
az ad sp create 명령을 사용하여 클라이언트 애플리케이션에 대한 서비스 주체를 만듭니 다.
az ad sp create --id $clientApplicationId
az ad app show 명령을 사용하여 두 앱 구성 요소 간 인증 흐름을 허용하도록 서버 앱의 oAuth2 ID를 가져옵니다. 이 oAuth2 ID는 다음 단계에서 사용됩니다.
oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)
az ad app permission add 명령을 사용하여 oAuth2 통신 흐름을 사용하도록 클라이언트 애플리케이션 및 서버 애플리케이션 구성 요소에 대한 권한을 추가 합니다. 그런 다음, az ad app permission grant 명령을 사용하여 서버 애플리케이션과 통신하도록 클라이언트 애플리케이션에 대한 권한을 부여 합니다.
az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId
클러스터 배포
이제 두 개의 Microsoft Entra 애플리케이션을 만들어 AKS 클러스터 자체를 만듭니다. 먼저, az group create 명령을 사용하여 리소스 그룹을 만듭니다. 다음 예제에서는 EastUS 지역에 리소스 그룹을 만듭니다.
클러스터용 리소스 그룹을 만듭니다.
az group create --name myResourceGroup --location EastUS
az account show 명령을 사용하여 Azure 구독의 테넌트 ID를 가져옵니다. 그런 다음, az aks create 명령을 사용하여 AKS 클러스터를 만듭니다. AKS 클러스터를 만드는 명령은 서버 및 클라이언트 애플리케이션 ID, 서버 애플리케이션 서비스 주체 비밀 및 테넌트 ID를 제공합니다.
tenantId=$(az account show --query tenantId -o tsv)
az aks create \
--resource-group myResourceGroup \
--name $aksname \
--node-count 1 \
--generate-ssh-keys \
--aad-server-app-id $serverApplicationId \
--aad-server-app-secret $serverApplicationSecret \
--aad-client-app-id $clientApplicationId \
--aad-tenant-id $tenantId
마지막으로, az aks get-credentials 명령을 사용하여 클러스터 관리자 자격 증명을 가져옵니다. 다음 단계 중 하나에서 일반 사용자 클러스터 자격 증명을 가져와서 Microsoft Entra 인증 흐름이 작동하는지 확인합니다.
az aks get-credentials --resource-group myResourceGroup --name $aksname --admin
Kubernetes RBAC 바인딩 만들기
AKS 클러스터에서 Microsoft Entra 계정을 사용하려면 역할 바인딩 또는 클러스터 역할 바인딩을 만들어야 합니다. 역할은 부여할 권한을 정의하고 바인딩은 원하는 사용자에게 적용합니다. 이러한 할당은 지정된 네임스페이스 또는 전체 클러스터에 적용할 수 있습니다. 자세한 내용은 Kubernetes RBAC 권한 부여 사용을 참조하세요.
az ad signed-in-user show 명령을 사용하여 현재 로그인한 사용자의 UPN(사용자 계정 이름)을 가져옵니다. 이 사용자 계정은 다음 단계에서 Microsoft Entra 통합에 사용할 수 있습니다.
az ad signed-in-user show --query userPrincipalName -o tsv
Important
Kubernetes RBAC 바인딩을 부여한 사용자가 동일한 Microsoft Entra 테넌트에 있는 경우 userPrincipalName에 따라 권한을 할당합니다. 사용자가 다른 Microsoft Entra 테넌트에 있는 경우 objectId 속성을 대신 쿼리하고 사용합니다.
명명 basic-azure-ad-binding.yaml 된 YAML 매니페스트를 만들고 다음 내용을 붙여넣습니다. 마지막 줄에서 userPrincipalName_or_objectId를 이전 명령의 UPN 또는 개체 ID 출력으로 바꿉니다.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: contoso-cluster-admins
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: User
name: userPrincipalName_or_objectId
kubectl apply 명령을 사용하여 ClusterRoleBinding을 만들고 YAML 매니페스트의 파일 이름을 지정합니다.
kubectl apply -f basic-azure-ad-binding.yaml
Microsoft Entra ID를 사용하여 클러스터에 액세스
이제 AKS 클러스터에 대한 Microsoft Entra 인증의 통합을 테스트해 보겠습니다. 일반 사용자 자격 증명을 kubectl 사용하도록 구성 컨텍스트를 설정합니다. 이 컨텍스트는 Microsoft Entra ID를 통해 모든 인증 요청을 다시 전달합니다.
az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing
이제 kubectl get Pods 명령을 사용하여 모든 네임스페이스에서 Pod를 봅니다.
kubectl get pods --all-namespaces
웹 브라우저를 사용하여 Microsoft Entra 자격 증명을 사용하여 인증하라는 로그인 프롬프트가 표시됩니다. 인증된 후에는 다음 예제 출력과 같이 kubectl 명령이 AKS 클러스터에 Pod를 표시합니다.
kubectl get pods --all-namespaces
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BYMK7UXVD to authenticate.
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-754f947b4-2v75r 1/1 Running 0 23h
kube-system coredns-754f947b4-tghwh 1/1 Running 0 23h
kube-system coredns-autoscaler-6fcdb7d64-4wkvp 1/1 Running 0 23h
kube-system heapster-5fb7488d97-t5wzk 2/2 Running 0 23h
kube-system kube-proxy-2nd5m 1/1 Running 0 23h
kube-system kube-svc-redirect-swp9r 2/2 Running 0 23h
kube-system kubernetes-dashboard-847bb4ddc6-trt7m 1/1 Running 0 23h
kube-system metrics-server-7b97f9cd9-btxzz 1/1 Running 0 23h
kube-system tunnelfront-6ff887cffb-xkfmq 1/1 Running 0 23h
수신된 kubectl 인증 토큰이 캐시됩니다. 토큰이 만료되었거나 Kubernetes 구성 파일이 다시 만들어지는 경우에만 로그인하라는 메시지가 다시 표시됩니다.
다음 예제 출력과 같이 웹 브라우저를 사용하여 성공적으로 로그인한 후 권한 부여 오류 메시지가 표시되면 다음과 같은 가능한 문제를 검사.
error: You must be logged in to the server (Unauthorized)
- 사용자 계정이 동일한 Microsoft Entra 테넌트에 있는지 여부에 따라 적절한 개체 ID 또는 UPN을 정의했습니다.
- 사용자가 200개 이상의 그룹의 구성원이 아닙니다.
- 서버에 대한 애플리케이션 등록에 정의된 비밀은 다음을 사용하여 구성된 값과 일치합니다.
--aad-server-app-secret - 한 번에 하나의 kubectl 버전만 컴퓨터에 설치되어 있는지 확인합니다. 버전이 충돌하면 권한 부여 중에 문제가 발생할 수 있습니다. 최신 버전을 설치하려면 az aks install-cli를 사용합니다.
Microsoft Entra 통합에서 AKS 관리형 Microsoft Entra ID로의 마이그레이션에 대한 질문과 대답
1. 마이그레이션 계획은 무엇인가요?
Microsoft Entra Integration(레거시)은 2023년 6월 1일에 더 이상 사용되지 않습니다. 이 날짜 이후에는 Microsoft Entra ID(레거시)를 사용하여 새 클러스터를 만들 수 없습니다. 2023년 8월 1일부터 모든 Microsoft Entra Integration(레거시) AKS 클러스터를 AKS 관리형 Microsoft Entra ID로 자동으로 마이그레이션합니다. 영향을 받은 구독 관리자에게 격주로 알림 이메일을 보내 마이그레이션을 상기시킵니다.
2. 아무 조치도 취하지 않으면 어떻게 됩니까?
Microsoft Entra Integration(레거시) AKS 클러스터는 2023년 6월 1일 이후에도 계속 작동합니다. 2023년 8월 1일부터 클러스터를 AKS 관리형 Microsoft Entra ID로 자동으로 마이그레이션합니다. 마이그레이션하는 동안 API 서버 가동 중지 시간이 발생할 수 있습니다.
kubeconfig 콘텐츠는 마이그레이션 후에 변경됩니다. 를 사용하여 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name>새 자격 증명을 kubeconfig 파일에 병합해야 합니다.
AKS 클러스터를 AKS 관리 Microsoft Entra ID로 8월 1일 이전에 수동으로 업데이트하는 것이 좋습니다. 이렇게 하면 업무 외 시간에 가동 중지 시간이 더 편리할 때 가동 중지 시간을 관리할 수 있습니다.
3. 수동 마이그레이션 후에도 여전히 알림 전자 메일을 받는 이유는 무엇인가요?
전자 메일을 보내는 데 며칠이 걸립니다. 전자 메일 보내기 프로세스를 시작하기 전에 클러스터가 마이그레이션되지 않은 경우에도 알림을 받을 수 있습니다.
4. 클러스터를 AKS 관리형 Microsoft Entra ID로 마이그레이션할지 여부를 어떻게 검사 수 있나요?
명령을 사용하여 az aks show AKS 클러스터가 AKS 관리 Microsoft Entra ID로 마이그레이션되어 있는지 확인합니다.
az aks show -g <RGName> -n <ClusterName> --query "aadProfile"
클러스터가 AKS 관리형 Microsoft Entra ID를 사용하는 경우 출력은 다음과 managed 같습니다 true. 예시:
{
"adminGroupObjectIDs": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"adminUsers": null,
"clientAppId": null,
"enableAzureRbac": null,
"managed": true,
"serverAppId": null,
"serverAppSecret": null,
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
다음 단계
이 문서에 표시된 명령이 포함된 전체 스크립트는 [AKS 샘플 리포지토리의 Microsoft Entra 통합 스크립트][complete-script]를 참조하세요.
Microsoft Entra 사용자 및 그룹을 사용하여 클러스터 리소스에 대한 액세스를 제어하려면 AKS에서 Kubernetes 역할 기반 액세스 제어 및 Microsoft Entra ID를 사용하여 클러스터 리소스에 대한 액세스 제어를 참조하세요.
Kubernetes 클러스터를 보호하는 방법에 대한 자세한 내용은 AKS에 대한 액세스 및 ID 옵션을 참조하세요.)
ID 및 리소스 제어에 대한 모범 사례는 AKS의 인증 및 권한 부여 모범 사례를 참조 하세요.