Custom certificate authority (CA) in Azure Kubernetes Service (AKS)

2025-05-07

Custom Certificate Authority (CA) allows you to add up to 10 base64-encoded certificates to your node's trust store. This feature is often needed when CAs are required to be present on the node, for example when connecting to a private registry.

This article shows you how to create custom CAs and apply them to your AKS clusters.

Prerequisites

An Azure subscription. If you don't have an Azure subscription, create a free account.
You need the Azure CLI version 2.72.0 or later installed and configured. To find your CLI version, run az --version. If you need to install or upgrade, see Install Azure CLI.
A base64 encoded certificate string or a text file with certificate.

Limitations

Windows node pools aren't supported.
Installing different CAs in the same cluster isn't supported.

Install CAs on your node's trust store

Create a file containing CAs.

Create a text file containing up to 10 blank line separated certificates. When this file is passed to your cluster, these certificates are installed in your node's trust stores.

Example text file:
```
    -----BEGIN CERTIFICATE-----
    cert1
    -----END CERTIFICATE-----

    -----BEGIN CERTIFICATE-----
    cert2
    -----END CERTIFICATE-----
```
Before proceeding to the next step, make sure that there are no blank spaces in your text file. These blank spaces will result in an error in the next step if not removed.
Use the az aks create or az aks update to pass certificates to your cluster. Once the operation completes, the certificates are installed in your node's trust stores.
- Install CAs during cluster creation using the az aks create command and specifying your text file for the --custom-ca-trust-certificates parameter.
```
az aks create \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --node-count 2 \
    --custom-ca-trust-certificates FileWithCAs \
    --generate-ssh-keys
```
- Install CAs during cluster update using the az aks update command and specifying your text file for the --custom-ca-trust-certificates parameter.
```
az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --custom-ca-trust-certificates <path-to-ca-file>
```
Note

This operation triggers a model update to ensure all existing nodes have the same CAs installed for correct provisioning. AKS creates new nodes, drains existing nodes, deletes existing nodes, and replaces them with nodes that have the new set of CAs installed.
Check that CAs are installed.

Use the az aks show command to check that CAs are installed.

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

The securityProfile output should include your Custom CA Trust Certificates.

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

Troubleshooting

Formatting error

Adding certificates to a cluster can result in an error if the file with the certificates isn't formatted properly.

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

If you encounter this error, you should check that your input file has no extra new lines, white spaces, or data other than correctly formatted certificates as shown in the example file.

Feature is enabled and secret with CAs is added, but operations are failing with X.509 Certificate Signed by Unknown Authority error

Incorrectly formatted certs passed in the secret

AKS requires certs passed in the user-created secret to be properly formatted and base64 encoded. Make sure the CAs you passed are properly base64 encoded and that files with CAs don't have CRLF line breaks.

Certificates passed to --custom-ca-trust-certificates shouldn't be base64 encoded.

Containerd doesn't pick up new certificates

From the node's shell, run systemctl restart containerd. Once containerd restarts, the container runtime picks up the new certificates.

Next steps

For more information on AKS security best practices, see Best practices for cluster security and upgrades in Azure Kubernetes Service (AKS).