kubelogin을 사용하여 Azure Kubernetes Service에서 사용자 인증
Azure의 kubelogin 플러그 인은 Microsoft Entra 인증을 구현하는 클라이언트 이동 자격 증명 플러그 인입니다. kubelogin 플러그 인은 kubectl 명령줄 도구에서 사용할 수 없는 기능을 제공합니다.
Microsoft Entra ID와 통합되고 Kubernetes 버전 1.24 이상을 실행하는 AKS(Azure Kubernetes Service) 클러스터는 자동으로 kubelogin 형식을 사용합니다.
이 문서에서는 AKS에서 지원되는 모든 Microsoft Entra 인증 방법에 kubelogin을 사용하는 방법에 대한 개요 및 예제를 제공합니다.
제한 사항
- Microsoft Entra JSON 웹 토큰(JWT) 클레임에 최대 200개의 그룹을 포함할 수 있습니다. 그룹이 200개 이상인 경우 애플리케이션 역할을 사용하는 것이 좋습니다.
- Microsoft Entra ID에서 만든 그룹은 표시 이름이 아니라 ObjectID 값에 의해서만 포함됩니다.
sAMAccountName명령은 온-프레미스 Windows Server Active Directory에서 동기화된 그룹에만 사용할 수 있습니다. - AKS에서 서비스 주체 인증 방법은 이전 버전의 Azure Active Directory가 아니라, 관리형 Microsoft Entra ID로만 작동합니다.
- Microsoft Entra 조건부 액세스 정책이 Microsoft Entra 테넌트에 설정된 경우 디바이스 코드 인증 방법이 작동하지 않습니다. 이 시나리오에서는 웹 브라우저 대화형 인증을 사용합니다.
인증 작동 방법
kubelogin과 상호 작용할 때는 대부분 convert-kubeconfig 하위 명령을 사용합니다. 하위 명령은 --kubeconfig 또는 KUBECONFIG 환경 변수에 지정된 kubeconfig 파일을 사용하여 지정된 인증 방법에 따라 최종 kubeconfig 파일을 exec 형식으로 변환합니다.
kubelogin에서 구현하는 인증 방법은 Microsoft Entra OAuth 2.0 토큰 부여 흐름입니다. 일반적으로 kubelogin 하위 명령에서는 다음 매개 변수 플래그를 사용합니다. 일반적으로 이러한 플래그는 AKS에서 kubeconfig 파일을 가져올 때 사용할 준비가 됩니다.
--tenant-id: Microsoft Entra 테넌트 ID입니다.--client-id: 공용 클라이언트 애플리케이션의 애플리케이션 ID입니다. 이 클라이언트 앱은 디바이스 코드, 웹 브라우저 대화형 및 OAuth 2.0 ROPC(리소스 소유자 암호 자격 증명)(워크플로 ID) 로그인 메서드에서만 사용됩니다.--server-id: 웹앱 또는 리소스 서버의 애플리케이션 ID입니다. 이 리소스에 토큰이 발급됩니다.
참고 항목
각 인증 방법에서 토큰은 파일 시스템에 캐시되지 않습니다.
인증 방법
다음 섹션에서는 지원되는 인증 방법 및 그 사용 방법에 대해 설명합니다.
- 디바이스 코드
- Azure CLI
- 웹 브라우저 대화형
- 서비스 주체
- 관리 ID
- 워크로드 ID
디바이스 코드
디바이스 코드는 convert-kubeconfig 하위 명령의 기본 인증 방법입니다. -l devicecode 매개 변수는 선택 사항입니다. 이 인증 방법은 사용자가 브라우저 세션에서 로그인할 수 있도록 디바이스 코드를 묻는 메시지를 표시합니다.
kubelogin 및 exec 플러그 인이 도입되기 전에 kubectl의 Azure 인증 방법은 디바이스 코드 흐름만 지원했습니다. 이 방법은 접두사가 spn:인 audience 클레임이 있는 토큰을 생성하는 이전 버전의 라이브러리를 사용했습니다. OBO(On-Behalf-Of) 흐름을 사용하는 AKS 관리형 Microsoft Entra ID와 호환되지 않습니다. convert-kubeconfig 하위 명령을 실행하면 kubelogin이 대상 그룹 클레임에서 spn: 접두사를 제거합니다.
요구 사항에 이전 버전의 기능 사용이 포함된 경우 --legacy 인수를 추가합니다. 이전 버전의 Azure Active Directory 클러스터에서 kubeconfig 파일을 사용하는 경우 kubelogin이 자동으로 --legacy 플래그를 추가합니다.
이 로그인 방법에서는 액세스 토큰 및 새로 고침 토큰이 ${HOME}/.kube/cache/kubelogin 디렉터리에 캐시됩니다. 이 경로를 재정의하려면 --token-cache-dir 매개 변수를 포함합니다.
AKS Microsoft Entra 통합 클러스터에서 Kubernetes 1.24 이전 버전을 사용하는 경우 다음 명령을 실행하여 kubeconfig 파일 형식을 수동으로 변환해야 합니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
캐시된 토큰을 정리하려면 다음 명령을 실행합니다.
kubelogin remove-tokens
참고 항목
Microsoft Entra 테넌트에 조건부 액세스 정책이 구성된 경우 디바이스 코드 로그인 방법이 작동하지 않습니다. 이 시나리오에서는 웹 브라우저 대화형 메서드를 사용합니다.
Azure CLI
Azure CLI 인증 방법은 Azure CLI가 설정하는 로그인 컨텍스트를 사용하여 액세스 토큰을 가져옵니다. 토큰은 동일한 Microsoft Entra 테넌트를 az login으로 발급됩니다. kubelogin은 토큰이 이미 Azure CLI에서 관리되기 때문에 토큰 캐시 파일에 토큰을 쓰지 않습니다.
참고 항목
이 인증 방법은 AKS 관리형 Microsoft Entra ID에로만 작동합니다.
다음 예제에서는 Azure CLI 메서드를 사용하여 인증하는 방법을 보여 줍니다.
az login
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l azurecli
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
Azure CLI 구성 디렉터리가 ${HOME} 디렉터리 외부에 있는 경우 --azure-config-dir 매개 변수와 convert-kubeconfig 하위 명령을 사용합니다. 이 명령은 환경 변수가 구성된 kubeconfig 파일을 생성합니다. kubectl 명령을 실행할 때 AZURE_CONFIG_DIR 환경 변수를 이 디렉터리로 설정하여 동일한 구성을 가져올 수 있습니다.
웹 브라우저 대화형
웹 브라우저 대화형 인증 방법은 자동으로 웹 브라우저를 열어 사용자를 로그인합니다. 사용자가 인증되면 브라우저에서 확인된 자격 증명을 사용하여 로컬 웹 서버로 리디렉션됩니다. 이 인증 방법은 조건부 액세스 정책을 준수합니다.
이 메서드를 사용하여 인증하면 액세스 토큰이 ${HOME}/.kube/cache/kubelogin 디렉터리에 캐시됩니다. --token-cache-dir 매개 변수를 사용하여 이 경로를 재정의할 수 있습니다.
전달자 토큰
다음 예제에서는 웹 브라우저 대화형 흐름에서 전달자 토큰을 사용하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l interactive
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
소유 증명 토큰
다음 예제에서는 웹 브라우저 대화형 흐름에서 PoP(소유 증명) 토큰을 사용하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
서비스 사용자
이 인증 방법은 서비스 주체를 사용하여 사용자를 로그인합니다. 환경 변수를 설정하거나 명령줄 인수에서 자격 증명을 사용하여 자격 증명을 제공할 수 있습니다. 사용할 수 있는 지원되는 자격 증명은 암호 또는 PFX(개인 정보 교환) 클라이언트 인증서입니다.
이 메서드를 사용하기 전에 다음 제한 사항을 고려합니다.
- 이 메서드는 관리형 Microsoft Entra ID에로만 작동합니다.
- 서비스 주체는 최대 200개 Microsoft Entra 그룹의 구성원일 수 있습니다.
환경 변수
다음 예제에서는 환경 변수를 사용하여 클라이언트 암호를 설정하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
그런 후 다음 명령을 실행합니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn
export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
명령줄 인수
다음 예제에서는 명령줄 인수에서 클라이언트 암호를 설정하는 방법을 보여줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
Warning
명령줄 인수 메서드는 kubeconfig 파일에 비밀을 저장합니다.
클라이언트 인증서
다음 예제에서는 클라이언트 인증서를 사용하여 클라이언트 암호를 설정하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
그런 후 다음 명령을 실행합니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn
export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
PoP 토큰 및 환경 변수
다음 예제에서는 환경 변수에서 가져오는 클라이언트 암호를 사용하는 PoP 토큰을 설정하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
관리 ID
Microsoft Entra 인증을 지원하는 리소스에 연결하는 애플리케이션에 관리 ID 인증 방법을 사용합니다. 예제에는 Azure 가상 머신, 가상 머신 확장 집합 또는 Azure Cloud Shell과 같은 Azure 리소스에 액세스하는 것이 포함됩니다.
기본 관리 ID
다음 예제에서는 기본 관리 ID를 사용하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l msi
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
특정 ID
다음 예제에서는 특정 ID와 함께 관리 ID를 사용하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
워크로드 ID
워크로드 ID 인증 방법은 Microsoft Entra와 페더레이션된 ID 자격 증명을 사용하여 AKS 클러스터에 대한 액세스를 인증합니다. 이 메서드는 Microsoft Entra 통합 인증을 사용합니다. 다음 환경 변수를 설정하면 작동합니다.
AZURE_CLIENT_ID: 워크로드 ID와 페더레이션되는 Microsoft Entra 애플리케이션 ID입니다.AZURE_TENANT_ID: Microsoft Entra 테넌트 ID입니다.AZURE_FEDERATED_TOKEN_FILE: Kubernetes 프로젝션된 서비스 계정(JWT) 토큰과 같은 워크로드 ID의 서명된 어설션을 포함하는 파일입니다.AZURE_AUTHORITY_HOST: Microsoft Entra 인증 기관의 기준 URL입니다. 예:https://login.microsoftonline.com/.
워크로드 ID를 사용하면 외부 시스템에 서비스 주체 자격 증명을 저장하지 않고도 GitHub 또는 ArgoCD와 같은 CI/CD 시스템에서 Kubernetes 클러스터에 액세스할 수 있습니다. GitHub에서 OIDC(OpenID Connect) 페더레이션을 구성하려면 OIDC 페더레이션 예제를 참조하세요.
다음 예제에서는 워크로드 ID를 사용하는 방법을 보여 줍니다.
export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig -l workloadidentity
이 kubectl 명령을 실행하여 노드 정보를 가져옵니다.
kubectl get nodes
AKS에서 kubelogin을 사용하는 방법
AKS는 자사 Microsoft Entra 애플리케이션 쌍을 사용합니다. 이러한 애플리케이션 ID는 모든 환경에서 동일합니다.
서버 쪽에서 사용하는 AKS Microsoft Entra 서버 애플리케이션 ID는 6dae42f8-4368-4678-94ff-3960e28e3630입니다. AKS 클러스터에 액세스하는 액세스 토큰을 이 애플리케이션에 발급해야 합니다. 대부분의 kubelogin 인증 방법에는 --server-id와 kubelogin get-token을 함께 사용해야 합니다.
kubelogin에서 사용자를 대신하여 공용 클라이언트 인증을 수행하는 데 사용하는 AKS Microsoft Entra 클라이언트 애플리케이션 ID는 80faf920-1908-4b52-b5ef-a8e7bedfc67a입니다. 클라이언트 애플리케이션 ID는 디바이스 코드 및 웹 브라우저 대화형 인증 방법에 사용됩니다.
관련 콘텐츠
- AKS 관리형 Microsoft Entra ID 통합 방법 문서에서 AKS를 Microsoft Entra ID와 통합하는 방법에 대해 알아봅니다.
- AKS에서 관리 ID를 시작하려면 AKS에서 관리 ID 사용을 참조하세요.
- AKS에서 워크로드 ID를 시작하려면 AKS에서 워크로드 ID 사용을 참조하세요.