Usare autorità di certificazione personalizzate nel servizio Azure Kubernetes

L'autorità di certificazione personalizzata consente di aggiungere fino a 10 certificati con codifica base64 all'archivio attendibilità del nodo. Questa funzionalità è spesso necessaria quando le autorità di certificazione (CA) devono essere presenti nel nodo, ad esempio quando ci si connette a un registro privato.

Questo articolo mostra come creare CA personalizzate e applicarle ai cluster del servizio Azure Kubernetes.

Prerequisites

• Una sottoscrizione di Azure. Se non hai una sottoscrizione di Azure, crea un account gratuito.
• interfaccia della riga di comando di Azure versione 2.72.0 o successiva installata e configurata. Per trovare la versione della CLI, eseguire il comando az --version. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure.
• Una stringa di certificato base64 encoded o un file di testo con certificato.

Limitations

• I pool di nodi di Windows non sono supportati.
• L'installazione di ca diverse nello stesso cluster non è supportata.

Creare un file di certificato

• Creare un file di testo contenente fino a 10 certificati separati da righe vuote. Quando si passa questo file al cluster, i certificati vengono installati negli archivi attendibili del nodo AKS.

  File di testo di esempio:

      -----BEGIN CERTIFICATE-----
      cert1
      -----END CERTIFICATE-----
  
      -----BEGIN CERTIFICATE-----
      cert2
      -----END CERTIFICATE-----
  

Prima di procedere al passaggio successivo, assicurarsi che nel file di testo non siano presenti spazi vuoti per evitare errori.

Passare CA personalizzate nel cluster AKS

• Trasferisci i certificati al tuo cluster utilizzando il comando az aks create o il comando az aks update, impostando --custom-ca-trust-certificates sul nome del file del tuo certificato.

  # Create a new cluster
  az aks create \
      --resource-group <resource-group-name> \
      --name <cluster-name> \
      --node-count 2 \
      --custom-ca-trust-certificates <path-to-certificate-file> \
      --generate-ssh-keys
  
  # Update an existing cluster
  az aks update \
      --resource-group <resource-group-name> \
      --name <cluster-name> \
      --custom-ca-trust-certificates <path-to-certificate-file>
  

  Note

  Questa operazione attiva un aggiornamento del modello per garantire che tutti i nodi esistenti abbiano le stesse CA installate per garantire un provisioning corretto. AKS crea nuovi nodi, scarica i nodi esistenti, li elimina e li sostituisce con nodi in cui è installato il nuovo set di CAs.

Verificare che le CA siano installate

• Verificare che le CA siano installate usando il comando az aks show.

  az aks show --resource-group <resource-group-name> --name <cluster-name> | grep securityProfile -A 4
  

  Nell'output la securityProfile sezione deve includere i certificati della CA personalizzati. Per esempio:

    "securityProfile": {
      "azureKeyVaultKms": null,
      "customCaTrustCertificates": [
          "values"
  

Risolvere gli errori di formattazione delle CA personalizzate

L'aggiunta di certificati a un cluster può generare un errore se il file con i certificati non è formattato correttamente. È possibile che venga visualizzato un errore simile all'esempio seguente:

failed to decode one of SecurityProfile.CustomCATrustCertificates to PEM after base64 decoding

Se si verifica questo errore, verificare che il file di input non contenga nuove righe, spazi vuoti o dati diversi da quelli formattati correttamente, come illustrato nel file di esempio.

Risolvere gli errori del certificato X.509 personalizzato firmato da un'autorità sconosciuta

Il servizio Azure Kubernetes richiede che i certificati forniti siano formattati correttamente e codificati in base64. Assicurarsi che le CA passate siano codificate correttamente in base64 e che i file con CA non abbiano interruzioni di riga CR LF.

Riavviare il contenitore per raccogliere nuovi certificati

Se containerd non preleva nuovi certificati, eseguire il systemctl restart containerd comando dalla shell del nodo. Dopo il riavvio di containerd, il runtime del contenitore dovrebbe caricare i nuovi certificati.

enableCustomCATrust (anteprima) Migrazione del ritiro

Rimuovere la proprietà di attendibilità della CA personalizzata dai pool di nodi

Le versioni interfaccia della riga di comando di Azure correnti non includono l--disable-custom-ca-trust'opzione . Per rimuovere la proprietà obsoleta enableCustomCATrust, utilizzare un aggiornamento generico della risorsa per ogni pool di nodi interessato. L'API 2025-08-02-preview è l'ultima versione dell'API che espone questa proprietà.

POOL_ID=$(az aks nodepool show \
  --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --name <node-pool-name> \
  --query id \
  --output tsv)

az resource update \
  --ids "$POOL_ID" \
  --api-version 2025-08-02-preview \
  --set properties.enableCustomCATrust=false

Questo comando recupera la risorsa completa del pool di nodi, aggiorna enableCustomCATruste invia nuovamente la risorsa aggiornata. Mantiene le altre proprietà del pool di nodi.

Verificare che la proprietà sia disabilitata e che l'aggiornamento del pool di nodi sia riuscito:

az rest \
  --method get \
  --url "https://management.azure.com${POOL_ID}?api-version=2025-08-02-preview" \
  --query "properties.{enableCustomCATrust:enableCustomCATrust,provisioningState:provisioningState}" \
  --output json

Ripetere questi passaggi per ogni pool di nodi in cui enableCustomCATrust è abilitato. L'output previsto mostra enableCustomCATrust impostato su false e provisioningState impostato su Succeeded.

Se si vuole abilitare l'attendibilità CA personalizzata nei cluster dopo il ritiro, usare --custom-ca-trust-certificates e fornire un percorso a un file di certificato.

Contenuti correlati

Per altre informazioni sulle procedure consigliate per la sicurezza del servizio Azure Kubernetes, vedere Procedure consigliate per la sicurezza e gli aggiornamenti del cluster nel servizio Azure Kubernetes (AKS).