Referência do Provedor de Kubernetes da Configuração de Aplicativos do Azure

A referência a seguir descreve as propriedades compatíveis com o Provedor de Kubernetes da Configuração de Aplicativos do v2.1.0Azure. Consulte as notas de versão para obter mais informações sobre a alteração.

Propriedades

Um recurso AzureAppConfigurationProvider tem as seguintes propriedades filho de nível superior sob o spec. endpoint ou connectionStringReference precisa ser especificado.

A propriedade spec.target tem a propriedade filho a seguir.

Se a spec.target.configMapData propriedade não estiver definida, o ConfigMap gerado será preenchido com a lista de valores-chave recuperados da Configuração de Aplicativos do Azure, o que permite que o ConfigMap seja consumido como variáveis de ambiente. Atualize essa propriedade se desejar consumir o ConfigMap como um arquivo montado. Essa propriedade tem as propriedades filho a seguir.

A propriedade spec.auth não será necessária se a cadeia de conexão do repositório da Configuração de Aplicativos for fornecida definindo a propriedade spec.connectionStringReference. Caso contrário, uma das identidades, entidade de serviço, identidade de carga de trabalho ou identidade gerenciada será usada para autenticação. O spec.auth tem as propriedades filho a seguir. Apenas uma delas deve ser especificada. Se nenhum deles for definido, a identidade gerenciada atribuída pelo sistema do conjunto de dimensionamento de máquinas virtuais será usada.

A propriedade spec.auth.workloadIdentity tem a propriedade filho a seguir.

O spec.configuration tem as propriedades filho a seguir.

Se a spec.configuration.selectors propriedade não estiver definida, todas as chaves-valor sem rótulo serão baixadas. Contém uma matriz de objetos seletores, que têm as propriedades filho a seguir. Observe que as chaves-valor do último seletor têm precedência e substituem quaisquer chaves sobrepostas dos seletores anteriores.

A propriedade spec.configuration.refresh tem as propriedades filho a seguir.

O spec.configuration.refresh.monitoring.keyValues é uma matriz de objetos que contém as propriedades filho a seguir.

A propriedade spec.secret tem as propriedades filho a seguir. É necessário se alguma referência do Key Vault deve ser baixada. Para saber mais sobre o suporte para tipos de segredos internos do Kubernetes, consulte Tipos de segredos.

A propriedade spec.secret.target tem a propriedade filho a seguir.

Se a propriedade spec.secret.auth não estiver definida, a identidade gerenciada atribuída pelo sistema será usada. Ele tem as propriedades filho a seguir.

O método de autenticação de cada Key Vault pode ser especificado com as propriedades a seguir. Um de managedIdentityClientId, servicePrincipalReference ou workloadIdentity deve ser fornecido.

A propriedade spec.secret.refresh tem as propriedades filho a seguir.

A propriedade spec.featureFlag tem as propriedades filho a seguir. Ele é necessário se algum sinalizador de recurso for baixado.

Se a spec.featureFlag.selectors propriedade não estiver definida, os sinalizadores de recurso não serão baixados. Contém uma matriz de objetos seletores, que têm as propriedades filho a seguir. Observe que os sinalizadores de recurso do último seletor têm precedência e substituem quaisquer chaves sobrepostas dos seletores anteriores.

A propriedade spec.featureFlag.refresh tem as propriedades filho a seguir.

Instalação

Use o comando a seguir helm install para instalar o Provedor de Kubernetes da Configuração de Aplicativos do Azure. Consulte helm-values.yaml para obter a lista completa de parâmetros e seus valores padrão. Você pode substituir os valores padrão passando o --set sinalizador para o comando.

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

Dimensionamento automático

Por padrão, o dimensionamento automático está desabilitado. No entanto, se você tiver vários AzureAppConfigurationProvider recursos para produzir vários ConfigMaps/Secrets, poderá ativar o dimensionamento automático horizontal do pod definindo autoscaling.enabled como true.

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

Coleta de dados

O software pode coletar informações sobre você e seu uso do software e enviá-las à Microsoft. A Microsoft pode usar essas informações para fornecer serviços e aprimorar nossos produtos e serviços. Você pode desativar a telemetria definindo o requestTracing.enabled=false durante a instalação do Provedor de Kubernetes da Configuração de Aplicativos do Azure. Há também alguns recursos no software que podem permitir que você e a Microsoft coletem dados dos usuários de seus aplicativos. Se você usar esses recursos, deverá cumprir a lei aplicável, incluindo o fornecimento de avisos apropriados aos usuários de seus aplicativos, juntamente com uma cópia da política de privacidade da Microsoft. Nossa política de privacidade está localizada em https://go.microsoft.com/fwlink/?LinkID=824704. Você pode saber mais sobre a coleta e o uso de dados na documentação de ajuda e em nossa declaração de privacidade. Usar o software significa que você autoriza essas práticas.

