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

Custom certificate authorities (CAs) allow you to establish trust between your Azure Kubernetes Service (AKS) cluster and your workloads, such as private registries, proxies, and firewalls. A Kubernetes secret is used to store the certificate authority's information, then it's passed to all nodes in the cluster.

This feature is applied per nodepool, so new and existing nodepools must be configured to enable this feature.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

Prerequisites

Limitations

This feature isn't currently supported for Windows nodepools.

Install the aks-preview extension

You also need the aks-preview Azure CLI extensions version 0.5.72 or later. Install the aks-preview extension by using the az extension add command, or install any available updates by using the az extension update command.

# Install the aks-preview extension
az extension add --name aks-preview

# Update the extension to make sure you have the latest version installed
az extension update --name aks-preview

Register the CustomCATrustPreview preview feature

Register the CustomCATrustPreview feature flag by using the az feature register command:

az feature register --namespace "Microsoft.ContainerService" --name "CustomCATrustPreview"

It takes a few minutes for the status to show Registered. Verify the registration status by using the az feature list command:

az feature list --query "[?contains(name, 'Microsoft.ContainerService/CustomCATrustPreview')].{Name:name,State:properties.state}" -o table

Refresh the registration of the Microsoft.ContainerService resource provider by using the az provider register command:

az provider register --namespace Microsoft.ContainerService

Configure a new AKS cluster to use a custom CA

To configure a new AKS cluster to use a custom CA, run the az aks create command with the --enable-custom-ca-trust parameter.

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 2 \
    --enable-custom-ca-trust

Configure a new nodepool to use a custom CA

To configure a new nodepool to use a custom CA, run the az aks nodepool add command with the --enable-custom-ca-trust parameter.

az aks nodepool add \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name myNodepool \
    --enable-custom-ca-trust \
    --os-type Linux

Configure an existing nodepool to use a custom CA

To configure an existing nodepool to use a custom CA, run the az aks nodepool update command with the --enable-custom-trust-ca parameter.

az aks nodepool update \
    --resource-group myResourceGroup \
    --cluster-name myAKSCluster \
    --name myNodepool \
    --enable-custom-ca-trust

Create a Kubernetes secret with your CA information

Create a Kubernetes secret YAML manifest with your base64 encoded certificate string in the data field. Data from this secret is used to update CAs on all nodes.

You must ensure that:

  • The secret is named custom-ca-trust-secret.
  • The secret is created in the kube-system namespace.
apiVersion: v1
kind: Secret
metadata: 
    name: custom-ca-trust-secret
    namespace: kube-system
type: Opaque
data:
    ca1.crt: |
      {base64EncodedCertStringHere}
    ca2.crt: |
      {anotherBase64EncodedCertStringHere}

To update or remove a CA, edit and apply the YAML manifest. The cluster will poll for changes and update the nodes accordingly. This process may take a couple of minutes before changes are applied.

Next steps

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