Azure CLI(레거시)를 사용하여 AKS(Azure Kubernetes Service)와 Microsoft Entra ID 통합
Warning
이 문서에 설명된 기능인 Microsoft Entra Integration(레거시)은 2023년 6월 1일부터 사용 중지되었습니다. 현재 Microsoft Entra 통합(레거시)을 사용하여 새 클러스터를 만들 수 없습니다.
AKS에는 서버 또는 클라이언트 애플리케이션을 관리하지 않아도 되는 새롭고 향상된 AKS 관리형 Microsoft Entra ID 환경이 포함됩니다. 마이그레이션하려면 여기에 있는 지침을 따릅니다.
사용자 인증을 위해 Microsoft Entra ID를 사용하도록 AKS(Azure Kubernetes Service)를 구성할 수 있습니다. 이 구성에서는 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 인증 개요
OpenID Connect와 함께 AKS 클러스터에 Microsoft Entra 인증이 제공됩니다. OpenID Connect는 OAuth 2.0 프로토콜을 기반으로 하는 ID 계층입니다. OpenID Connect에 대한 자세한 내용은 Open ID Connect 설명서를 참조하세요.
Kubernetes 클러스터 내부에서 인증 토큰을 확인하는 데 Webhook 토큰 인증이 사용됩니다. Webhook 토큰 인증은 AKS 클러스터의 일부로 구성 및 관리됩니다. Webhook 토큰 인증에 대한 자세한 내용은 webhook 인증 설명서를 참조하세요.
참고 항목
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 바인딩 만들기
Microsoft Entra 계정을 AKS 클러스터와 함께 사용하려면 역할 바인딩 또는 클러스터 역할 바인딩을 만들어야 합니다. 역할은 부여할 사용 권한을 정의하고, 바인딩은 원하는 사용자에게 역할을 적용합니다. 이러한 할당은 주어진 네임스페이스 또는 전체 클러스터에 적용될 수 있습니다. 자세한 내용은 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를 통해 다시 모든 인증 요청을 전달합니다.
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 통합(레거시)은 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 클러스터를 8월 1일 이전에 AKS 관리형 Microsoft Entra ID로 수동으로 업데이트하는 것이 좋습니다. 이렇게 하면 업무 외 시간에 좀 더 편리할 때 가동 중지 시간을 관리할 수 있습니다.
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의 인증 및 권한 부여 모범 사례를 참조하세요.
Azure Kubernetes Service