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

  • [アーティクル]

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

プロパティ

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

名前 説明 必須 Type
endpoint キー値を取得する Azure App Configuration のエンドポイント。 代替手段 string
connectionStringReference Azure App Configuration 接続文字列を含む Kubernetes シークレットの名前。 代替手段 string
replicaDiscoveryEnabled Azure アプリ構成のレプリカが自動的に検出され、フェールオーバーに使用されるかどうかを決定する設定。 プロパティがない場合は、既定値が true 使用されます。 false [bool]
ターゲット Kubernetes で取得したキー値の宛先。 true object
auth Azure App Configuration にアクセスするための認証方法。 false object
configuration Azure App Configuration でのキー値のクエリと処理の設定。 false object
シークレット Azure App Configuration での Key Vault 参照の設定。 条件付 オブジェクト
featureFlag Azure アプリ構成の機能フラグの設定。 false object

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

名前 説明 必須 Type
configMapName 作成する ConfigMap の名前。 true string
configMapData 取得したデータを生成された ConfigMap にどのように設定するかを指定する設定。 false オブジェクト

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

名前 説明 必須 タイプ
type 取得したデータが生成された ConfigMap でどのように構築されるかを示す設定。 指定できる値は、default、json、yaml、properties です。 省略可能 string
key type が json、yaml、または properties に設定されている場合に取得されるデータのキー名。 ConfigMap がマウントされたファイルとして使われるように設定されている場合は、ファイル名に設定します。 条件付 string
separator 型が設定jsonyamlされている場合に、ConfigMap データを階層形式で出力するために使用される区切り記号。 区切り記号は既定では空で、生成された ConfigMap には元の形式のキー値が含まれています。 この設定は、アプリケーションで使用される構成ファイル ローダーが、階層形式に変換せずにキー値を読み込めない場合にのみ構成します。 省略可能 string

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

名前 説明 必須 Type
servicePrincipalReference サービス プリンシパルの資格情報を含む Kubernetes シークレットの名前。 シークレットは、Kubernetes プロバイダーと同じ名前空間に存在する必要があります。 false string
workloadIdentity ワークロード ID を使うための設定。 false object
managedIdentityClientId 仮想マシン スケール セットのユーザー割り当てマネージド ID のクライアント ID。 false string

spec.auth.workloadIdentity プロパティには、次の子プロパティがあります。 そのうちの 1 つを指定する必要があります。

名前 説明 必須 Type
managedIdentityClientId ワークロード ID に関連付けられているユーザー割り当てマネージド ID のクライアント ID。 代替手段 string
managedIdentityClientIdReference ユーザー割り当てマネージド ID のクライアント ID は、ConfigMap から取得できます。 ConfigMap は、Kubernetes プロバイダーと同じ名前空間に存在する必要があります。 代替手段 オブジェクト

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

名前 説明 必須 Type
configMap ユーザー割り当てマネージド ID のクライアント ID が見つかる ConfigMap の名前。 true string
キー ユーザー割り当てマネージド ID のクライアント ID の値を保持するキー名。 true string

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

名前 説明 必須 Type
selectors キー値のフィルター処理用のセレクターの一覧。 false オブジェクト配列
trimKeyPrefixes トリミングするキー プレフィックスの一覧。 false 文字列配列
更新 Azure アプリ構成からキー値を更新するための設定。 プロパティがない場合、Azure アプリ Configuration のキー値は更新されません。 false オブジェクト

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

名前 説明 必須 Type
keyFilter キー値のクエリを実行するためのキー フィルター。 このプロパティとプロパティを snapshotName 同時に設定しないでください。 代替手段 string
labelFilter キー値のクエリを実行するためのラベル フィルター。 このプロパティとプロパティを snapshotName 同時に設定しないでください。 false string
スナップショットName キー値の読み込み元となるスナップショットの名前。 このプロパティは、他のプロパティと組み合わせて使用しないでください。 代替手段 string

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

名前 説明 必須 Type
有効 Azure アプリ構成のキー値が自動的に更新されるかどうかを決定する設定。 プロパティがない場合は、既定値が false 使用されます。 false [bool]
監視 変更検出用に監視されるキー値 (別名: センチネル キー)。 Azure アプリ構成のキー値は、監視対象のキー値の少なくとも 1 つが変更された場合にのみ更新されます。 true object
interval Azure アプリ構成からキー値が更新される間隔。 1 秒以上である必要があります。 このプロパティがない場合は、既定値の 30 秒が使用されます。 false 期間文字列

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

