Azure App Configuration Kubernetes プロバイダー リファレンス

次のリファレンスでは、Azure アプリ Configuration Kubernetes Provider v2.0.0でサポートされるプロパティの概要を示します。 変更の詳細については、 リリースノート を参照してください。

プロパティ

AzureAppConfigurationProvider リソースでは、spec に次の最上位の子プロパティがあります。 endpoint または connectionStringReference のいずれかを指定する必要があります。

spec.target プロパティには、次の子プロパティがあります。

spec.target.configMapData プロパティが設定されていない場合、生成された ConfigMap には、Azure アプリ Configuration から取得されたキー値の一覧が設定されます。これにより、ConfigMap を環境変数として使用できます。 ConfigMap をマウントされたファイルとして使う場合は、このプロパティを更新します。 このプロパティには、次の子プロパティがあります。

spec.connectionStringReference プロパティの設定によって App Configuration ストアの接続文字列が指定されている場合、spec.auth プロパティは必要ありません。 それ以外の場合は、ID、サービス プリンシパル、ワークロード ID、またはマネージド ID のいずれかが認証に使用されます。 spec.auth には、次の子プロパティがあります。 そのうち 1 つだけを指定する必要があります。 いずれも設定されていない場合は、仮想マシン スケール セットのシステム割り当てマネージド ID が使用されます。

spec.auth.workloadIdentity プロパティには、次の子プロパティがあります。

spec.configuration には、次の子プロパティがあります。

spec.configuration.selectors プロパティが設定されていない場合は、ラベルのないすべてのキー値がダウンロードされます。 これには、次の子プロパティを持つ "セレクター" オブジェクトの配列が含まれています。 最後のセレクターのキー値が優先され、前のセレクターの重複するキーがオーバーライドされることに注意してください。

spec.configuration.refresh プロパティには、次の子プロパティがあります。

spec.configuration.refresh.monitoring.keyValues はオブジェクトの配列であり、次の子プロパティがあります。

spec.secret プロパティには、次の子プロパティがあります。 Key Vault 参照のダウンロードが想定される場合は必須です。 Kubernetes 組み込みの種類のシークレットのサポートの詳細については、「 シークレットの種類を参照してください。

spec.secret.target プロパティには、次の子プロパティがあります。

spec.secret.auth プロパティが設定されていない場合は、システム割り当てマネージド ID が使用されます。 これには、次の子プロパティがあります。

各 "キー コンテナー" の認証方法は、次のプロパティで指定できます。 managedIdentityClientId、servicePrincipalReference、または workloadIdentity のいずれかを指定する必要があります。

spec.secret.refresh プロパティには、次の子プロパティがあります。

spec.featureFlag プロパティには、次の子プロパティがあります。 これは、いずれかの機能フラグがダウンロードされる必要がある場合に必要です。

spec.featureFlag.selectors プロパティが設定されていない場合、機能フラグはダウンロードされません。 これには、次の子プロパティを持つ "セレクター" オブジェクトの配列が含まれています。 最後のセレクターの機能フラグが優先され、前のセレクターの重複するキーがオーバーライドされることに注意してください。

spec.featureFlag.refresh プロパティには、次の子プロパティがあります。

インストール

次の helm install コマンドを使用して、Azure アプリ Configuration Kubernetes プロバイダーをインストールします。 パラメーターとその既定値の完全な一覧については、 helm-values.yaml を参照してください。 --set フラグをコマンドに渡すことで、既定値をオーバーライドできます。

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

自動スケール

既定では、自動スケーリングは無効です。 ただし、複数の ConfigMaps/Secret を生成する複数の AzureAppConfigurationProvider リソースがある場合は、 autoscaling.enabled を true に設定することで、ポッドの水平自動スケーリングを有効にすることができます。

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 はこの情報を、サービスの提供ならびに Microsoft の製品およびサービスの向上を目的として使用することがあります。 Azure アプリ Configuration Kubernetes Provider のインストール中にrequestTracing.enabled=falseを設定することで、テレメトリをオフにすることができます。 ソフトウェアには、お客様と Microsoft がアプリケーションのユーザーからデータを収集できる機能もあります。 これらの機能を使用する場合は、アプリケーションのユーザーに適切な通知を Microsoft のプライバシーに関する声明のコピーと共に提供するなど、適用される法律を遵守する必要があります。 マイクロソフトのプライバシーに関する声明については、https://go.microsoft.com/fwlink/?LinkID=824704 を参照してください。 データの収集と使用の詳細については、ヘルプ ドキュメントとプライバシーに関する声明を参照してください。 本ソフトウェアを使用した場合、お客様はこれらの規定に同意したものとみなされます。

例

認証

仮想マシン スケール セットのシステム割り当てマネージド ID を使う

1. Azure Kubernetes Service (AKS) クラスターで使用される仮想マシン スケール セットでシステム割り当てマネージド ID を有効にします。

2. システム割り当てマネージド ID に Azure App Configuration の App Configuration データ閲覧者ロールを付与します。

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
   

仮想マシン スケール セットのユーザー割り当てマネージド ID を使う

1. ユーザー割り当てマネージド ID を作成し、作成後にそのクライアント ID をメモします。

2. Azure Kubernetes Service (AKS) クラスターで使用される仮想マシン スケール セットでユーザー割り当てマネージド ID を割り当てます。

3. ユーザー割り当てマネージド ID に Azure App Configuration の App Configuration データ閲覧者ロールを付与します。

