Informazioni di riferimento sul provider Kubernetes di configurazione app Azure

Il riferimento seguente illustra le proprietà supportate dal provider Kubernetes v2.1.0di configurazione app Azure . Per altre informazioni sulla modifica, vedere le note sulla versione.

Proprietà

Una AzureAppConfigurationProvider risorsa ha le proprietà figlio di primo livello seguenti in spec. È endpoint necessario specificare o connectionStringReference .

La spec.target proprietà ha la proprietà figlio seguente.

Se la spec.target.configMapData proprietà non è impostata, l'oggetto ConfigMap generato viene popolato con l'elenco di valori chiave recuperati da app Azure Configuration, che consente l'utilizzo di ConfigMap come variabili di ambiente. Aggiornare questa proprietà se si desidera utilizzare ConfigMap come file montato. Questa proprietà ha le proprietà figlio seguenti.

La spec.auth proprietà non è necessaria se la stringa di connessione dell'archivio Configurazione app viene fornita impostando la spec.connectionStringReference proprietà . In caso contrario, per l'autenticazione viene usata una delle identità, dell'entità servizio, dell'identità del carico di lavoro o dell'identità gestita. ha spec.auth le proprietà figlio seguenti. È necessario specificare solo uno di essi. Se nessuno di essi è impostato, viene usata l'identità gestita assegnata dal sistema del set di scalabilità di macchine virtuali.

La spec.auth.workloadIdentity proprietà ha la proprietà figlio seguente.

ha spec.configuration le proprietà figlio seguenti.

Se la spec.configuration.selectors proprietà non è impostata, vengono scaricati tutti i valori chiave senza etichetta. Contiene una matrice di oggetti selettore , che hanno le proprietà figlio seguenti. Si noti che i valori chiave dell'ultimo selettore hanno la precedenza ed eseguono l'override di eventuali chiavi sovrapposte dai selettori precedenti.

La spec.configuration.refresh proprietà ha le proprietà figlio seguenti.

spec.configuration.refresh.monitoring.keyValues è una matrice di oggetti con le proprietà figlio seguenti.

La spec.secret proprietà ha le proprietà figlio seguenti. È necessario se è previsto che vengano scaricati riferimenti a Key Vault. Per altre informazioni sul supporto per i tipi predefiniti di segreti kubernetes, vedere Tipi di segreti.

La spec.secret.target proprietà ha la proprietà figlio seguente.

Se la spec.secret.auth proprietà non è impostata, viene usata l'identità gestita assegnata dal sistema. Ha le proprietà figlio seguenti.

Il metodo di autenticazione di ogni insieme di credenziali delle chiavi può essere specificato con le proprietà seguenti. È necessario specificare uno di managedIdentityClientIdo servicePrincipalReference workloadIdentity .

La spec.secret.refresh proprietà ha le proprietà figlio seguenti.

La spec.featureFlag proprietà ha le proprietà figlio seguenti. È necessario se è previsto il download di eventuali flag di funzionalità.

Se la spec.featureFlag.selectors proprietà non è impostata, i flag di funzionalità non vengono scaricati. Contiene una matrice di oggetti selettore , che hanno le proprietà figlio seguenti. Si noti che i flag di funzionalità dell'ultimo selettore hanno la precedenza ed eseguono l'override di eventuali chiavi sovrapposte dai selettori precedenti.

La spec.featureFlag.refresh proprietà ha le proprietà figlio seguenti.

Installazione

Usare il comando seguente helm install per installare il provider Kubernetes di configurazione app Azure. Per l'elenco completo dei parametri e dei relativi valori predefiniti, vedere helm-values.yaml . È possibile eseguire l'override dei valori predefiniti passando il --set flag al comando .

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

Scalabilità automatica

Per impostazione predefinita, la scalabilità automatica è disabilitata. Tuttavia, se si dispone di più AzureAppConfigurationProvider risorse per produrre più ConfigMaps/Secrets, è possibile abilitare la scalabilità automatica orizzontale dei pod impostando su 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

Raccolta dati

Il software può raccogliere informazioni sull'utente e sull'uso del software e inviarlo a Microsoft. Microsoft potrà utilizzarle per erogare i servizi e migliorare i prodotti e i servizi offerti. È possibile disattivare i dati di telemetria impostando durante l'installazione requestTracing.enabled=false del provider Kubernetes di configurazione app Azure. Esistono anche alcune funzionalità del software che possono consentire all'utente e a Microsoft di raccogliere dati dagli utenti delle applicazioni. Se si usano queste funzionalità, è necessario rispettare la legge applicabile, inclusa la fornitura di comunicazioni appropriate agli utenti delle applicazioni insieme a una copia dell'informativa sulla privacy di Microsoft. L’informativa sulla privacy di Microsoft si trova all’indirizzo https://go.microsoft.com/fwlink/?LinkID=824704. Ulteriori informazioni sulla raccolta e il trattamento dei dati sono disponibili nella documentazione e nell’informativa sulla privacy. L’utilizzo del software da parte del licenziatario costituisce accettazione implicita di tali criteri.

