AKS(Azure Kubernetes Service) 클러스터의 비밀 저장소 CSI 드라이버에 대한 Azure Key Vault 공급자 사용

2025-07-23

비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자를 사용하면 Azure Key Vault를 CSI 볼륨을 통해 AKS(Azure Kubernetes Service) 클러스터와 비밀 저장소로 통합할 수 있습니다.

기능

CSI 볼륨을 사용하여 Pod에 비밀, 키 및 인증서를 탑재합니다.
CSI 인라인 볼륨을 지원합니다.
단일 볼륨으로 여러 비밀 저장소 개체 탑재를 지원합니다.
SecretProviderClass CRD를 사용하여 Pod 이식성을 지원합니다.
Windows 컨테이너를 지원합니다.
Kubernetes 비밀과 동기화합니다.
탑재된 콘텐츠 및 동기화된 Kubernetes 비밀의 자동 순환을 지원합니다.

제한 사항

subPath 볼륨 탑재로 ConfigMap 또는 Secret를 사용하는 컨테이너는 비밀이 갱신될 때 자동화된 업데이트를 받지 않습니다. Kubernetes 제한 사항입니다. 변경 내용을 적용하려면 애플리케이션에서 파일 시스템의 변경 내용을 확인하거나 Pod를 다시 시작하여 변경된 파일을 다시 로드해야 합니다. 자세한 내용은 비밀 저장소 CSI 드라이버의 알려진 제한 사항을 참조하세요.
추가 기능은 노드 리소스 그룹에 명명된 azurekeyvaultsecretsprovider-xxx 관리 ID를 만들고 VMSS(Virtual Machine Scale Sets)에 자동으로 할당합니다. 이 관리 ID 또는 사용자 고유의 관리 ID를 사용하여 키 자격 증명 모음에 액세스할 수 있습니다. ID 생성을 방지할 수는 없습니다.

필수 구성 요소

Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Azure CLI 버전이 2.30.0 이상인지 확인합니다. 이전 버전을 사용하는 경우 최신 버전을 설치하세요.

네트워크

네트워크 격리 클러스터를 사용하는 경우 Azure Key Vault에 액세스하도록 프라이빗 엔드포인트를 설정하는 것이 좋습니다.
클러스터에 아웃바운드 유형 userDefinedRouting 이 있고 Azure Firewall과 같은 도메인 이름에 따라 아웃바운드 트래픽을 제어할 수 있는 방화벽 디바이스를 사용하는 경우 필요한 아웃바운드 네트워크 규칙 및 FQDN이 허용되는지 확인합니다.
클러스터에 대한 수신을 제한하는 경우 포트 9808 및 8095가 열려 있는지 확인합니다.

역할

SecretProviderClass와 함께 사용되는 ID는 key 또는 certificate개체 형식에 액세스하기 위해 Key Vault Certificate User를 가져야 합니다.
secret개체 형식에 액세스하기 위해 Key Vault Secrets User이(가) 필요한 SecretProviderClass에 사용되는 ID입니다.

비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자 지원을 사용하여 AKS 클러스터 만들기

az group create 명령을 사용하여 Azure 리소스 그룹을 만듭니다.
```
az group create --name myResourceGroup --___location eastus2
```
--enable-addons azure-keyvault-secrets-provider 매개 변수와 함께 az aks create 명령을 사용하여 비밀 저장소 CSI 드라이버 기능에 대한 Azure Key Vault 공급자를 사용하여 AKS 클러스터를 만듭니다. 추가 기능은 키 자격 증명 모음에서 인증을 받는 데 사용할 수 있는 사용자가 할당한 관리 ID를 만듭니다. 다음 예제에서는 비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자를 사용하는 AKS 클러스터를 만듭니다.
참고

Microsoft Entra 워크로드 ID를 사용하려면 다음 예제와 같이 --enable-oidc-issuer 및 --enable-workload-identity 매개 변수도 사용해야 합니다.
```
az aks create --name myAKSCluster --resource-group myResourceGroup --enable-addons azure-keyvault-secrets-provider --enable-oidc-issuer --enable-workload-identity --generate-ssh-keys
```
```
az aks create \
    --name myAKSCluster \
    --resource-group myResourceGroup \
    --enable-addons azure-keyvault-secrets-provider \
    --generate-ssh-keys
```
이전 명령은 Azure 리소스에 액세스하기 위해 azureKeyvaultSecretsProvider 사용자가 할당한 관리 ID를 만듭니다. 다음 예제에서는 이 ID를 사용하여 비밀을 저장할 키 자격 증명 모음에 연결하지만 다른 ID 액세스 메서드를 사용할 수도 있습니다. 출력에 있는 ID의 clientId를 적어 둡니다.
```
...,
 "addonProfiles": {
    "azureKeyvaultSecretsProvider": {
      ...,
      "identity": {
        "clientId": "<client-id>",
        ...
      }
    }
```