名前 説明 必須 種類
key キー値のキー。 true string
label キー値のラベル。 false string

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

名前 説明 必須 Type
ターゲット Kubernetes で取得したシークレットの宛先。 true object
auth Key Vault にアクセスするための認証方法。 false object
更新 Key Vault からデータを更新するための設定。 プロパティがない場合、対応する Key Vault 参照が再読み込みされない限り、Key Vault からのデータは更新されません。 false object

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

名前 説明 必須 Type
secretName 作成する Kubernetes シークレットの名前。 true string

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

名前 説明 必須 Type
servicePrincipalReference 個別の認証方法が指定されていないキー コンテナーでの認証に使われるサービス プリンシパルの資格情報を含む、Kubernetes シークレットの名前。 false string
workloadIdentity 個別の認証方法が指定されていないキー コンテナーでの認証に使われるワークロード ID の設定。 spec.auth.workloadIdentity と同じ子プロパティがあります。 false object
managedIdentityClientId 個別の認証方法が指定されていないキー コンテナーでの認証に使われる、仮想マシン スケール セットのユーザー割り当てマネージド ID のクライアント ID。 false string
keyVaults 個々のキー コンテナーの認証方法。 false オブジェクト配列

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

名前 説明 必須 Type
uri キー コンテナーの URI。 true string
servicePrincipalReference キー コンテナーでの認証に使われるサービス プリンシパルの資格情報を含む、Kubernetes シークレットの名前。 false string
workloadIdentity キー コンテナーでの認証に使われるワークロード ID の設定。 spec.auth.workloadIdentity と同じ子プロパティがあります。 false object
managedIdentityClientId キー コンテナーでの認証に使われる仮想マシン スケール セットのユーザー割り当てマネージド ID のクライアント ID。 false string

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

名前 説明 必須 Type
有効 キー コンテナーからのデータが自動的に更新されるかどうかを決定する設定。 プロパティがない場合は、既定値が false 使用されます。 false [bool]
interval Key Vault からデータが更新される間隔。 1 分以上である必要があります。 Key Vault 更新は、spec.configuration.refresh を使用して構成された App Configuration 更新とは無関係です。 true 期間文字列

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

名前 説明 必須 Type
selectors 機能フラグ フィルター処理のセレクターの一覧。 false オブジェクト配列
更新 Azure アプリ構成から機能フラグを更新するための設定。 このプロパティがない場合、Azure アプリ Configuration の機能フラグは更新されません。 false オブジェクト

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

名前 説明 必須 Type
keyFilter 機能フラグのクエリを実行するためのキー フィルター。 このプロパティとプロパティを snapshotName 同時に設定しないでください。 代替手段 string
labelFilter 機能フラグのクエリを実行するためのラベル フィルター。 このプロパティとプロパティを snapshotName 同時に設定しないでください。 false string
スナップショットName 機能フラグの読み込み元となるスナップショットの名前。 このプロパティは、他のプロパティと組み合わせて使用しないでください。 代替手段 string

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

名前 説明 必須 Type
有効 Azure アプリ構成の機能フラグが自動的に更新されるかどうかを決定する設定。 プロパティがない場合は、既定値が false 使用されます。 false [bool]
interval Azure アプリ構成から機能フラグが更新される間隔。 1 秒以上である必要があります。 このプロパティがない場合は、既定値の 30 秒が使用されます。 false 期間文字列

インストール

次helm installのコマンドを使用して、Azure アプリ Configuration 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

自動スケール

既定では、自動スケーリングは無効です。 ただし、複数の Configマップ/Secrets を生成する複数AzureAppConfigurationProviderのリソースがある場合は、autoscaling.enabledtrue

例

認証

仮想マシン スケール セットのシステム割り当てマネージド 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 をメモします。

  4. Azure CLI を使用して、マネージド ID、OIDC 発行者、サブジェクト間のフェデレーション 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:azappconfig-system:az-appconfig-k8s-provider --audience api://AzureADTokenExchange

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

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

接続文字列の使用

  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>

シークレットの種類

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

名前 値
.kubernetes.secret.type kubernetes.io/tls

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 分ごとにダウンロードおよび更新されます。

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

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

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

key value
key1 value1
key2 value2
key3 値3

また、 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