4. spec.auth.managedIdentityClientId プロパティを、次のサンプル AzureAppConfigurationProvider リソースのユーザー割り当てマネージド ID のクライアント ID に設定し、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 App Configuration の App Configuration データ閲覧者ロールを付与します。

3. AzureAppConfigurationProvider リソースと同じ名前空間に Kubernetes シークレットを作成し、サービス プリンシパルの azure_client_id、azure_client_secret、azure_tenant_id をシークレットに追加します。

4. spec.auth.servicePrincipalReference プロパティを次のサンプル AzureAppConfigurationProvider リソースのシークレットの名前に設定し、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>
   

ワークロード ID を使う

1. Azure Kubernetes Service (AKS) クラスターでワークロード ID を有効にします。

2. AKS クラスターの OIDC 発行者 URL を取得します。

3. ユーザー割り当てマネージド ID を作成し クライアント ID、テナント ID、名前、およびリソース グループをメモします。

4. ユーザー割り当てマネージド ID に Azure App Configuration の App Configuration データ閲覧者ロールを付与します。

5. AKS デプロイ ファイルを含むディレクトリに次の内容を含む YAML ファイル ( serviceAccount.yaml など) を追加して、サービス アカウントを作成します。 サービス アカウントは、すべてのデプロイ変更を AKS クラスターに適用すると作成されます (たとえば、 kubectl applyを使用)。 <your-managed-identity-client-id>をクライアント ID に置き換え、<your-managed-identity-tenant-id>を作成したばかりのユーザー割り当てマネージド ID のテナント 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 を使用して、ユーザー割り当てマネージド ID のフェデレーション ID 資格情報を作成します。 <user-assigned-identity-name>を名前に置き換え、<resource-group>を新しく作成したユーザー割り当てマネージド ID のリソース グループに置き換えます。 <aks-oidc-issuer>を AKS クラスターの OIDC 発行者 URL に置き換えます。 <your-service-account-name>を、新しく作成したサービス アカウントの名前に置き換えます。 <federated-identity-credential-name>を、フェデレーション ID 資格情報の優先名に置き換えます。

   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
   

   フェデレーション ID 資格情報のサブジェクトは、次の形式に従う必要があることに注意してください: 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. AzureAppConfigurationProvider リソースと同じ名前空間に Kubernetes シークレットを作成し、キー azure_app_configuration_connection_string を含む Azure App Configuration 接続文字列をシークレットに追加します。

2. spec.connectionStringReference プロパティを次のサンプル AzureAppConfigurationProvider リソースのシークレットの名前に設定し、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 App Configuration からダウンロードするキー値をフィルター処理します。

次の例では、ラベルのないすべてのキー値がダウンロードされます。

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

次の例では、2 つのセレクターが使用され、それぞれ一意のラベルを持つ 2 つのキー値のセットが取得されます。 最後のセレクターの値が優先され、前のセレクターの重複するキーがオーバーライドされることに注意してください。

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 に追加する前にキーの名前から 2 つのプレフィックスをトリミングします。

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 App Configuration でデータを変更する場合は、Kubernetes クラスターでそれらの変更を自動的に更新することが必要になる場合があります。 複数のキー値を更新するのは一般的ですが、更新の途中でクラスターが変更を取得することは望ましくありません。 構成の一貫性を維持するために、キー値を使用して更新の完了を通知できます。 このキー値は、"センチネル キー" と呼ばれます。 Kubernetes プロバイダーはこのキー値を監視できます。ConfigMap とシークレットは、センチネル キーで変更が検出された後にのみ、更新されたデータで再生成されます。

次の例では、app1_sentinel という名前のキー値が 1 分ごとにポーリングされ、センチネル キーで変更が検出されるたびに構成が更新されます。

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 の参照

認証

次のサンプルでは、1 つの Key Vault がサービス プリンシパルで認証され、他のすべての Key Vault はユーザー割り当てマネージド ID で認証されます。

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>

シークレットの種類

現在、シークレット、不透明、TLS の 2 つの Kubernetes 組み込み タイプのシークレットがサポートされています。 Key Vault 参照から解決されたシークレットは、既定で Opaque シークレット 型として保存されます。 証明書への Key Vault 参照があり、TLS シークレットの種類として保存する場合は、次の名前と値を持つタグAzure アプリ構成の Key Vault 参照に追加できます。 これにより、 kubernetes.io/tls 型のシークレットが生成され、Key Vault 参照のキーに基づいて名前が付けられます。

Key Vault からのシークレットの更新

Key Vault からシークレットを更新するには、通常、対応する Key Vault 参照を Azure App Configuration から再度読み込む必要があります。 ただし、spec.secret.refresh プロパティを使用すると、Key Vaultからシークレットを個別に更新できます。 これは、シークレットのローテーション中にワークロードが Key Vault から更新されたシークレットを自動的に取得するようにする場合に特に便利です。 最新バージョンのシークレットを読み込むには、Key Vault 参照がバージョン管理されたシークレットであってはならないことに注意してください。

次のサンプルでは、Key Vault からバージョン管理されていないすべてのシークレットを 1 時間ごとに更新します。

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 App Configuration から取得したデータの項目別一覧が設定されます。これは、環境変数として簡単に使用できます。 configMapData.type プロパティが json、yaml、またはプロパティに設定されている場合、Azure App Configuration から取得されたデータは、生成された ConfigMap の configMapData.key プロパティで指定されたキー名を持つ 1 つの項目にグループ化され、マウントされたファイルとして使用できます。

次の例は、configMapData.type プロパティのさまざまな設定を使って、生成された ConfigMap にデータがどのように設定されるかを示しています。

App Configuration ストアに次のキー値がある場合:

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