Użyj rozszerzenia dostawcy tajnych danych usługi Azure Key Vault, aby pobrać tajne dane do klastrów Kubernetes z obsługą Azure Arc.

2025-04-02

Dostawca usługi Azure Key Vault dla sterownika CSI magazynu wpisów tajnych umożliwia integrację usługi Azure Key Vault jako magazynu wpisów tajnych z klastrem Kubernetes za pośrednictwem woluminu CSI. Dla klastrów Kubernetes obsługiwanych przez Azure Arc można zainstalować rozszerzenie Azure Key Vault Secrets Provider, aby pobierać sekrety.

Możliwości rozszerzenia dostawcy tajnych wpisów usługi Azure Key Vault obejmują:

Instaluje wpisy tajne/klucze/certyfikaty do zasobnika przy użyciu woluminu wbudowanego CSI
Obsługuje przenośność podów za pomocą CRD SecretProviderClass
Obsługuje kontenery systemów Linux i Windows
Obsługuje synchronizację z sekretami Kubernetes
Obsługuje automatyczne obracanie wpisów tajnych
Składniki rozszerzenia są wdrażane w strefach dostępności, dzięki czemu są strefowo nadmiarowe

Napiwek

Jeśli dostęp w trybie offline jest konieczny lub jeśli potrzebujesz wpisów tajnych zsynchronizowanych z magazynem wpisów tajnych Kubernetes, użyj rozszerzenia Magazynu wpisów tajnych do zarządzania wpisami tajnymi w klastrach Kubernetes z włączoną usługą Arc.

Wymagania wstępne

Klaster z obsługiwaną dystrybucją Kubernetes połączoną z usługą Azure Arc. Następujące dystrybucje kubernetes są obecnie obsługiwane w tym scenariuszu:
- API Azure klastra
- Klastry usługi Azure Kubernetes Service (AKS) w środowisku lokalnym platformy Azure
- Usługa AKS włączona przez usługę Azure Arc
- Aparat Google Kubernetes
- Dystrybucja rozwiązania OpenShift Kubernetes
- Dystrybucja rozwiązania Canonical Kubernetes
- Elastic Kubernetes Service
- Struktura Tanzu Kubernetes
- Azure Red Hat OpenShift
Łączność wychodząca z następującymi punktami końcowymi:
- linuxgeneva-microsoft.azurecr.io
- upstreamarc.azurecr.io
- *.blob.core.windows.net
Upewnij się, że spełnisz ogólne wymagania wstępne dotyczące rozszerzeń klastra. Musisz użyć wersji 0.4.0 lub nowszej rozszerzenia interfejsu wiersza polecenia platformy k8s-extension Azure.

Zainstaluj rozszerzenie dostawcy sekretów Azure Key Vault w klastrze Kubernetes z obsługą usługi Arc

Rozszerzenie dostawcy tajemnic Azure Key Vault można zainstalować w połączonym klastrze w portalu Azure, przy użyciu Azure CLI albo przez wdrożenie szablonu ARM.

W każdym klastrze Kubernetes z obsługą usługi Azure Arc można wdrożyć tylko jedno wystąpienie rozszerzenia.

Napiwek

Jeśli klaster znajduje się za serwerem proxy ruchu wychodzącego, przed zainstalowaniem rozszerzenia upewnij się, że połączysz go z usługą Azure Arc przy użyciu opcji konfiguracji serwera proxy.

Azure Portal

W witrynie Azure Portal przejdź do pozycji Kubernetes — Azure Arc i wybierz klaster.
W menu usługi w obszarze Ustawienia wybierz pozycję Rozszerzenia. Następnie wybierz pozycję + Dodaj.
Z listy dostępnych rozszerzeń wybierz Dostawcę tajemnic Azure Key Vault, aby wdrożyć najnowszą wersję rozszerzenia.
Postępuj zgodnie z monitami, aby wdrożyć rozszerzenie. W razie potrzeby dostosuj instalację, zmieniając opcje domyślne na karcie Konfiguracja .

Azure CLI (Interfejs wiersza polecenia platformy Azure)

Ustaw zmienne środowiskowe:

export CLUSTER_NAME=<arc-cluster-name>
export RESOURCE_GROUP=<resource-group-name>

Zainstaluj Secrets Store CSI Driver oraz rozszerzenie Azure Key Vault Secrets Provider, uruchamiając następujące polecenie:

az k8s-extension create --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --extension-type Microsoft.AzureKeyVaultSecretsProvider --name akvsecretsprovider

Powinny zostać wyświetlone dane wyjściowe podobne do tego przykładu. Może upłynąć kilka minut, zanim chart Helm dostawcy tajemnic zostanie wdrożony w klastrze.

