Share via

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

  • 發行項

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

屬性

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

名稱 描述 必要 類型
endpoint Azure 應用程式組態 端點，您想要從中擷取索引鍵/值。 替代 字串
connectionStringReference 包含 Azure 應用程式組態 連接字串 的 Kubernetes 秘密名稱。 替代 字串
replicaDiscoveryEnabled 此設定會決定是否會自動探索並用於故障轉移 Azure 應用程式組態的複本。 如果屬性不存在，則會使用的預設值 true 。 false bool
目標 Kubernetes 中擷取之索引鍵/值的目的地。 true object
auth 要存取 Azure 應用程式組態 的驗證方法。 false object
組態 在 Azure 應用程式組態 中查詢和處理索引鍵/值的設定。 false object
secret Azure 應用程式組態 中 金鑰保存庫 參考的設定。 conditional object
featureFlag Azure 應用程式組態 中功能旗標的設定。 false object

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

名稱 描述 必要 類型
configMapName 要建立的 ConfigMap 名稱。 true 字串
configMapData 指定所產生 ConfigMap 中應如何填入擷取數據的設定。 false object

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

名稱 描述 必要 類型
type 設定，指出在產生的 ConfigMap 中如何建構擷取的數據。 允許的值包括default、 jsonyaml 與 properties。 選用 字串
索引鍵 當 設定為json、 yaml 或 properties時type，所擷取數據的索引鍵名稱。 如果 ConfigMap 設定為要當做掛接的檔案取用，請將它設定為檔名。 conditional 字串
separator 當類型設定為 json 或 yaml時，用來以階層格式輸出 ConfigMap 數據的分隔符。 根據預設，分隔符是空的，產生的 ConfigMap 會以其原始格式包含索引鍵/值。 只有在應用程式中所使用的組態檔載入器無法載入索引鍵/值，而不需將它們轉換成階層格式時，才設定此設定。 選用 字串

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

名稱 描述 必要 類型
servicePrincipalReference 包含服務主體認證的 Kubernetes 秘密名稱。 秘密必須位於與 Kubernetes 提供者相同的命名空間中。 false 字串
workloadIdentity 使用工作負載識別的設定。 false object
managedIdentityClientId 虛擬機擴展集使用者指派受控識別的用戶端標識碼。 false 字串

屬性 spec.auth.workloadIdentity 具有下列子屬性。 其中一個必須指定。

名稱 描述 必要 類型
managedIdentityClientId 與工作負載身分識別相關聯的使用者指派受控識別的用戶端標識碼。 替代 字串
managedIdentityClientIdReference 您可以從 ConfigMap 取得使用者指派受控識別的用戶端識別碼。 ConfigMap 必須與 Kubernetes 提供者位於相同的命名空間中。 替代 object

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

名稱 描述 必要 類型
configMap ConfigMap 的名稱，您可以在其中找到使用者指派受控識別的用戶端識別碼。 true 字串
索引鍵 保存使用者指派受控識別之用戶端識別碼值的金鑰名稱。 true 字串

spec.configuration具有下列子屬性。

名稱 描述 必要 類型
選擇 索引鍵/值篩選的選取器清單。 false 對象陣列
trimKeyPrefixes 要修剪的索引鍵前置詞清單。 false 字串陣列
重新整理 從Azure 應用程式組態 重新整理索引鍵/值的設定。 如果屬性不存在，則不會重新整理來自 Azure 應用程式組態的索引鍵/值。 false object

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

名稱 描述 必要 類型
keyFilter 用於查詢索引鍵/值的索引鍵篩選。 此屬性和 snapshotName 屬性不應同時設定。 替代 字串
labelFilter 用於查詢索引鍵/值的標籤篩選。 此屬性和 snapshotName 屬性不應同時設定。 false 字串
snapshotName 載入索引鍵/值之快照集的名稱。 這個屬性不應該與其他屬性搭配使用。 替代 字串

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

名稱 描述 必要 類型
已啟用 此設定會決定是否自動重新整理來自 Azure 應用程式組態的索引鍵/值。 如果屬性不存在，則會使用的預設值 false 。 false bool
監視 監視變更偵測的索引鍵/值，也稱為 sentinel 索引鍵。 只有當至少有一個受監視的索引鍵/值變更時，才會重新整理來自 Azure 應用程式組態 的索引鍵/值。 true object
interval 從Azure 應用程式組態 重新整理索引鍵/值的間隔。 它必須大於或等於1秒。 如果屬性不存在，則會使用預設值 30 秒。 false duration 字串

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

