AKS(Azure Kubernetes Service)에서 Microsoft Entra 워크로드 ID 사용

아티클
03/11/2024

AKS(Azure Kubernetes Services) 클러스터에 배포된 워크로드에는 Azure Key Vault 및 Microsoft Graph와 같은 Microsoft Entra 보호 리소스에 액세스하려면 Microsoft Entra 애플리케이션 자격 증명 또는 관리 ID가 필요합니다. Microsoft Entra 워크로드 ID는 Kubernetes의 네이티브 기능과 통합되어 외부 ID 공급자와 페더레이션됩니다.

Microsoft Entra 워크로드 ID는 Pod가 Kubernetes ID(즉, 서비스 계정)를 사용할 수 있도록 하는 서비스 계정 토큰 볼륨 프로젝션을 사용합니다. Kubernetes 토큰이 발급되고 OIDC 페더레이션을 통해 Kubernetes 애플리케이션이 주석이 달린 서비스 계정을 기반으로 Microsoft Entra ID를 통해 Azure 리소스에 안전하게 액세스할 수 있습니다.

Microsoft Entra 워크로드 ID는 애플리케이션 등록을 사용하는 경우 Azure ID 클라이언트 라이브러리 및 MSAL(Microsoft 인증 라이브러리) 컬렉션과 특히 잘 작동합니다. 워크로드는 이러한 라이브러리를 사용하여 Azure 클라우드 리소스를 원활하게 인증하고 액세스할 수 있습니다.

이 문서는 이 새로운 인증 기능을 이해하는 데 도움이 되며, Microsoft Entra Pod 관리 ID에서 프로젝트 전략 및 잠재적 마이그레이션을 계획하는 데 사용할 수 있는 옵션을 검토합니다.

참고 항목

모든 단계를 수동으로 구성하는 대신 일부 단계를 자동으로 구성하는 데 도움이 되는 서비스 커넥터라는 또 다른 구현이 있습니다. 참고 항목: 서비스 커넥터란?

종속성

AKS는 버전 1.22 이상에서 Microsoft Entra 워크로드 ID를 지원합니다.
Azure CLI 버전, 2.47.0 이상. az --version을 실행하여 버전을 찾고 az upgrade를 실행하여 버전을 업그레이드합니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.

Azure ID 클라이언트 라이브러리

Azure ID 클라이언트 라이브러리에서 다음 방식 중 하나를 선택합니다.

WorkloadIdentityCredential을(를) 사용하려고 시도하는 DefaultAzureCredential을(를) 사용합니다.
WorkloadIdentityCredential을 포함하는 ChainedTokenCredential 인스턴스를 만듭니다.
직접 WorkloadIdentityCredential 사용

다음 표에는 각 언어 에코시스템의 클라이언트 라이브러리에 필요한 최소 패키지 버전이 나와 있습니다.

에코시스템	라이브러리	최소 버전
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Go	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

다음 코드 샘플에서는 DefaultAzureCredential이 사용됩니다. 이 자격 증명 형식은 Azure Workload Identity 변형 웹후크에 의해 삽입된 환경 변수를 사용하여 Azure Key Vault에 인증합니다.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_URL");
string secretName = Environment.GetEnvironmentVariable("SECRET_NAME");

var client = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

#include <cstdlib>
#include <azure/identity.hpp>
#include <azure/keyvault/secrets/secret_client.hpp>

using namespace Azure::Identity;
using namespace Azure::Security::KeyVault::Secrets;

int main()
{
  const char* keyVaultUrl = std::getenv("KEYVAULT_URL");
  const char* secretName = std::getenv("SECRET_NAME");
  auto credential = std::make_shared<DefaultAzureCredential>();

  SecretClient client(keyVaultUrl, credential);
  Secret secret = client.GetSecret(secretName).Value;

  return 0;
}

package main

import (
	"context"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
    "k8s.io/klog/v2"
)

func main() {
	keyVaultUrl := os.Getenv("KEYVAULT_URL")
	secretName := os.Getenv("SECRET_NAME")

	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		klog.Fatal(err)
	}

	client, err := azsecrets.NewClient(keyVaultUrl, credential, nil)
	if err != nil {
		klog.Fatal(err)
	}

	secret, err := client.GetSecret(context.Background(), secretName, "", nil)
	if err != nil {
		klog.ErrorS(err, "failed to get secret", "keyvault", keyVaultUrl, "secretName", secretName)
		os.Exit(1)
	}
}

