Azure 應用程式組態 Kubernetes 提供者參考

下列參考概述 Azure 應用程式組態 Kubernetes 提供者 v2.1.0所支持的屬性。 如需變更的詳細資訊，請參閱 版本資訊 。

屬性

AzureAppConfigurationProvider資源在 下spec具有下列最上層子屬性。 endpoint必須指定或 connectionStringReference 。

屬性 spec.target 具有下列子屬性。

spec.target.configMapData如果未設定 屬性，產生的 ConfigMap 會填入從 Azure 應用程式組態 擷取的索引鍵/值清單，讓 ConfigMap 成為環境變數。 如果您想要使用 ConfigMap 作為掛接的檔案，請更新此屬性。 此屬性具有下列子屬性。

spec.auth如果設定 屬性來提供 spec.connectionStringReference 應用程式組態 存放區的 連接字串，則不需要屬性。 否則，會使用其中一個身分識別、服務主體、工作負載身分識別或受控識別來進行驗證。 spec.auth具有下列子屬性。 應該只指定其中一個。 如果未設定它們，則會使用虛擬機擴展集的系統指派受控識別。

屬性 spec.auth.workloadIdentity 具有下列子屬性。

spec.configuration具有下列子屬性。

spec.configuration.selectors如果未設定屬性，則會下載不含標籤的所有索引鍵/值。 它包含選取器對象的陣列，其具有下列子屬性。 請注意，上一個選取器的索引鍵/值優先，並覆寫先前選取器中的任何重疊索引鍵。

屬性 spec.configuration.refresh 具有下列子屬性。

spec.configuration.refresh.monitoring.keyValues是 對象的陣列，其具有下列子屬性。

屬性 spec.secret 具有下列子屬性。 如果預期下載任何 金鑰保存庫 參考，則為必要專案。 若要深入瞭解 Kubernetes 內建秘密類型的支援，請參閱 秘密類型。

屬性 spec.secret.target 具有下列子屬性。

spec.secret.auth如果未設定 屬性，則會使用系統指派的受控識別。 它有下列子屬性。

您可以使用下列屬性來指定每個 金鑰保存庫 的驗證方法。 必須提供 其中 managedIdentityClientId一個 或 servicePrincipalReference workloadIdentity 。

屬性 spec.secret.refresh 具有下列子屬性。

屬性 spec.featureFlag 具有下列子屬性。 如果預期下載任何功能旗標，則為必要專案。

spec.featureFlag.selectors如果未設定屬性，則不會下載功能旗標。 它包含選取器對象的陣列，其具有下列子屬性。 請注意，最後一個選取器的功能旗標會優先使用，並覆寫先前選取器中的任何重疊索引鍵。

屬性 spec.featureFlag.refresh 具有下列子屬性。

安裝

使用下列helm install命令來安裝 Azure 應用程式組態 Kubernetes Provider。 如需參數及其預設值的完整清單，請參閱 helm-values.yaml 。 您可以將 旗標傳遞 --set 至 命令，以覆寫預設值。

helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace

自動調整

預設會停用自動調整。 不過，如果您有多個資源可以產生多個 AzureAppConfigurationProvider ConfigMaps/秘密，您可以將 設定 autoscaling.enabled 為 true來啟用水準 Pod 自動調整。

helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace
    --set autoscaling.enabled=true

資料集合

軟體可能會收集您及其使用軟體的相關信息，並將其傳送至Microsoft。 Microsoft 得運用此資訊提供服務，並以此改善產品和服務。 您可以在安裝 Azure 應用程式組態 Kubernetes 提供者時設定 requestTracing.enabled=false 來關閉遙測。 軟體中也有一些功能可讓您和Microsoft從應用程式的使用者收集數據。 如果您使用這些功能，您必須遵守適用的法律，包括提供適當的通知給應用程式的使用者，以及Microsoft隱私聲明的複本。 本公司的隱私權聲明位於 https://go.microsoft.com/fwlink/?LinkID=824704。 您可於文件和本公司隱私權聲明中，進一步了解資料收集與使用的相關資訊。 使用本軟體，即代表貴用戶同意前述做法。