名稱 描述 必要 類型
索引鍵 索引鍵/值的索引鍵。 true 字串
label 索引鍵/值的標籤。 false 字串

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

名稱 描述 必要 類型
目標 Kubernetes 中擷取秘密的目的地。 true object
auth 用來存取 金鑰保存庫 的驗證方法。 false object
重新整理 從金鑰保存庫 重新整理數據的設定。 如果屬性不存在，除非重載對應的 金鑰保存庫 參考，否則不會重新整理來自 金鑰保存庫 的數據。 false object

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

名稱 描述 必要 類型
secretName 要建立的 Kubernetes 秘密名稱。 true 字串

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

名稱 描述 必要 類型
servicePrincipalReference Kubernetes 秘密的名稱，其中包含用於驗證的服務主體認證，其中具有未指定個別驗證方法的 金鑰保存庫。 false 字串
workloadIdentity 工作負載身分識別的設定，用於使用未指定個別驗證方法的 金鑰保存庫 進行驗證。 其子屬性與 spec.auth.workloadIdentity相同。 false object
managedIdentityClientId 虛擬機擴展集使用者指派受控識別的用戶端識別碼，用於向未指定個別驗證方法的 金鑰保存庫 進行驗證。 false 字串
keyVaults 個別 金鑰保存庫的驗證方法。 false 對象陣列

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

名稱 描述 必要 類型
uri 金鑰保存庫的 URI。 true 字串
servicePrincipalReference Kubernetes 秘密的名稱，其中包含用來向 金鑰保存庫 進行驗證的服務主體認證。 false 字串
workloadIdentity 用於向 金鑰保存庫 進行驗證的工作負載身分識別設定。 其子屬性與 spec.auth.workloadIdentity相同。 false object
managedIdentityClientId 用於向 金鑰保存庫 進行驗證的虛擬機擴展集使用者指派受控識別的用戶端識別碼。 false 字串

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

名稱 描述 必要 類型
已啟用 決定是否自動重新整理來自 金鑰保存庫 數據的設定。 如果屬性不存在，則會使用的預設值 false 。 false bool
interval 從 金鑰保存庫 重新整理數據的間隔。 它必須大於或等於1分鐘。 金鑰保存庫 重新整理與透過 spec.configuration.refresh設定的 應用程式組態 重新整理無關。 true duration 字串

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

名稱 描述 必要 類型
選擇 功能旗標篩選的選取器清單。 false 對象陣列
重新整理 從 Azure 應用程式組態 重新整理功能旗標的設定。 如果屬性不存在，則不會重新整理來自 Azure 應用程式組態的功能旗標。 false object

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

名稱 描述 必要 類型
keyFilter 查詢功能旗標的索引鍵篩選。 此屬性和 snapshotName 屬性不應同時設定。 替代 字串
labelFilter 查詢功能旗標的標籤篩選。 此屬性和 snapshotName 屬性不應同時設定。 false 字串
snapshotName 載入功能旗標的快照集名稱。 這個屬性不應該與其他屬性搭配使用。 替代 字串

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

名稱 描述 必要 類型
已啟用 此設定會決定是否自動重新整理來自 Azure 應用程式組態的功能旗標。 如果屬性不存在，則會使用的預設值 false 。 false bool
interval 從 Azure 應用程式組態 重新整理功能旗標的間隔。 它必須大於或等於1秒。 如果屬性不存在，則會使用預設值 30 秒。 false duration 字串

安裝

使用下列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 Config 地圖/秘密，您可以將 設定autoscaling.enabled為 true來啟用水準 Pod 自動調整。

範例

驗證

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

  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 CLI 在受控識別、OIDC 簽發者與主體之間建立同盟身分識別認證。

    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:azappconfig-system:az-appconfig-k8s-provider --audience api://AzureADTokenExchange

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

  6. 將 spec.auth.workloadIdentity.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:
    workloadIdentity:
      managedIdentityClientId: <your-managed-identity-client-id>

使用 連接字串

  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 型別的秘密，並以 金鑰保存庫 參考的索引鍵命名。

名稱 值
.kubernetes.secret.type kubernetes.io/tls

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

從 金鑰保存庫 重新整理秘密通常需要從 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 分鐘下載並重新整理一次。

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
  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 中填入數據。

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

索引鍵 value
key1 value1
key2 value2
key3 value3

configMapData.type屬性不存在或設定為 default，

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

產生的 ConfigMap 會填入下列資料：

data:
  key1: value1
  key2: value2
  key3: value3