{
  "aksAssignedIdentity": null,
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": {},
  "configurationSettings": {},
  "customLocationSettings": null,
  "errorInfo": null,
  "extensionType": "microsoft.azurekeyvaultsecretsprovider",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Kubernetes/connectedClusters/$CLUSTER_NAME/providers/Microsoft.KubernetesConfiguration/extensions/akvsecretsprovider",
  "identity": {
    "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "tenantId": null,
    "type": "SystemAssigned"
  },
  "location": null,
  "name": "akvsecretsprovider",
  "packageUri": null,
  "provisioningState": "Succeeded",
  "releaseTrain": "Stable",
  "resourceGroup": "$RESOURCE_GROUP",
  "scope": {
    "cluster": {
      "releaseNamespace": "kube-system"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": {
    "createdAt": "2022-05-12T18:35:56.552889+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2022-05-12T18:35:56.552889+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "1.1.3"
}

Szablon ARM

Utwórz plik .json przy użyciu następującego formatu. Pamiętaj, aby zaktualizować wartość <cluster-name>, odnoszącą się do twojego klastra.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "ConnectedClusterName": {
            "defaultValue": "<cluster-name>",
            "type": "String",
            "metadata": {
                "description": "The Connected Cluster name."
            }
        },
        "ExtensionInstanceName": {
            "defaultValue": "akvsecretsprovider",
            "type": "String",
            "metadata": {
                "description": "The extension instance name."
            }
        },
        "ExtensionVersion": {
            "defaultValue": "",
            "type": "String",
            "metadata": {
                "description": "The version of the extension type."
            }
        },
        "ExtensionType": {
            "defaultValue": "Microsoft.AzureKeyVaultSecretsProvider",
            "type": "String",
            "metadata": {
                "description": "The extension type."
            }
        },
        "ReleaseTrain": {
            "defaultValue": "stable",
            "type": "String",
            "metadata": {
                "description": "The release train."
            }
        }
    },
    "functions": [],
    "resources": [
        {
            "type": "Microsoft.KubernetesConfiguration/extensions",
            "apiVersion": "2021-09-01",
            "name": "[parameters('ExtensionInstanceName')]",
            "identity": {
             "type": "SystemAssigned"
            },
            "properties": {
                "extensionType": "[parameters('ExtensionType')]",
                "releaseTrain": "[parameters('ReleaseTrain')]",
                "version": "[parameters('ExtensionVersion')]"
            },
            "scope": "[concat('Microsoft.Kubernetes/connectedClusters/', parameters('ConnectedClusterName'))]"
        }
    ]
}

Teraz ustaw zmienne środowiskowe przy użyciu następującego polecenia interfejsu wiersza polecenia platformy Azure:
```
export TEMPLATE_FILE_NAME=<template-file-path>
export DEPLOYMENT_NAME=<desired-deployment-name>
```

Na koniec uruchom to polecenie Azure CLI, aby zainstalować rozszerzenie dostawcy sekretów usługi Azure Key Vault:

az deployment group create --name $DEPLOYMENT_NAME --resource-group $RESOURCE_GROUP --template-file $TEMPLATE_FILE_NAME

Teraz powinno być możliwe wyświetlenie zasobów tajnych dostawców i użycie rozszerzenia w klastrze.

Weryfikowanie instalacji rozszerzenia

Aby potwierdzić pomyślną instalację rozszerzenia dostawcy sekretów dla Azure Key Vault, uruchom następujące polecenie.

az k8s-extension show --cluster-type connectedClusters --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --name akvsecretsprovider

Powinny zostać wyświetlone dane wyjściowe podobne do tego przykładu.