範例

驗證

使用虛擬機擴展集的系統指派受控識別

1. 在 Azure Kubernetes Service （AKS） 叢集所使用的虛擬機擴展集中 啟用系統指派的受控識別。

2. 在 Azure 應用程式組態 中授與系統指派的受控識別 應用程式組態 數據讀取者角色。

3. 將下列範例 AzureAppConfigurationProvider 資源部署到 AKS 叢集。

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     endpoint: <your-app-configuration-store-endpoint>
     target:
       configMapName: configmap-created-by-appconfig-provider
   

使用虛擬機擴展集的使用者指派受控識別

1. 建立使用者指派的受控識別 ，並在建立後記下其用戶端標識符。

2. 將使用者指派的受控識別指派給 Azure Kubernetes Service （AKS） 叢集所使用的虛擬機擴展集 。

3. 在 Azure 應用程式組態 中授與使用者指派的受控識別 應用程式組態 數據讀取者角色。

4. 將 spec.auth.managedIdentityClientId 屬性設定為下列範例 AzureAppConfigurationProvider 資源中使用者指派受控識別的用戶端標識碼，並將其部署至 AKS 叢集。

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     endpoint: <your-app-configuration-store-endpoint>
     target:
       configMapName: configmap-created-by-appconfig-provider
     auth:
       managedIdentityClientId: <your-managed-identity-client-id>
   

使用服務主體

1. 建立服務主體

2. 在 Azure 應用程式組態 中授與服務主體 應用程式組態 數據讀取者角色。

3. 在與AzureAppConfigurationProvider資源相同的命名空間中建立 Kubernetes 秘密，並將服務主體的azure_client_id、azure_client_secret和azure_tenant_id新增至秘密。

4. 將 spec.auth.servicePrincipalReference 屬性設定為下列範例 AzureAppConfigurationProvider 資源中的 Secret 名稱，並將其部署至 Kubernetes 叢集。

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     endpoint: <your-app-configuration-store-endpoint>
     target:
       configMapName: configmap-created-by-appconfig-provider
     auth:
       servicePrincipalReference: <your-service-principal-secret-name>
   

使用工作負載身分識別

1. 在 Azure Kubernetes Service （AKS） 叢集上啟用工作負載身分識別 。

2. 取得 AKS 叢集的 OIDC 簽發者 URL 。

3. 建立使用者指派的受控識別，並記下其用戶端標識碼 、租使用者標識碼、名稱和資源群組。

4. 在 Azure 應用程式組態 中授與使用者指派的受控識別 應用程式組態 數據讀取者角色。

5. 將 YAML 檔案（例如 serviceAccount.yaml）新增下列內容新增至包含 AKS 部署檔案的目錄，以建立服務帳戶。 當您將所有部署變更套用至 AKS 叢集時，將會建立服務帳戶（例如，使用 kubectl apply）。 將 取代為用戶端標識碼，並將 <your-managed-identity-tenant-id> 取代<your-managed-identity-client-id>為剛建立之使用者指派受控識別的租用戶標識碼。 將取代 <your-service-account-name> 為您慣用的名稱。

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: <your-service-account-name>
     annotations:
       azure.workload.identity/client-id: <your-managed-identity-client-id>
       azure.workload.identity/tenant-id: <your-managed-identity-tenant-id>
   

6. 使用 Azure CLI 為使用者指派的受控識別建立同盟身分識別認證。 將 取代為名稱，並將 <resource-group> 取代<user-assigned-identity-name>為新建立的使用者指派受控識別的資源群組。 將取代 <aks-oidc-issuer> 為 AKS 叢集的 OIDC 簽發者 URL。 將取代 <your-service-account-name> 為新建立的服務帳戶名稱。 將取代 <federated-identity-credential-name> 為您慣用的同盟身分識別認證名稱。

   az identity federated-credential create --name "<federated-identity-credential-name>" --identity-name "<user-assigned-identity-name>" --resource-group "<resource-group>" --issuer "<aks-oidc-issuer>" --subject system:serviceaccount:default:<your-service-account-name> --audience api://AzureADTokenExchange
   

   請注意，同盟身分識別認證的主體應遵循下列格式： system:serviceaccount:<service-account-namespace>:<service-account-name>。