import java.util.Map;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.DefaultAzureCredential;

public class App {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        String keyVaultUrl = env.get("KEYVAULT_URL");
        String secretName = env.get("SECRET_NAME");

        SecretClient client = new SecretClientBuilder()
                .vaultUrl(keyVaultUrl)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();
        KeyVaultSecret secret = client.getSecret(secretName);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const main = async () => {
    const keyVaultUrl = process.env["KEYVAULT_URL"];
    const secretName = process.env["SECRET_NAME"];

    const credential = new DefaultAzureCredential();
    const client = new SecretClient(keyVaultUrl, credential);

    const secret = await client.getSecret(secretName);
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

import os

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def main():
    keyvault_url = os.getenv('KEYVAULT_URL', '')
    secret_name = os.getenv('SECRET_NAME', '')

    client = SecretClient(vault_url=keyvault_url, credential=DefaultAzureCredential())
    secret = client.get_secret(secret_name)

if __name__ == '__main__':
    main()

MSAL(Microsoft 인증 라이브러리)

다음 클라이언트 라이브러리는 필요한 최소 버전입니다.

에코시스템	라이브러리	이미지	예시	Windows 있음
.NET	Microsoft Authentication Library-for-dotnet	`ghcr.io/azure/azure-workload-identity/msal-net:latest`	링크	예
Go	Microsoft Authentication Library-for-go	`ghcr.io/azure/azure-workload-identity/msal-go:latest`	링크	예
Java	Microsoft Authentication Library-for-java	`ghcr.io/azure/azure-workload-identity/msal-java:latest`	링크	아니요
JavaScript	Microsoft Authentication Library-for-js	`ghcr.io/azure/azure-workload-identity/msal-node:latest`	링크	아니요
Python	Microsoft Authentication Library-for-python	`ghcr.io/azure/azure-workload-identity/msal-python:latest`	링크	아니요

제한 사항

관리 ID당 페더레이션 ID 자격 증명은 20개만 가질 수 있습니다.
페더레이션 ID 자격 증명이 처음 추가된 후 전파되는 데 몇 초 정도 걸립니다.
오픈 소스 프로젝트인 Virtual Kubelet을 기반으로 하는 가상 노드 추가 기능은 지원되지 않습니다.
이러한 지역의 사용자 할당 관리 ID에서는 페더레이션된 ID 자격 증명 만들기가 지원되지 않습니다.

작동 방식

이 보안 모델에서 AKS 클러스터는 토큰 발급자 역할을 하며, Microsoft Entra ID는 OpenID Connect를 사용하여 퍼블릭 서명 키를 검색하고 서비스 계정 토큰의 신뢰성을 확인한 후 Microsoft Entra ID 토큰으로 교환합니다. 워크로드는 Azure ID 클라이언트 라이브러리 또는 Microsoft 인증 라이브러리를 사용하여 해당 볼륨에 프로젝션된 서비스 계정 토큰을 Microsoft Entra 토큰으로 교환할 수 있습니다.

AKS 워크로드 ID 보안 모델의 다이어그램

다음 표에서는 Microsoft Entra 워크로드 ID에 필요한 OIDC 발급자 엔드포인트를 설명합니다.

엔드포인트	설명
`{IssuerURL}/.well-known/openid-configuration`	OIDC 검색 문서라고도 합니다. 여기에는 발급자의 구성에 대한 메타데이터가 포함됩니다.
`{IssuerURL}/openid/v1/jwks`	여기에는 Microsoft Entra ID가 서비스 계정 토큰의 신뢰성을 확인하는 데 사용하는 공개 서명 키가 포함됩니다.

다음 다이어그램에는 OpenID Connect를 사용하는 인증 순서가 요약되어 있습니다.

AKS 워크로드 ID OIDC 인증 순서의 다이어그램

웹후크 인증서 자동 회전

다른 웹후크 추가 기능과 마찬가지로 인증서는 클러스터 인증서 자동 회전 작업에 의해 회전됩니다.

서비스 계정 레이블 및 주석

Microsoft Entra 워크로드 ID는 서비스 계정과 관련된 다음 매핑을 지원합니다.

하나의 서비스 계정이 하나의 Microsoft Entra 개체를 참조하는 일대일 매핑.
여러 서비스 계정이 동일한 Microsoft Entra 개체를 참조하는 다대일 매핑.
하나의 서비스 계정이 클라이언트 ID 주석을 변경하여 여러 Microsoft Entra 개체를 참조하는 일대다 매핑. 자세한 내용은 Kubernetes Service 계정으로 복수 ID를 페더레이션하는 방법을 참조하세요.

참고 항목

서비스 계정 주석이 업데이트된 경우 변경 내용을 적용하려면 Pod를 다시 시작해야 합니다.

Microsoft Entra Pod 관리 ID를 사용한 경우 서비스 계정을 Azure ID로 간주합니다. 단, 서비스 계정은 CRD(Custom Resource Definition)가 아닌 핵심 Kubernetes API에 속합니다. 다음은 제공되는 레이블 및 주석 목록을 설명하며 이는 서비스 계정 토큰을 Microsoft Entra 액세스 토큰으로 교환할 때 동작을 구성하는 데 사용할 수 있습니다.

서비스 계정 주석

모든 주석은 선택 사항입니다. 주석을 지정하지 않으면 기본값이 사용됩니다.

주석	설명	기본값
`azure.workload.identity/client-id`	Microsoft Entra 애플리케이션을 나타냅니다. Pod와 함께 사용할 클라이언트 ID입니다.
`azure.workload.identity/tenant-id`	Azure AD 애플리케이션이 등록되는 Microsoft Entra 애플리케이션이 등록되었습니다.	AZURE_TENANT_ID 환경 변수가 `azure-wi-webhook-config` ConfigMap에서 추출되었습니다.
`azure.workload.identity/service-account-token-expiration`	프로젝션된 서비스 계정 토큰에 대한 `expirationSeconds` 필드를 나타냅니다. 서비스 계정 토큰을 새로 고치는 동안 오류로 인해 발생하는 가동 중지 시간을 방지하기 위해 구성하는 선택적 필드입니다. Kubernetes 서비스 계정 토큰 만료는 Microsoft Entra 토큰과 관련이 없습니다. Microsoft Entra 토큰은 발급된 후 24시간 후에 만료됩니다.	3600 지원되는 범위는 3600~86400입니다.

Pod 레이블

참고 항목

워크로드 ID를 사용하는 애플리케이션의 경우 워크로드 ID를 사용해야 하는 Pod에 일관되고 신뢰할 수 있는 동작을 제공하기 위해 워크로드 ID를 장애 닫기 시나리오로 이동하려면 AKS의 Pod 사양에 azure.workload.identity/use: "true" 레이블을 추가해야 합니다. 그렇지 않으면 Pod가 다시 시작된 후 실패합니다.

Label	설명	권장 값	Required
`azure.workload.identity/use`	이 레이블은 Pod 템플릿 사양에 필요합니다. 이 레이블이 있는 Pod만 azure-workload-identity 변경 허용 웹후크에 의해 변경되어 Azure 특정 환경 변수 및 예상 서비스 계정 토큰 볼륨을 삽입합니다.	true	예

Pod 주석

모든 주석은 선택 사항입니다. 주석을 지정하지 않으면 기본값이 사용됩니다.

주석	설명	기본값
`azure.workload.identity/service-account-token-expiration`	프로젝션된 서비스 계정 토큰의 `expirationSeconds` 필드를 나타냅니다. 서비스 계정 토큰을 새로 고치는 동안 오류로 인해 발생하는 가동 중지 시간을 방지하기 위해 구성하는 선택적 필드입니다. Kubernetes 서비스 계정 토큰 만료는 Microsoft Entra 토큰과 관련이 없습니다. Microsoft Entra 토큰은 발급된 후 24시간 후에 만료됩니다. ¹	3600 지원되는 범위는 3600~86400입니다.
`azure.workload.identity/skip-containers`	프로젝션된 서비스 계정 볼륨 추가를 건너뛸 세미콜론으로 구분된 컨테이너 목록을 나타냅니다. 예: `container1;container2`.	기본적으로 서비스 계정에 `azure.workload.identity/use: true` 레이블이 지정된 경우 프로젝션된 서비스 계정 토큰 볼륨이 모든 컨테이너에 추가됩니다.
`azure.workload.identity/inject-proxy-sidecar`	프록시 init 컨테이너 및 프록시 사이드카를 Pod에 삽입합니다. 프록시 사이드카는 IMDS에 대한 토큰 요청을 가로채고 페더레이션 ID 자격 증명이 있는 사용자를 대신하여 Microsoft Entra 토큰을 획득하는 데 사용됩니다.	true
`azure.workload.identity/proxy-sidecar-port`	프록시 사이드카의 포트를 나타냅니다.	8000

¹ 서비스 계정에도 주석이 추가된 경우 우선 적용됩니다.

워크로드 ID로 마이그레이션하는 방법

이미 Pod 관리 ID를 실행 중인 클러스터에서는 워크로드 ID를 두 가지 방법 중 하나로 사용하도록 구성할 수 있습니다. 첫 번째 옵션을 사용하면 현재 Pod 관리 ID에 대해 구현한 것과 동일한 구성을 사용할 수 있습니다. 네임스페이스 내의 서비스 계정에 ID를 주석으로 추가하면 워크로드 ID가 주석을 Pod에 삽입할 수 있습니다.

두 번째 옵션은 최신 버전의 Azure ID 클라이언트 라이브러리를 사용하도록 애플리케이션을 다시 작성하는 것입니다.

마이그레이션 프로세스를 간소화하고 용이하게 하기 위해 애플리케이션이 만드는 IMDS 트랜잭션을 OIDC(OpenID Connect)로 변환하는 마이그레이션 사이드카를 개발했습니다. 마이그레이션 사이드카는 장기적인 솔루션이 아니라 워크로드 ID에서 빠르게 시작하고 실행할 수 있는 방법입니다. 애플리케이션 내에서 마이그레이션 사이드카를 실행하면 애플리케이션 IMDS 트랜잭션이 OIDC로 프록시됩니다. 다른 방법은 OIDC 인증을 지원하는 지원되는 버전의 Azure Identity 클라이언트 라이브러리로 업그레이드하는 것입니다.

다음 표에는 워크로드 ID에 대한 마이그레이션 또는 배포 권장 사항이 요약되어 있습니다.

시나리오	설명
새 클러스터 또는 기존 클러스터 배포는 Azure ID 클라이언트 라이브러리의 지원되는 버전을 실행합니다.	마이그레이션 단계가 필요하지 않습니다. 샘플 배포 리소스: - 새 클러스터에서 워크로드 ID 배포 및 구성 - 자습서: AKS에서 애플리케이션과 함께 워크로드 ID 사용
새 클러스터 또는 기존 클러스터 배포는 Azure ID 클라이언트 라이브러리의 지원되지 않는 버전을 실행합니다.	지원되는 버전의 Azure ID SDK를 사용하도록 컨테이너 이미지를 업데이트하거나 마이그레이션 사이드카를 사용합니다.

다음 단계

마이그레이션 옵션으로 워크로드 ID를 사용하여 인증하도록 Pod를 설정하는 방법을 알아보려면 워크로드 ID로 애플리케이션 인증 현대화를 참조하세요.
Azure Kubernetes Service 클러스터를 배포하고 워크로드 ID를 사용하도록 샘플 애플리케이션을 구성할 수 있는 AKS(Azure Kubernetes Service)의 애플리케이션에서 워크로드 ID 사용 가이드를 참조하세요.

AKS(Azure Kubernetes Service)에서 Microsoft Entra 워크로드 ID 사용

종속성

Azure ID 클라이언트 라이브러리

MSAL(Microsoft 인증 라이브러리)

제한 사항

작동 방식

웹후크 인증서 자동 회전

서비스 계정 레이블 및 주석

서비스 계정 주석

Pod 레이블

Pod 주석

워크로드 ID로 마이그레이션하는 방법

다음 단계

추가 리소스