Uso de entidades de certificación (CA) personalizadas en Azure Kubernetes Service (AKS)

La entidad de certificación personalizada (CA) permite agregar hasta 10 certificados codificados en base64 al almacén de confianza del nodo. Esta característica suele ser necesaria cuando las entidades de certificación (CA) deben estar presentes en el nodo, como al conectarse a un registro privado.

En este artículo se muestra cómo crear entidades de certificación personalizadas y aplicarlas a los clústeres de AKS.

Note

La función de Autoridad Certificadora (CA) Personalizada añade tus certificados personalizados al almacén de confianza del nodo de AKS. Los certificados agregados mediante esta funcionalidad no están disponibles para los contenedores que se ejecutan en pods. Si necesita que los certificados estén dentro de los contenedores, debe agregarlos por separado, añadiéndolos a la imagen utilizada por sus pods o en tiempo de ejecución usando scripting y un secreto.

Prerequisites

  • Suscripción a Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita.
  • La CLI de Azure, versión 2.72.0 o posterior, instalada y configurada. Para buscar la versión de la CLI, ejecute el az --version comando . Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.
  • Cadena de certificado codificada en base64 o un archivo de texto con certificado.

Limitations

  • No se admiten los grupos de nodos de Windows.
  • No se admite la instalación de diferentes CA en el mismo clúster.

Creación de un archivo de certificado

  • Cree un archivo de texto que contenga hasta 10 certificados separados por líneas en blanco. Al pasar este archivo al clúster, los certificados se instalan en los almacenes de confianza del nodo de AKS.

    Archivo de texto de ejemplo:

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

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

Antes de continuar con el paso siguiente, asegúrese de que no haya espacios en blanco en el archivo de texto para evitar errores.

Proporcionar CAs personalizadas al clúster de AKS

  • Pase certificados a su clúster utilizando el comando az aks create o az aks update con --custom-ca-trust-certificates configurado al nombre de su archivo 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 operación desencadena una actualización del modelo para asegurarse de que todos los nodos existentes tienen instaladas las mismas CA para el aprovisionamiento correcto. AKS crea nuevos nodos, purga los nodos existentes, elimina los nodos existentes y los reemplaza por los nodos que tienen instalado el nuevo conjunto de CA.

Comprobación de que las CA están instaladas

  • Compruebe que las CA están instaladas mediante el az aks show comando .

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

    En la salida, la sección securityProfile debe incluir tus certificados de autoridad certificadora personalizados. Por ejemplo:

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

Resolución de errores de formato de la entidad de certificación personalizada

Agregar certificados a un clúster puede producir un error si el archivo con los certificados no tiene el formato correcto. Es posible que vea un error similar al ejemplo siguiente:

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

Si se produce este error, debe comprobar que el archivo de entrada no tiene líneas, espacios en blanco ni datos adicionales que no tengan el formato correcto de los certificados, como se muestra en el archivo de ejemplo.

Resolución de errores del certificado X.509 de Autoridad de Certificación (CA) personalizado firmado por una autoridad desconocida

AKS requiere que los certificados pasados tienen el formato correcto y se codifican en Base64. Asegúrese de que las entidades de certificación que ha pasado están codificadas correctamente en base64 y que los archivos con entidades de certificación no tienen saltos de línea CRLF.

Reinicie containerd para detectar nuevos certificados

Si el contenedor no recoge nuevos certificados, ejecute el systemctl restart containerd comando desde el shell del nodo. Una vez reiniciado el contenedor, el entorno de ejecución del contenedor debe recoger los nuevos certificados.

enableCustomCATrust (versión preliminar) Migración de retirada

Importante

A partir del 14 de septiembre de 2026, la propiedad enableCustomCATrust en versión preliminar se retirará. Después de esa fecha, el campo enableCustomCATrust=true de nivel de grupo de nodos ya no habilitará la característica de entidad de certificación (CA) personalizada en AKS. La última API en versión preliminar que admite esta propiedad es 2025-08-02-preview. Los grupos de nodos existentes que todavía dependen enableCustomCATrust=true pueden experimentar errores durante las operaciones de escalado o cuando se actualizan los certificados. Para evitar interrupciones del servicio, actualice los clústeres y grupos de nodos afectados y quite la propiedad de versión preliminar antes del 14 de septiembre de 2026. Para conocer los pasos de migración, consulte enableCustomCATrust Migración de retirada (versión preliminar). Para obtener más información sobre este retiro, consulte la incidencia de retiro en GitHub. Para mantenerse informado sobre los anuncios y las actualizaciones, siga las notas de la versión de AKS.

Eliminar la propiedad de confianza en una CA personalizada de sus grupos de nodos

Las versiones de CLI de Azure actuales no incluyen la --disable-custom-ca-trust opción . Para eliminar la propiedad enableCustomCATrust obsoleta, utilice una actualización genérica de recursos para cada grupo de nodos afectado. La 2025-08-02-preview API es la última versión de API que expone esta propiedad.

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 recupera el recurso completo del grupo de nodos, actualiza enableCustomCATrusty devuelve el recurso actualizado. Conserva las demás propiedades del grupo de nodos.

Compruebe que la propiedad está deshabilitada y que la actualización del grupo de nodos se realizó correctamente:

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 estos pasos para cada grupo de nodos en el que enableCustomCATrust esté habilitado. La salida esperada muestra enableCustomCATrust establecido en false y provisioningState establecido en Succeeded.

Si desea que la confianza en una CA personalizada esté habilitada para sus clústeres tras esta retirada, use --custom-ca-trust-certificates y proporcione una ruta a un archivo de certificado.

Contenido relacionado

Para obtener más información sobre los procedimientos recomendados de seguridad de AKS, puede consultar los Procedimientos recomendados para administrar la seguridad y las actualizaciones de los clústeres en Azure Kubernetes Service (AKS).

  • Last updated on