7. 將 spec.auth.workloadIdentity.serviceAccountName 屬性設定為下列範例 AzureAppConfigurationProvider 資源中的服務帳戶名稱。 請確定 AzureAppConfigurationProvider 資源和服務帳戶位於相同的命名空間中。

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     endpoint: <your-app-configuration-store-endpoint>
     target:
       configMapName: configmap-created-by-appconfig-provider
     auth:
       workloadIdentity:
         serviceAccountName: <your-service-account-name>
   

使用 連接字串

1. 在與資源相同的命名空間中建立 Kubernetes 秘密，AzureAppConfigurationProvider並在秘密中使用密鑰azure_app_configuration_connection_string新增 Azure 應用程式組態 連接字串。

2. 將 spec.connectionStringReference 屬性設定為下列範例 AzureAppConfigurationProvider 資源中的 Secret 名稱，並將其部署至 Kubernetes 叢集。

   apiVersion: azconfig.io/v1
   kind: AzureAppConfigurationProvider
   metadata:
     name: appconfigurationprovider-sample
   spec:
     connectionStringReference: <your-connection-string-secret-name>
     target:
       configMapName: configmap-created-by-appconfig-provider
   

索引鍵/值選取

selectors使用 屬性來篩選要從 Azure 應用程式組態 下載的索引鍵/值。

下列範例會下載不含標籤的所有索引鍵/值。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider

在下列範例中，會使用兩個選取器來擷取兩組索引鍵/值，每組都有唯一標籤。 請務必注意，最後一個選取器的值優先，並覆寫先前選取器中的任何重疊索引鍵。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - keyFilter: app1*
        labelFilter: common
      - keyFilter: app1*
        labelFilter: development

快照集可以單獨使用，也可以與其他索引鍵/值選取器一起使用。 在下列範例中，您會從快照集載入一般組態的索引鍵/值，然後使用索引鍵/值來覆寫其中一些值以進行開發。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - snapshotName: app1_common_configuration
      - keyFilter: app1*
        labelFilter: development

索引鍵前置詞修剪

下列範例會 trimKeyPrefixes 使用 屬性來修剪索引鍵名稱的兩個前置詞，再將它們新增至產生的 ConfigMap。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    trimKeyPrefixes: [prefix1, prefix2]

設定重新整理

當您在 Azure 應用程式組態 中變更數據時，您可能會想要在 Kubernetes 叢集中自動重新整理這些變更。 更新多個索引鍵/值很常見，但您不希望叢集在更新中途取得變更。 若要維持組態一致性，您可以使用機碼值來發出更新完成的訊號。 這個索引鍵/值稱為 sentinel 索引鍵。 Kubernetes 提供者可以監視此索引鍵/值，而且 ConfigMap 和秘密只會在 sentinel 密鑰中偵測到變更之後，以更新的數據重新產生。

在下列範例中，會每隔一分鐘輪詢名為 app1_sentinel 的索引鍵/值，並在 Sentinel 索引鍵中偵測到變更時重新整理組態。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - keyFilter: app1*
        labelFilter: common
    refresh:
      enabled: true
      interval: 1m
      monitoring:
        keyValues:
          - key: app1_sentinel
            label: common

Key Vault 參考

驗證

在下列範例中，服務主體會驗證一個 金鑰保存庫，而所有其他 金鑰保存庫 則會使用使用者指派的受控識別進行驗證。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - keyFilter: app1*
  secret:
    target:
      secretName: secret-created-by-appconfig-provider
    auth:
      managedIdentityClientId: <your-user-assigned-managed-identity-client-id>
      keyVaults:
        - uri: <your-key-vault-uri>
          servicePrincipalReference: <name-of-secret-containing-service-principal-credentials>

秘密類型

