Edit

Azure App Configuration Kubernetes Provider reference

  • Article

The following reference outlines the properties supported by the Azure App Configuration Kubernetes Provider.

Properties

An AzureAppConfigurationProvider resource has the following top-level child properties under the spec. Either endpoint or connectionStringReference has to be specified.

Name Description Required Type
endpoint The endpoint of Azure App Configuration, which you would like to retrieve the key-values from. alternative string
connectionStringReference The name of the Kubernetes Secret that contains Azure App Configuration connection string. alternative string
target The destination of the retrieved key-values in Kubernetes. true object
auth The authentication method to access Azure App Configuration. false object
configuration The settings for querying and processing key-values in Azure App Configuration. false object
secret The settings for Key Vault references in Azure App Configuration. conditional object

The spec.target property has the following child property.

Name Description Required Type
configMapName The name of the ConfigMap to be created. true string
configMapData The setting that specifies how the retrieved data should be populated in the generated ConfigMap. false object

If the spec.target.configMapData property is not set, the generated ConfigMap will be populated with the list of key-values retrieved from Azure App Configuration, which allows the ConfigMap to be consumed as environment variables. Update this property if you wish to consume the ConfigMap as a mounted file. This property has the following child properties.

Name Description Required Type
type The setting that indicates how the retrieved data is constructed in the generated ConfigMap. The allowed values include default, json, yaml and properties. optional string
key The key name of the retrieved data when the type is set to json, yaml or properties. Set it to the file name if the ConfigMap is set up to be consumed as a mounted file. conditional string

The spec.auth property isn't required if the connection string of your App Configuration store is provided by setting the spec.connectionStringReference property. Otherwise, one of the identities, service principal, workload identity, or managed identity, will be used for authentication. The spec.auth has the following child properties. Only one of them should be specified. If none of them are set, the system-assigned managed identity of the virtual machine scale set will be used.

Name Description Required Type
servicePrincipalReference The name of the Kubernetes Secret that contains the credentials of a service principal. false string
workloadIdentity The settings for using workload identity. false object
managedIdentityClientId The Client ID of user-assigned managed identity of virtual machine scale set. false string

The spec.auth.workloadIdentity property has the following child property.

Name Description Required Type
managedIdentityClientId The Client ID of the user-assigned managed identity associated with the workload identity. true string

The spec.configuration has the following child properties.

Name Description Required Type
selectors The list of selectors for key-value filtering. false object array
trimKeyPrefixes The list of key prefixes to be trimmed. false string array
refresh The settings for refreshing data from Azure App Configuration. If the property is absent, data from Azure App Configuration will not be refreshed. false object

If the spec.configuration.selectors property isn't set, all key-values with no label will be downloaded. It contains an array of selector objects, which have the following child properties.

Name Description Required Type
keyFilter The key filter for querying key-values. true string
labelFilter The label filter for querying key-values. false string

The spec.configuration.refresh property has the following child properties.

Name Description Required Type
enabled The setting that determines whether data from Azure App Configuration is automatically refreshed. If the property is absent, a default value of false will be used. false bool
monitoring The key-values monitored for change detection, aka sentinel keys. The data from Azure App Configuration will be refreshed only if at least one of the monitored key-values is changed. true object
interval The interval at which the data will be refreshed from Azure App Configuration. It must be greater than or equal to 1 second. If the property is absent, a default value of 30 seconds will be used. false duration string

The spec.configuration.refresh.monitoring.keyValues is an array of objects, which have the following child properties.

Name Description Required Type
key The key of a key-value. true string
label The label of a key-value. false string

The spec.secret property has the following child properties. It is required if any Key Vault references are expected to be downloaded.

Name Description Required Type
target The destination of the retrieved secrets in Kubernetes. true object
auth The authentication method to access Key Vaults. false object
refresh The settings for refreshing data from Key Vaults. If the property is absent, data from Key Vaults will not be refreshed unless the corresponding Key Vault references are reloaded. false object

The spec.secret.target property has the following child property.

Name Description Required Type
secretName The name of the Kubernetes Secret to be created. true string

If the spec.secret.auth property isn't set, the system-assigned managed identity is used. It has the following child properties.

Name Description Required Type
servicePrincipalReference The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with Key Vaults that don't have individual authentication methods specified. false string
workloadIdentity The settings of the workload identity used for authentication with Key Vaults that don't have individual authentication methods specified. It has the same child properties as spec.auth.workloadIdentity. false object
managedIdentityClientId The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with Key Vaults that don't have individual authentication methods specified. false string
keyVaults The authentication methods for individual Key Vaults. false object array

The authentication method of each Key Vault can be specified with the following properties. One of managedIdentityClientId, servicePrincipalReference or workloadIdentity must be provided.

Name Description Required Type
uri The URI of a Key Vault. true string
servicePrincipalReference The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with a Key Vault. false string
workloadIdentity The settings of the workload identity used for authentication with a Key Vault. It has the same child properties as spec.auth.workloadIdentity. false object
managedIdentityClientId The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with a Key Vault. false string

The spec.secret.refresh property has the following child property.

