Usar autoridades de certificação personalizadas (ACs) no AKS (Serviço de Kubernetes do Azure)

A AC (Autoridade de Certificação) Personalizada permite que você adicione até 10 certificados codificados em base64 ao repositório de confiança do nó. Esse recurso geralmente é necessário quando as autoridades de certificação (ACs) precisam estar presentes no nó, como ao se conectar a um registro privado.

Este artigo mostra como criar ACs personalizadas e aplicá-las aos clusters do AKS.

Prerequisites

• Uma assinatura do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita.
• CLI do Azure versão 2.72.0 ou posterior instalada e configurada. Para localizar a versão da CLI, execute o az --version comando. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.
• Uma cadeia de caracteres de certificado codificado em base64 ou um arquivo de texto com certificado.

Limitations

• Não há suporte a pools de nós Windows.
• Não há suporte para a instalação de CAs diferentes no mesmo cluster.

Criar um arquivo de certificado

• Crie um arquivo de texto contendo até 10 certificados separados de linha em branco. Quando você passa esse arquivo para o cluster, os certificados são instalados nos repositórios de confiança do nó do AKS.

  Exemplo de arquivo de texto:

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

Antes de prosseguir para a próxima etapa, verifique se não há espaços em branco no arquivo de texto para evitar erros.

Passar CAs personalizadas para o cluster do AKS

• Transfira certificados para seu cluster usando os comandos az aks create ou az aks update, com --custom-ca-trust-certificates definido como o nome do arquivo de certificado.

  # 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

  Essa operação aciona uma atualização do modelo para assegurar que todos os nós existentes estejam com os mesmos CAs (Autoridades Certificadoras) instalados, garantindo o provisionamento correto. O AKS cria novos nós, drena os nós existentes, exclui os nós existentes e os substitui por nós que têm o novo conjunto de ACs instalado.

Verificar se as ACs estão instaladas

• Confira se as CAs estão instaladas usando o comando az aks show.

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

  Na saída, a seção securityProfile deve incluir seus certificados AC personalizados. Por exemplo:

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

Resolver erros de formatação de autoridade certificadora personalizada

Adicionar certificados a um cluster pode resultar em um erro se o arquivo com os certificados não estiver formatado corretamente. Você pode ver um erro semelhante ao seguinte exemplo:

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

Se você encontrar esse erro, deverá verificar se o arquivo de entrada não tem novas linhas adicionais, espaços em branco ou dados diferentes de certificados formatados corretamente, conforme mostrado no arquivo de exemplo.

Resolver erros personalizados de certificado CA X.509 assinado por autoridade desconhecida

O AKS requer que os certificados passados sejam formatados corretamente e codificados em base64. Verifique se as CAs que você passou estão codificadas corretamente em base64 e se os arquivos com CAs não têm quebras de linha da CRLF.

Reiniciar contêineres para escolher novos certificados

Se containerd não escolher novos certificados, execute o comando systemctl restart containerd no shell do nó. Depois que o containerd reinicia, o container runtime deve capturar os novos certificados.

enableCustomCATrust (versão prévia) migração de descontinuação

Remover a propriedade Custom CA Trust de seus pools de nós

As versões CLI do Azure atuais não incluem a opção--disable-custom-ca-trust. Para remover a propriedade descontinuada enableCustomCATrust, use uma atualização genérica de recurso em cada pool de nós afetado. A 2025-08-02-preview API é a última versão da API que expõe essa propriedade.

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

Esse comando recupera o recurso completo do pool de nós, atualiza enableCustomCATruste envia o recurso atualizado de volta. Preserva as outras propriedades do pool de nós.

Verifique se a propriedade está desativada e se a atualização do pool de nós foi bem-sucedida:

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

Repita essas etapas para cada pool de nós em que enableCustomCATrust estiver habilitado. A saída esperada mostra enableCustomCATrust definido como false e provisioningState definido como Succeeded.

Se você quiser que a Confiança de Autoridade de Certificação Personalizada seja habilitada em seus clusters após essa desativação, use --custom-ca-trust-certificates e forneça um caminho para um arquivo de certificado.

Conteúdo relacionado

Para saber mais sobre as melhores práticas de segurança do AKS, confira Melhores práticas para segurança de cluster e atualizações no AKS (Serviço de Kubernetes do Azure).