Exemplos

Autenticação

Usar a identidade gerenciada atribuída pelo sistema de um conjunto de dimensionamento de máquinas virtuais

1. Habilite a identidade gerenciada atribuída pelo sistema no conjunto de dimensionamento de máquinas virtuais usado pelo cluster do Serviço de Kubernetes do Azure (AKS).

2. Conceda a função de Leitor de Dados da Configuração de Aplicativos da identidade gerenciada atribuída pelo sistema na Configuração de Aplicativos do Azure.

3. Implante o recurso de amostra AzureAppConfigurationProvider a seguir no cluster do 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
   

Usar a identidade gerenciada atribuída pelo usuário de um conjunto de dimensionamento de máquinas virtuais

1. Crie uma identidade gerenciada atribuída pelo usuário e anote sua ID de cliente após a criação.

2. Atribua a identidade gerenciada atribuída pelo usuário ao conjunto de dimensionamento de máquinas virtuais usado pelo cluster do Serviço de Kubernetes do Azure (AKS).

3. Conceda a função de Leitor de Dados de Configuração de Aplicativos da identidade gerenciada atribuída pelo sistema na Configuração de Aplicativos do Azure.

4. Defina a propriedade spec.auth.managedIdentityClientId como a ID do cliente da identidade gerenciada atribuída pelo usuário no recurso de amostra AzureAppConfigurationProvider a seguir e implante-a no cluster do 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>
   

Usar a entidade de serviço

1. Criar uma entidade de serviço

2. Conceda à entidade de serviço a função de Leitor de Dados de Configuração de Aplicativo na Configuração de Aplicativos do Azure.

3. Crie um Segredo do Kubernetes no mesmo namespace que o recurso AzureAppConfigurationProvider e adicione azure_client_id, azure_client_secret e azure_tenant_id da entidade de serviço ao Segredo.

4. Defina a propriedade spec.auth.servicePrincipalReference como o nome do Segredo no recurso de amostra AzureAppConfigurationProvider a seguir e implante-a no cluster do 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>
   

Usar a identidade da carga de trabalho

1. Habilite a Identidade da Carga de Trabalho no cluster do AKS (Serviço de Kubernetes do Azure).

2. Obtenha o URL do emissor do OIDC do cluster do AKS.

3. Crie uma identidade gerenciada atribuída pelo usuário e anote sua ID do cliente, ID do locatário, nome e grupo de recursos.

4. Conceda a função de Leitor de Dados de Configuração de Aplicativos da identidade gerenciada atribuída pelo sistema na Configuração de Aplicativos do Azure.

5. Crie uma conta de serviço adicionando um arquivo YAML (por exemplo, serviceAccount.yaml) com o conteúdo a seguir ao diretório que contém os arquivos de implantação do AKS. A conta de serviço será criada quando você aplicar todas as alterações de implantação ao cluster do AKS (por exemplo, usando kubectl apply). Substitua <your-managed-identity-client-id> pela ID do cliente e <your-managed-identity-tenant-id> pela ID do locatário da identidade gerenciada atribuída pelo usuário que acabou de ser criada. Substitua <your-service-account-name> pelo nome de sua preferência.

   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. Crie uma credencial de identidade federada para a identidade gerenciada atribuída pelo usuário usando a CLI do Azure. Substitua <user-assigned-identity-name> pelo nome e <resource-group> pelo grupo de recursos da identidade gerenciada atribuída pelo usuário recém-criada. Substitua <aks-oidc-issuer> pela URL do emissor do OIDC do cluster do AKS. Substitua <your-service-account-name> pelo nome da conta de serviço recém-criada. Substitua <federated-identity-credential-name> pelo nome de sua preferência para a credencial de identidade federada.

   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
   

   Observe que o assunto da credencial de identidade federada deve seguir este formato: system:serviceaccount:<service-account-namespace>:<service-account-name>.

7. Defina a spec.auth.workloadIdentity.serviceAccountName propriedade como o nome da conta de serviço no recurso de exemplo AzureAppConfigurationProvider a seguir. Certifique-se de que o AzureAppConfigurationProvider recurso e a conta de serviço estejam no mesmo namespace.

   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>
   

Usar a cadeia de conexão

1. Crie um Segredo do Kubernetes no mesmo namespace que o recurso AzureAppConfigurationProvider e adicione a cadeia de conexão da Configuração de Aplicativos do Azure com a chave azure_app_configuration_connection_string no Segredo.

2. Defina a propriedade spec.connectionStringReference como o nome do Segredo no recurso de amostra AzureAppConfigurationProvider a seguir e implante-a no cluster do 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
   

Seleção de valor-chave