Esempi

Autenticazione

Usare l'identità gestita assegnata dal sistema del set di scalabilità di macchine virtuali

1. Abilitare l'identità gestita assegnata dal sistema nel set di scalabilità di macchine virtuali usato dal cluster del servizio Azure Kubernetes (servizio Azure Kubernetes).

2. Concedere l'identità gestita assegnata dal sistema Configurazione app ruolo Lettore dati in configurazione app Azure.

3. Distribuire la risorsa di esempio AzureAppConfigurationProvider seguente nel cluster del servizio Azure 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
   

Usare l'identità gestita assegnata dall'utente del set di scalabilità di macchine virtuali

1. Creare un'identità gestita assegnata dall'utente e annotare l'ID client dopo la creazione.

2. Assegnare l'identità gestita assegnata dall'utente al set di scalabilità di macchine virtuali usato dal cluster servizio Azure Kubernetes (servizio Azure Kubernetes).

3. Concedere l'identità gestita assegnata dall'utente Configurazione app ruolo Lettore dati in configurazione app Azure.

4. Impostare la spec.auth.managedIdentityClientId proprietà sull'ID client dell'identità gestita assegnata dall'utente nella risorsa di esempio AzureAppConfigurationProvider seguente e distribuirla nel cluster del servizio Azure 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:
       managedIdentityClientId: <your-managed-identity-client-id>
   

Usare l'entità servizio

1. Creare un'entità servizio

2. Concedere all'entità servizio Configurazione app ruolo Lettore dati in configurazione app Azure.

3. Creare un segreto Kubernetes nello stesso spazio dei nomi della AzureAppConfigurationProvider risorsa e aggiungere azure_client_id, azure_client_secret e azure_tenant_id dell'entità servizio al segreto.

4. Impostare la spec.auth.servicePrincipalReference proprietà sul nome del segreto nella risorsa di esempio AzureAppConfigurationProvider seguente e distribuirla nel cluster 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>
   

Usare l'identità del carico di lavoro

1. Abilitare l'identità del carico di lavoro nel cluster servizio Azure Kubernetes (servizio Azure Kubernetes).

2. Ottenere l'URL dell'autorità di certificazione OIDC del cluster del servizio Azure Kubernetes.

3. Creare un'identità gestita assegnata dall'utente e annotare l'ID client, l'ID tenant, il nome e il gruppo di risorse.

4. Concedere l'identità gestita assegnata dall'utente Configurazione app ruolo Lettore dati in configurazione app Azure.

5. Creare un account del servizio aggiungendo un file YAML ,ad esempio serviceAccount.yaml, con il contenuto seguente nella directory contenente i file di distribuzione del servizio Azure Kubernetes. L'account del servizio verrà creato quando si applicano tutte le modifiche alla distribuzione al cluster del servizio Azure Kubernetes, ad esempio usando kubectl apply. Sostituire <your-managed-identity-client-id> con l'ID client e <your-managed-identity-tenant-id> con l'ID tenant dell'identità gestita assegnata dall'utente appena creata. Sostituire <your-service-account-name> con il nome preferito.

   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. Creare una credenziale di identità federata per l'identità gestita assegnata dall'utente usando l'interfaccia della riga di comando di Azure. Sostituire <user-assigned-identity-name> con il nome e <resource-group> con il gruppo di risorse dell'identità gestita assegnata dall'utente appena creata. Sostituire <aks-oidc-issuer> con l'URL dell'autorità di certificazione OIDC del cluster del servizio Azure Kubernetes. Sostituire <your-service-account-name> con il nome dell'account del servizio appena creato. Sostituire <federated-identity-credential-name> con il nome preferito per le credenziali di identità federate.

   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
   

   Si noti che l'oggetto delle credenziali dell'identità federata deve seguire questo formato: system:serviceaccount:<service-account-namespace>:<service-account-name>.

7. Impostare la spec.auth.workloadIdentity.serviceAccountName proprietà sul nome dell'account del servizio nella risorsa di esempio AzureAppConfigurationProvider seguente. Assicurarsi che la AzureAppConfigurationProvider risorsa e l'account del servizio si trovino nello stesso spazio dei nomi.

   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>
   

Usare stringa di connessione

1. Creare un segreto Kubernetes nello stesso spazio dei nomi della AzureAppConfigurationProvider risorsa e aggiungere app Azure Configurazione stringa di connessione con azure_app_configuration_connection_string chiave nel segreto.

2. Impostare la spec.connectionStringReference proprietà sul nome del segreto nella risorsa di esempio AzureAppConfigurationProvider seguente e distribuirla nel cluster 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
   

Selezione chiave-valore

Usare la selectors proprietà per filtrare i valori chiave da scaricare da app Azure Configuration.