{
  "aksAssignedIdentity": null,
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": {},
  "configurationSettings": {},
  "customLocationSettings": null,
  "errorInfo": null,
  "extensionType": "microsoft.azurekeyvaultsecretsprovider",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Kubernetes/connectedClusters/$CLUSTER_NAME/providers/Microsoft.KubernetesConfiguration/extensions/akvsecretsprovider",
  "identity": {
    "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "tenantId": null,
    "type": "SystemAssigned"
  },
  "location": null,
  "name": "akvsecretsprovider",
  "packageUri": null,
  "provisioningState": "Succeeded",
  "releaseTrain": "Stable",
  "resourceGroup": "$RESOURCE_GROUP",
  "scope": {
    "cluster": {
      "releaseNamespace": "kube-system"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": {
    "createdAt": "2022-05-12T18:35:56.552889+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2022-05-12T18:35:56.552889+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "1.1.3"
}

Tworzenie lub wybieranie usługi Azure Key Vault

Następnie określ usługę Azure Key Vault do użycia z połączonym klastrem. Jeśli jeszcze go nie masz, utwórz nową usługę Key Vault przy użyciu następujących poleceń. Należy pamiętać, że nazwa magazynu kluczy musi być globalnie unikatowa.

Ustaw następujące zmienne środowiskowe:

export AKV_RESOURCE_GROUP=<resource-group-name>
export AZUREKEYVAULT_NAME=<AKV-name>
export AZUREKEYVAULT_LOCATION=<AKV-location>

Następnie uruchom następujące polecenie:

az keyvault create -n $AZUREKEYVAULT_NAME -g $AKV_RESOURCE_GROUP -l $AZUREKEYVAULT_LOCATION

Usługa Azure Key Vault może przechowywać klucze, wpisy tajne i certyfikaty. W tym przykładzie można ustawić wpis tajny w postaci zwykłego tekstu o nazwie DemoSecret przy użyciu następującego polecenia:

az keyvault secret set --vault-name $AZUREKEYVAULT_NAME -n DemoSecret --value MyExampleSecret

Przed przejściem do następnej sekcji zanotuj następujące właściwości:

Nazwa obiektu tajnego w usłudze Key Vault
Typ obiektu (wpis tajny, klucz lub certyfikat)
Nazwa zasobu usługi Key Vault
Identyfikator dzierżawy Azure dla subskrypcji, do której należy Key Vault

Zapewnianie tożsamości w celu uzyskania dostępu do usługi Azure Key Vault

Obecnie sterownik CSI do przechowywania sekretów w klastrach z obsługą usługi Arc jest dostępny za pośrednictwem jednostki usługi. Wykonaj następujące kroki, aby zapewnić tożsamość, która może uzyskać dostęp do usługi Key Vault.

Wykonaj kroki , aby utworzyć jednostkę usługi na platformie Azure. Zanotuj identyfikator klienta i klucz tajny klienta wygenerowany w tym kroku.
Następnie upewnij się, że Azure Key Vault ma uprawnienia do uzyskania dostępu do utworzonego principale usługi.

Użyj identyfikatora klienta i tajnego klucza klienta z pierwszego kroku, aby utworzyć tajny klucz Kubernetes w połączonym klastrze.

kubectl create secret generic secrets-store-creds --from-literal clientid="<client-id>" --from-literal clientsecret="<client-secret>"

Etykieta utworzonego sekretu:

kubectl label secret secrets-store-creds secrets-store.csi.k8s.io/used=true

Utwórz zasób SecretProviderClass z następującym kodem YAML, uzupełniając wartości dla nazwy skarbca kluczy, identyfikatora dzierżawcy i obiektów do pobrania z instancji AKV:

# This is a SecretProviderClass example using service principal to access Keyvault
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: akvprovider-demo
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    keyvaultName: <key-vault-name>
    cloudName:                           # Defaults to AzurePublicCloud
    objects:  |
      array:
        - |
          objectName: DemoSecret
          objectType: secret             # object types: secret, key or cert
          objectVersion: ""              # [OPTIONAL] object versions, default to latest if empty
    tenantId: <tenant-Id>                # The tenant ID of the Azure Key Vault instance

Aby korzystać z chmur krajowych, zmień cloudName na AzureUSGovernmentCloud dla platformy Azure Government lub na AzureChinaCloud dla platformy Microsoft Azure obsługiwanej przez firmę 21Vianet.

Zastosuj klasę SecretProviderClass do klastra:
```
kubectl apply -f secretproviderclass.yaml
```

Utwórz pod przy użyciu następującego kodu YAML, wypełniając nazwę swojej tożsamości.

# This is a sample pod definition for using SecretProviderClass and service principal to access Keyvault
kind: Pod
apiVersion: v1
metadata:
  name: busybox-secrets-store-inline
spec:
  containers:
    - name: busybox
      image: k8s.gcr.io/e2e-test-images/busybox:1.29
      command:
        - "/bin/sleep"
        - "10000"
      volumeMounts:
      - name: secrets-store-inline
        mountPath: "/mnt/secrets-store"
        readOnly: true
  volumes:
    - name: secrets-store-inline
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "akvprovider-demo"
        nodePublishSecretRef:                       
          name: secrets-store-creds

Zastosuj pod do swojego klastra.
```
kubectl apply -f pod.yaml
```

Weryfikowanie tajemnic

Po uruchomieniu poda, zamontowana zawartość na ścieżce woluminu określonej w pliku wdrożeniowym YAML jest dostępna.

## show secrets held in secrets-store
kubectl exec busybox-secrets-store-inline -- ls /mnt/secrets-store/

## print a test secret 'DemoSecret' held in secrets-store
kubectl exec busybox-secrets-store-inline -- cat /mnt/secrets-store/DemoSecret

Dodatkowe opcje konfiguracji

Rozszerzenie dostawcy wpisów tajnych usługi Azure Key Vault obsługuje konfiguracje chartów Helm.

Następujące ustawienia konfiguracji są często używane z rozszerzeniem Azure Key Vault Secrets Provider dla wpisów tajnych.

Ustawienie konfiguracji	Domyślny	opis
enableSecretRotation	fałsz	Typ logiczny (Boolean). Jeśli `true`, okresowo aktualizuje montaż zasobnika i Sekret Kubernetes, korzystając z najnowszej zawartości z zewnętrznego magazynu sekretów.
rotationPollInterval	2 m	Jeśli `enableSecretRotation` jest `true`, to ustawienie określa czas trwania interwału sondowania rotacji tajemnic. Ten czas trwania można dostosować na podstawie tego, jak często zamontowane zawartości dla wszystkich zasobników i sekrety Kubernetes muszą być ponownie zsynchronizowane z najnowszym stanem.
syncSecret.włączony	fałsz	Wejście logiczne. W niektórych przypadkach możesz utworzyć Sekret Kubernetes w celu odwzorowania zamontowanej zawartości. Jeśli `true`, `SecretProviderClass` umożliwia `secretObjects` zdefiniowanie żądanego stanu zsynchronizowanych obiektów sekretu Kubernetes.

Te ustawienia można określić, gdy rozszerzenie jest zainstalowane za pomocą az k8s-extension create polecenia :

az k8s-extension create --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --extension-type Microsoft.AzureKeyVaultSecretsProvider --name akvsecretsprovider --configuration-settings secrets-store-csi-driver.enableSecretRotation=true secrets-store-csi-driver.rotationPollInterval=3m secrets-store-csi-driver.syncSecret.enabled=true

Te ustawienia można również zmienić po instalacji za pomocą az k8s-extension update polecenia :

az k8s-extension update --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --name akvsecretsprovider --configuration-settings secrets-store-csi-driver.enableSecretRotation=true secrets-store-csi-driver.rotationPollInterval=3m secrets-store-csi-driver.syncSecret.enabled=true

Możesz użyć innych ustawień konfiguracji zgodnie z potrzebami wdrożenia. Aby na przykład zmienić katalog główny kubelet podczas tworzenia klastra, zmodyfikuj az k8s-extension create polecenie:

az k8s-extension create --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --extension-type Microsoft.AzureKeyVaultSecretsProvider --name akvsecretsprovider --configuration-settings linux.kubeletRootDir=/path/to/kubelet secrets-store-csi-driver.linux.kubeletRootDir=/path/to/kubelet

Odinstaluj rozszerzenie dostawcy sekretów usługi Azure Key Vault

Aby odinstalować rozszerzenie, uruchom następujące polecenie:

az k8s-extension delete --cluster-type connectedClusters --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --name akvsecretsprovider

Uwaga

Odinstalowanie rozszerzenia nie powoduje usunięcia niestandardowych definicji zasobów (CRD), które zostały utworzone podczas instalowania rozszerzenia.

Aby potwierdzić, że wystąpienie rozszerzenia zostało usunięte, uruchom następujące polecenie:

az k8s-extension list --cluster-type connectedClusters --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP

Jeśli rozszerzenie zostało pomyślnie usunięte, rozszerzenie dostawcy sekretów usługi Azure Key Vault nie jest wyświetlane w danych wyjściowych. Jeśli w klastrze nie są zainstalowane żadne inne rozszerzenia, zwracana jest pusta tablica.

Jeśli nie jest już potrzebny, pamiętaj o usunięciu wpisu tajnego Kubernetes skojarzonego z głównym elementem usługi, uruchamiając następujące polecenie:

kubectl delete secret secrets-store-creds

Uzgadnianie i rozwiązywanie problemów

Rozszerzenie dostawcy sekretów usługi Azure Key Vault jest samonaprawiające się. Jeśli ktoś spróbuje zmienić lub usunąć składnik rozszerzenia, który został wdrożony podczas instalacji rozszerzenia, ten składnik jest uzgadniany z jego oryginalnym stanem. Jedynymi wyjątkami są niestandardowe definicje zasobów (CRD). Usunięte CRD nie są synchronizowane. Aby przywrócić usunięte CRD, ponownie użyj polecenia az k8s-extension create z istniejącą nazwą wystąpienia rozszerzenia.

Aby uzyskać więcej informacji na temat rozwiązywania typowych problemów, zobacz przewodniki typu open source dotyczące rozwiązywania problemów dla dostawcy Azure Key Vault w ramach sterownika CSI dla Secrets Store i Secrets Store CSI Driver.

Następne kroki

Chcesz wypróbować coś? Szybko rozpocznij pracę ze scenariuszem Azure Arc Jumpstart za pomocą interfejsu API do zarządzania klastrami.
Dowiedz się więcej o usłudze Azure Key Vault.
Pomóż chronić klaster na inne sposoby, postępując zgodnie ze wskazówkami w książce zabezpieczeń dla platformy Kubernetes z obsługą usługi Azure Arc.