Use a propriedade selectors para filtrar os valores-chave a serem baixados da Configuração de Aplicativos do Azure.

A amostra a seguir baixa todos os valores-chave sem rótulo.

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

No exemplo a seguir, dois seletores são usados para recuperar dois conjuntos de valores-chave, cada um com rótulos exclusivos. É importante observar que os valores do último seletor têm precedência e substituem as chaves sobrepostas dos seletores anteriores.

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

Um instantâneo pode ser usado sozinho ou em conjunto com outros seletores de chave-valor. No exemplo a seguir, você carrega valores-chave de configuração comum de um instantâneo e, em seguida, substitui alguns deles por valores-chave para desenvolvimento.

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

Corte de prefixo de chave

A amostra a seguir usa a propriedade trimKeyPrefixes para cortar dois prefixos de nomes-chave antes de adicioná-los ao ConfigMap gerado.

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]

Atualização de configuração

Ao fazer alterações nos dados na Configuração de Aplicativos do Azure, talvez você queira que essas alterações sejam atualizadas automaticamente no cluster do Kubernetes. É comum atualizar vários valores de chave, mas você não deseja que o cluster pegue uma alteração no meio da atualização. Para manter a consistência da configuração, você pode usar uma chave-valor para sinalizar a conclusão da atualização. Essa chave-valor é conhecida como a chave sentinela. O provedor do Kubernetes pode monitorar esse valor-chave. O ConfigMap e o Segredo só serão regenerados com dados atualizados depois que uma alteração for detectada na chave sentinela.

No exemplo a seguir, um valor-chave chamado app1_sentinel é sondado a cada minuto e a configuração é atualizada sempre que as alterações são detectadas na chave sentinela.

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

Referências de Key Vault

Autenticação

No exemplo a seguir, um Key Vault é autenticado com uma entidade de serviço, enquanto todos os outros Key Vaults são autenticados com uma identidade gerenciada atribuída pelo usuário.

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>

Tipos de segredo

Atualmente, há suporte para dois tipos de segredos integrados do Kubernetes, Opaque e TLS. Os segredos resolvidos de referências do Key Vault são salvos como o tipo Segredo Opaco por padrão. Se você tiver uma referência do Key Vault a um certificado e quiser salvá-la como o tipo de Segredo TLS, poderá adicionar uma marca com o seguinte nome e valor à referência do Key Vault na Configuração de Aplicativos do Azure. Ao fazer isso, um Segredo com o kubernetes.io/tls tipo será gerado e nomeado após a chave da referência do Key Vault.

Os exemplos a seguir mostram como os dados são preenchidos nos Segredos gerados com diferentes tipos.

Supondo que um repositório da Configuração de Aplicativos tenha estas referências do Key Vault:

O exemplo a seguir gera segredos dos tipos Opaque e 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>

Os segredos gerados são preenchidos com os seguintes dados:

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>

Atualização de segredos do Key Vault

A atualização de segredos dos Key Vaults geralmente requer o recarregamento das referências de Key Vault correspondentes de Configuração de Aplicativos do Azure. No entanto, com a propriedade spec.secret.refresh, você pode atualizar os segredos de Key Vault independentemente. Isso é especialmente útil para garantir que sua carga de trabalho pegue automaticamente todos os segredos atualizados de Key Vault durante a rotação de segredos. Observe que, para carregar a versão mais recente de um segredo, a referência de Key Vault não deve ser um segredo com controle de versão.

O exemplo a seguir atualiza todos os segredos sem controle de versão de Key Vault a cada hora.

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

Sinalizadores de Recursos

No exemplo a seguir, os sinalizadores de recursos com chaves começando com app1 e rótulos equivalentes a são baixados e atualizados a common cada 10 minutos. Observe que, para preencher sinalizadores de recursos no ConfigMap gerado, a configMapData.type propriedade deve ser json ou 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

Consumo de ConfigMap

Os aplicativos em execução no Kubernetes normalmente consomem o ConfigMap como variáveis de ambiente ou como arquivos de configuração. Se a propriedade configMapData.type estiver ausente ou estiver definida como padrão, o ConfigMap será preenchido com a lista detalhada de dados recuperados da Configuração de Aplicativos do Azure, que podem ser facilmente consumidos como variáveis de ambiente. Se a propriedade configMapData.type estiver definida como json, yaml ou propriedades, os dados recuperados da Configuração de Aplicativos do Azure serão agrupados em um item com o nome da chave especificado pela propriedade configMapData.key no ConfigMap gerado, que pode ser consumido como um arquivo montado.

Os exemplos a seguir mostram como os dados são preenchidos no ConfigMap gerado com as configurações diferentes da propriedade configMapData.type.

Supondo que um repositório da Configuração de Aplicativos tenha estas chaves-valores:

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