目前支援兩種 Kubernetes 內 建的秘密類型，不透明和 TLS。 根據預設，從 金鑰保存庫 參考解析的秘密會儲存為不透明秘密類型。 如果您有憑證的 金鑰保存庫 參考，而且想要將它儲存為 TLS 秘密類型，您可以將具有下列名稱和值的標記新增至 Azure 應用程式組態 中的 金鑰保存庫 參考。 如此一來，就會產生具有 kubernetes.io/tls 型別的秘密，並以 金鑰保存庫 參考的索引鍵命名。

下列範例示範如何在產生的秘密中填入不同類型的數據。

假設 應用程式組態 存放區具有下列 金鑰保存庫 參考：

下列範例會產生不透明和 TLS 類型的秘密。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - keyFilter: app1*
  secret:
    target:
      secretName: secret-created-by-appconfig-provider
    auth:
      managedIdentityClientId: <your-user-assigned-managed-identity-client-id>

產生的秘密會填入下列資料：

name: secret-created-by-appconfig-provider
type: Opaque
data:
  app1-secret1: <secret value retrieved from Key Vault>
  app1-secret2: <secret value retrieved from Key Vault>

name: app1-certificate
type: kubernetes.io/tls
data:
  tls.crt: |
    <certificate data retrieved from Key Vault>
  tls.key: |
    <certificate key retrieved from Key Vault>

從 金鑰保存庫 重新整理秘密

從 金鑰保存庫 重新整理秘密通常需要從 Azure 應用程式組態 重載對應的 金鑰保存庫 參考。 不過，使用 spec.secret.refresh 屬性，您可以獨立重新整理來自 金鑰保存庫 的秘密。 這特別適用於確保您的工作負載在秘密輪替期間自動從 金鑰保存庫 挑選任何更新的秘密。 請注意，若要載入最新版本的秘密，金鑰保存庫 參考不得為版本設定的密碼。

下列範例會每小時從 金鑰保存庫 重新整理所有非版本設定的秘密。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  configuration:
    selectors:
      - keyFilter: app1*
        labelFilter: common
  secret:
    target:
      secretName: secret-created-by-appconfig-provider
    auth:
      managedIdentityClientId: <your-user-assigned-managed-identity-client-id>
    refresh:
      enabled: true
      interval: 1h

功能旗標

在下列範例中，以 開頭 app1 的索引鍵和相當於 common 的標籤的功能旗標會每隔 10 分鐘下載並重新整理一次。 請注意，若要在產生的 ConfigMap 中填入功能旗標， configMapData.type 屬性必須是 json 或 yaml。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData:
      type: json
      key: appSettings.json
  featureFlag:
    selectors:
      - keyFilter: app1*
        labelFilter: common
    refresh:
      enabled: true
      interval: 10m

ConfigMap 取用

在 Kubernetes 中執行的應用程式通常會使用 ConfigMap 做為環境變數或組態檔。 configMapData.type如果屬性不存在或設定為預設值，ConfigMap 會填入從 Azure 應用程式組態 擷取的數據專案化清單，這可以輕鬆地當做環境變數取用。 configMapData.type如果屬性設定為 json、yaml 或屬性，則從 Azure 應用程式組態 擷取的數據會分組成一個專案，其中包含所產生 ConfigMap 中 屬性所configMapData.key指定的索引鍵名稱，此專案可以當做掛接的檔案使用。

下列範例示範如何使用屬性的不同設定 configMapData.type ，在產生的 ConfigMap 中填入數據。

假設 應用程式組態 存放區具有下列索引鍵/值：

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider

data:
  key1: value1
  key2: value2
  key3: value3

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData:
      type: json
      key: appSettings.json

data:
  appSettings.json: >-
    {"key1":"value1","key2":"value2","key3":"value3"}

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData:
      type: yaml
      key: appSettings.yaml

data:
  appSettings.yaml: >-
    key1: value1
    key2: value2
    key3: value3

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData:
      type: properties
      key: app.properties

data:
  app.properties: >-
    key1=value1
    key2=value2
    key3=value3