참고

이 기능을 사용하도록 설정하면 AKS는 노드 리소스 그룹에 azurekeyvaultsecretsprovider-xxx(으)로 명명된 관리 ID를 만들고 VMSS(Virtual Machine Scale Sets)에 자동으로 할당합니다. 이 관리 ID 또는 사용자 고유의 관리 ID를 사용하여 키 자격 증명 모음에 액세스할 수 있습니다. ID 생성을 방지할 수는 없습니다.

비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자 지원으로 기존 AKS 클러스터 업그레이드

az aks enable-addons 명령을 사용하여 비밀 저장소 CSI 드라이버 기능을 위한 Azure Key Vault 공급자로 기존 AKS 클러스터를 업그레이드하고 azure-keyvault-secrets-provider 추가 기능을 사용하도록 설정합니다. 추가 기능은 키 자격 증명 모음에서 인증을 받는 데 사용할 수 있는 사용자가 할당한 관리 ID를 만듭니다.
```
az aks enable-addons --addons azure-keyvault-secrets-provider --name myAKSCluster --resource-group myResourceGroup
```

참고

비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자 설치 확인

az aks get-credentials 명령을 사용하여 AKS 클러스터 자격 증명을 가져옵니다.
```
az aks get-credentials --name myAKSCluster --resource-group myResourceGroup
```

kube-system 네임스페이스에 secrets-store-csi-driver 및 secrets-store-provider-azure 레이블이 있는 모든 Pod를 나열하는 kubectl get pods 명령을 사용하여 설치가 완료되었는지 확인합니다.

kubectl get pods -n kube-system -l 'app in (secrets-store-csi-driver,secrets-store-provider-azure)'

출력은 다음 예제 출력과 비슷하게 표시됩니다.

NAME                                     READY   STATUS    RESTARTS   AGE
aks-secrets-store-csi-driver-4vpkj       3/3     Running   2          4m25s
aks-secrets-store-csi-driver-ctjq6       3/3     Running   2          4m21s
aks-secrets-store-csi-driver-tlvlq       3/3     Running   2          4m24s
aks-secrets-store-provider-azure-5p4nb   1/1     Running   0          4m21s
aks-secrets-store-provider-azure-6pqmv   1/1     Running   0          4m24s
aks-secrets-store-provider-azure-f5qlm   1/1     Running   0          4m25s

클러스터의 노드 풀에 있는 각 노드에 비밀 저장소 CSI 드라이버 Pod 및 비밀 저장소 공급자 Azure Pod가 실행 중인지 확인합니다.

Azure Key Vault 만들기 또는 기존 Azure Key Vault 사용

az keyvault create 명령 또는 az keyvault update 명령을 --enable-rbac-authorization 플래그와 함께 사용하여 Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하는 키 자격 증명 모음을 만들거나 업데이트합니다. Key Vault의 이름은 전역적으로 고유해야 합니다. 키 자격 증명 모음 사용 권한 모델 및 Azure RBAC에 대한 자세한 내용은 Azure 역할 기반 액세스 제어를 사용하여 Key Vault 키, 인증서 및 비밀에 대한 액세스 제공을 참조하세요.
```
## Create a new Azure key vault
az keyvault create --name <keyvault-name> --resource-group myResourceGroup --___location eastus2 --enable-rbac-authorization

## Update an existing Azure key vault
az keyvault update --name <keyvault-name> --resource-group myResourceGroup --___location eastus2 --enable-rbac-authorization
```
키 자격 증명 모음에는 키, 비밀 및 인증서를 저장할 수 있습니다. 이 예제에서는 az keyvault secret set 명령을 사용하여 ExampleSecret이라는 일반 텍스트 암호를 설정합니다.
```
az keyvault secret set --vault-name <keyvault-name> --name ExampleSecret --value MyAKSExampleSecret
```
나중에 사용할 수 있도록 다음 속성을 기록해 둡니다.
- 키 자격 증명 모음에 있는 비밀 개체의 이름
- 개체 형식(비밀, 키 또는 인증서)
- 키 자격 증명 모음 리소스의 이름
- 구독의 Azure 테넌트 ID

다음 단계

이 문서에서는 AKS 클러스터에서 비밀 저장소 CSI 드라이버용 Azure Key Vault 공급자를 사용하는 방법을 알아보았습니다. 이제 Azure Key Vault에 액세스하기 위한 ID를 제공해야 합니다. 방법을 알아보려면 계속해서 다음 문서를 진행하세요.

AKS에서 Secrets Store CSI 드라이버용 Azure Key Vault 공급자에 액세스하기 위한 ID 제공