Name Description Required Type
enabled The setting that determines whether data from Key Vaults is automatically refreshed. If the property is absent, a default value of false will be used. false bool
interval The interval at which the data will be refreshed from Key Vault. It must be greater than or equal to 1 minute. The Key Vault refresh is independent of the App Configuration refresh configured via spec.configuration.refresh. true duration string

Examples

Authentication

Use system-assigned managed identity of virtual machine scale set

  1. Enable the system-assigned managed identity in the virtual machine scale set used by the Azure Kubernetes Service (AKS) cluster.

  2. Grant the system-assigned managed identity App Configuration Data Reader role in Azure App Configuration.

  3. Deploy the following sample AzureAppConfigurationProvider resource to the AKS cluster.

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

Use user-assigned managed identity of virtual machine scale set

  1. Create a user-assigned managed identity and note down its client ID after creation.

  2. Assign the user-assigned managed identity to the virtual machine scale set used by the Azure Kubernetes Service (AKS) cluster.

  3. Grant the user-assigned managed identity App Configuration Data Reader role in Azure App Configuration.

  4. Set the spec.auth.managedIdentityClientId property to the client ID of the user-assigned managed identity in the following sample AzureAppConfigurationProvider resource and deploy it to the AKS cluster.

    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>

Use service principal

  1. Create a Service Principal

  2. Grant the service principal App Configuration Data Reader role in Azure App Configuration.

  3. Create a Kubernetes Secret in the same namespace as the AzureAppConfigurationProvider resource and add azure_client_id, azure_client_secret, and azure_tenant_id of the service principal to the Secret.

  4. Set the spec.auth.servicePrincipalReference property to the name of the Secret in the following sample AzureAppConfigurationProvider resource and deploy it to the Kubernetes cluster.

    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>

Use workload identity

  1. Enable Workload Identity on the Azure Kubernetes Service (AKS) cluster.

  2. Get the OIDC issuer URL of the AKS cluster.

  3. Create a user-assigned managed identity and note down its client ID after creation.

  4. Create the federated identity credential between the managed identity, OIDC issuer, and subject using the Azure CLI.

    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. Grant the user-assigned managed identity App Configuration Data Reader role in Azure App Configuration.

  6. Set the spec.auth.workloadIdentity.managedIdentityClientId property to the client ID of the user-assigned managed identity in the following sample AzureAppConfigurationProvider resource and deploy it to the AKS cluster.

    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>

Use connection string

  1. Create a Kubernetes Secret in the same namespace as the AzureAppConfigurationProvider resource and add Azure App Configuration connection string with key azure_app_configuration_connection_string in the Secret.

  2. Set the spec.connectionStringReference property to the name of the Secret in the following sample AzureAppConfigurationProvider resource and deploy it to the Kubernetes cluster.

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

Key-value selection

Use the selectors property to filter the key-values to be downloaded from Azure App Configuration.

The following sample downloads all key-values with no label.

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

In following example, two selectors are used to retrieve two sets of key-values, each with unique labels. It's important to note that the values of the last selector take precedence and override any overlapping keys from the previous selectors.

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

Key prefix trimming

The following sample uses the trimKeyPrefixes property to trim two prefixes from key names before adding them to the generated 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]

Configuration refresh

When you make changes to your data in Azure App Configuration, you might want those changes to be refreshed automatically in your Kubernetes cluster. It's common to update multiple key-values, but you don't want the cluster to pick up a change midway through the update. To maintain configuration consistency, you can use a key-value to signal the completion of your update. This key-value is known as the sentinel key. The Kubernetes provider can monitor this key-value, and the ConfigMap and Secret will only be regenerated with updated data once a change is detected in the sentinel key.

In the following sample, a key-value named app1_sentinel is polled every minute, and the configuration is refreshed whenever changes are detected in the sentinel key.

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 references

In the following sample, one Key Vault is authenticated with a service principal, while all other Key Vaults are authenticated with a user-assigned managed identity.

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>

Refresh of secrets from Key Vault

Refreshing secrets from Key Vaults usually requires reloading the corresponding Key Vault references from Azure App Configuration. However, with the spec.secret.refresh property, you can refresh the secrets from Key Vault independently. This is especially useful for ensuring that your workload automatically picks up any updated secrets from Key Vault during secret rotation. Note that to load the latest version of a secret, the Key Vault reference must not be a versioned secret.

The following sample refreshes all non-versioned secrets from Key Vault every hour.

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

ConfigMap Consumption

Applications running in Kubernetes typically consume the ConfigMap either as environment variables or as configuration files. If the configMapData.type property is absent or is set to default, the ConfigMap is populated with the itemized list of data retrieved from Azure App Configuration, which can be easily consumed as environment variables. If the configMapData.type property is set to json, yaml or properties, data retrieved from Azure App Configuration is grouped into one item with key name specified by the configMapData.key property in the generated ConfigMap, which can be consumed as a mounted file.

The following examples show how the data is populated in the generated ConfigMap with different settings of the configMapData.type property.

Assuming an App Configuration store has these key-values:

key value
key1 value1
key2 value2
key3 value3

and the configMapData.type property is absent or set to 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

the generated ConfigMap will be populated with the following data:

data:
  key1: value1
  key2: value2
  key3: value3