L'esempio seguente scarica tutti i valori chiave senza etichetta.

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

Nell'esempio seguente vengono usati due selettori per recuperare due set di valori chiave, ognuno con etichette univoche. È importante notare che i valori dell'ultimo selettore hanno la precedenza ed eseguono l'override di eventuali chiavi sovrapposte dai selettori precedenti.

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

Uno snapshot può essere usato da solo o insieme ad altri selettori chiave-valore. Nell'esempio seguente vengono caricati i valori chiave della configurazione comune da uno snapshot e quindi ne viene eseguito l'override con i valori chiave per lo sviluppo.

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

Limitazione del prefisso della chiave

Nell'esempio seguente viene usata la trimKeyPrefixes proprietà per tagliare due prefissi dai nomi delle chiavi prima di aggiungerli all'oggetto ConfigMap generato.

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]

Aggiornamento della configurazione

Quando si apportano modifiche ai dati in app Azure Configurazione, è possibile che tali modifiche vengano aggiornate automaticamente nel cluster Kubernetes. È comune aggiornare più valori chiave, ma non si vuole che il cluster rilevi una modifica a metà dell'aggiornamento. Per mantenere la coerenza della configurazione, è possibile usare un valore chiave per segnalare il completamento dell'aggiornamento. Questo valore chiave è noto come chiave sentinel. Il provider Kubernetes può monitorare questo valore chiave e ConfigMap e Secret verranno rigenerati solo con i dati aggiornati dopo che viene rilevata una modifica nella chiave sentinel.

Nell'esempio seguente viene eseguito il polling di un valore chiave denominato app1_sentinel ogni minuto e la configurazione viene aggiornata ogni volta che vengono rilevate modifiche nella chiave 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

Riferimenti a Key Vault

Autenticazione

Nell'esempio seguente, un insieme di credenziali delle chiavi viene autenticato con un'entità servizio, mentre tutti gli altri insiemi di credenziali delle chiavi vengono autenticati con un'identità gestita assegnata dall'utente.

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>

Tipi di segreto

Sono attualmente supportati due tipi predefiniti kubernetes di segreti, opaco e TLS. I segreti risolti dai riferimenti a Key Vault vengono salvati come tipo segreto opaco per impostazione predefinita. Se si ha un riferimento a Key Vault a un certificato e si vuole salvarlo come tipo di segreto TLS, è possibile aggiungere un tag con il nome e il valore seguenti al riferimento di Key Vault in app Azure Configuration. In questo modo, verrà generato un segreto con il kubernetes.io/tls tipo e denominato dopo la chiave del riferimento all'insieme di credenziali delle chiavi.

Negli esempi seguenti viene illustrato come i dati vengono popolati nei segreti generati con tipi diversi.

Supponendo che un archivio Configurazione app abbia questi riferimenti a Key Vault:

L'esempio seguente genera segreti di tipi opachi 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>

I segreti generati vengono popolati con i dati seguenti:

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>

Aggiornamento dei segreti da Key Vault

L'aggiornamento dei segreti dagli insiemi di credenziali delle chiavi richiede in genere il ricaricamento dei riferimenti di Key Vault corrispondenti da app Azure Configurazione. Tuttavia, con la spec.secret.refresh proprietà è possibile aggiornare i segreti da Key Vault in modo indipendente. Ciò è particolarmente utile per garantire che il carico di lavoro rilevi automaticamente eventuali segreti aggiornati da Key Vault durante la rotazione dei segreti. Si noti che per caricare la versione più recente di un segreto, il riferimento a Key Vault non deve essere un segreto con controllo delle versioni.

L'esempio seguente aggiorna tutti i segreti non con controllo delle versioni da Key Vault ogni ora.

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

Flag di funzionalità

Nell'esempio seguente, i flag di funzionalità con chiavi che iniziano con app1 e le etichette equivalenti a common vengono scaricati e aggiornati ogni 10 minuti. Si noti che per popolare i flag di funzionalità nell'oggetto ConfigMap generato, la configMapData.type proprietà deve essere json o 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

Utilizzo di ConfigMap

Le applicazioni in esecuzione in Kubernetes usano in genere ConfigMap come variabili di ambiente o come file di configurazione. Se la configMapData.type proprietà è assente o è impostata su default, ConfigMap viene popolato con l'elenco di dati inseriti nell'elemento recuperato da app Azure Configuration, che può essere facilmente utilizzato come variabili di ambiente. Se la configMapData.type proprietà è impostata su json, yaml o proprietà, i dati recuperati da app Azure Configuration vengono raggruppati in un elemento con il nome della configMapData.key chiave specificato dalla proprietà nell'oggetto ConfigMap generato, che può essere utilizzato come file montato.

Negli esempi seguenti viene illustrato come i dati vengono popolati nell'oggetto ConfigMap generato con impostazioni diverse della configMapData.type proprietà .

Supponendo che un archivio Configurazione app abbia questi valori chiave:

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