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