Use autoridades certificadoras personalizadas (CAs) no Azure Kubernetes Service (AKS)

O suporte para Autoridade de Certificação (AC) personalizada permite adicionar até 10 certificados codificados em base64 ao repositório de confiança do seu nó. Para novos clusters, o conteúdo do certificado da CA não pode exceder 35 KB. Muitas vezes é necessário esta funcionalidade quando o nó requer autoridades certificadoras (CAs), como ao ligar-se a um registo privado.

Este artigo mostra como criar CAs personalizadas e aplicá-las aos seus clusters AKS.

Note

A funcionalidade Custom CA adiciona os seus certificados personalizados ao repositório de confiança do nó AKS. Os certificados adicionados com esta funcionalidade não estão disponíveis para contentores que correm em pods. Se precisares dos certificados dentro de contentores, tens de os adicionar separadamente, adicionando-os à imagem usada pelos teus pods ou em tempo de execução através de scripts e um segredo.

Prerequisites

  • Uma subscrição do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita.
  • CLI do Azure versão 2.72.0 ou posterior instalada e configurada. Para encontrar a sua versão da CLI, execute o az --version comando. Se precisar de instalar ou atualizar, consulte Install CLI do Azure.
  • Uma cadeia de caracteres de certificado codificada em base64 ou um arquivo de texto com certificado.

Limitations

  • Os pools de nós do Windows não são suportados.
  • Não há suporte para a instalação de CAs diferentes no mesmo cluster.
  • Para novos clusters, o conteúdo do certificado da CA não pode exceder 35 KB.

Criar um ficheiro de certificado

  • Crie um ficheiro de texto contendo até 10 certificados em branco separados por linhas. Para novos clusters, o conteúdo do certificado da CA no ficheiro não pode exceder 35 KB. Quando passa este ficheiro para o seu cluster, os certificados são instalados nos armazenamentos de confiança do nó AKS.

    Exemplo de arquivo de texto:

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

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

Antes de avançar para o próximo passo, certifique-se de que não há espaços em branco no seu ficheiro de texto para evitar erros.

Passa CAs personalizadas para o teu cluster AKS

  • Passe certificados para o seu cluster usando o comando az aks create ou az aks update, com --custom-ca-trust-certificates definido para o nome do seu ficheiro 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

    Esta operação inicia uma atualização do modelo para garantir que todos os nós existentes tenham as mesmas CAs instaladas, assegurando o provisionamento correto. O AKS cria novos nós, drena nós existentes, exclui nós existentes e os substitui por nós que têm o novo conjunto de CAs instalado.

Verifique que as CAs estão instaladas

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

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

    No resultado, a securityProfile secção deve incluir os seus certificados personalizados de CA. Por exemplo:

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

Resolver erros de formatação do Certificado de Autoridade personalizado

Adicionar certificados a um cluster pode resultar em um erro se o arquivo com os certificados não estiver formatado corretamente. 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, verifique se o arquivo de entrada não tem novas linhas, espaços em branco ou dados extras além de certificados formatados corretamente, conforme mostrado no arquivo de exemplo.

Resolver erros de certificado personalizado CA X.509 assinado por Autoridade Desconhecida

O AKS exige que os certificados aprovados estejam devidamente formatados e codificados em base64. Verifique se as ACs que submeteu estão codificadas corretamente em base64 e se os ficheiros com ACs não têm quebras de linha CRLF.

Reiniciar o containerd para recolher novos certificados

Se o containerd não reconhecer novos certificados, execute o comando systemctl restart containerd a partir da shell do nó. Quando o containerd reinicia, o tempo de execução do contentor deverá captar os novos certificados.

enableCustomCATrust (Pré-visualização) Migração para a reforma

Importante

A partir de 14 de setembro de 2026, a propriedade enableCustomCATrust em pré-visualização será descontinuada. Após essa data, o campo enableCustomCATrust=true ao nível do pool de nós deixará de permitir ativar a funcionalidade de Autoridade de Certificação Personalizada (CA) no AKS. A última API de pré-visualização que suporta esta propriedade é 2025-08-02-preview. Os grupos de nós existentes que ainda dependem de enableCustomCATrust=true podem sofrer falhas durante operações de dimensionamento ou quando os certificados são atualizados. Para evitar interrupções do serviço, atualize os clusters e pools de nós afetados e remova a propriedade de pré-visualização antes de 14 de setembro de 2026. Para ver os passos da migração, consulte enableCustomCATrust migração devido à descontinuação (pré-visualização). Para mais informações sobre esta reforma, consulte a edição Retirement GitHub. Para se manter informado sobre anúncios e atualizações, siga as notas de atualização do AKS.

Remova a propriedade Custom CA Trust dos seus pools de nós

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

Este comando obtém o recurso completo do pool de nós, atualiza enableCustomCATrust e envia o recurso atualizado novamente. 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 concluída com êxito:

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 estes passos para cada pool de nós onde enableCustomCATrust estiver ativado. A saída esperada mostra enableCustomCATrust definido para false e provisioningState definido para Succeeded.

Se quiser ativar o Custom CA Trust nos seus clusters após esta reforma, use --custom-ca-trust-certificates e forneça um caminho para um ficheiro de certificado.

Conteúdo relacionado

Para obter mais informações sobre as práticas recomendadas de segurança do AKS, consulte Práticas recomendadas para segurança de cluster e atualizações no Serviço Kubernetes do Azure (AKS).

  • Last updated on