Update proxy server settings, certificates in AKS hybrid

Applies to: AKS on Azure Stack HCI, AKS on Windows Server

This article describes how to update proxy settings and certificates for your deployment in AKS hybrid. Each AKS deployment has a single global proxy configuration. You can add exclusions using the noProxy parameter to exclude private subnets (for example, contoso.com) from using the proxy server, and you can update proxy certificates for the deployment. You can't change HTTP or HTTPS settings.

For information about the initial proxy server setup, see Use proxy server settings in AKS hybrid.

Proxy settings you can update

Before you begin, review current limitations to proxy settings updates in AKS hybrid:

  • AKS hybrid supports one global proxy configuration per AKS hybrid deployment. When you update the proxy settings, they're updated for the entire AKS hybrid deployment.

  • You can only update noProxy settings, which are used to exclude a private subnet from using the proxy server, and proxy certificates. HTTP and HTTPs proxy settings can't be updated.

  • You can't configure different proxy settings for a specific node pool or workload cluster. By the same token, you can't update proxy settings for a specific node pool or workload cluster.

  • Updates to proxy settings are only applied after you update your entire AKS deployment. You must update the AKS host management cluster and all AKS hybrid workload clusters. To check whether an update is available, use the AKS PowerShell module cmdlet Get-AksHciClusterUpdates.


Before you update proxy settings for an AKS deployment, you must meet the following prerequisites:

  • Your AKS deployment is running the October 2022 update or later.

  • The most recent version of the AksHci PowerShell module is installed. For more information, see Install the AksHci PowerShell module.

  • At least one update is available for your AKS deployment. Updates to proxy settings and certificates are applied automatically after updates are applied to an AKS deployment. To check for available updates, run the Get-AksHciClusterUpdates command in the AksHci PowerShell module.

Step 1: Create a new noProxy exclusion list

You may occasionally need to update noProxy settings to exclude a private subnet from using the proxy server for your AKS deployment. To prepare to update the noProxy settings, store a new exclusion list in a PowerShell variable.

  1. Before you update your noProxy settings, review the required noProxy settings in the proxy exclusion table. For more information, see Exclusion list for excluding private subnets from being sent to the proxy.

    Certain exclusions are required for your AKS hybrid deployment to function. Not excluding these URLs may cause failures in your AKS hybrid deployment.

  2. Store your updated noProxy URL list in a PowerShell variable:

    $noProxy = "localhost,,.svc,,,,.contoso.com"

Step 2: Create a proxy certificate bundle

To update certificates for your proxy server, create a new certificate bundle and then store the path to the file in a PowerShell variable. You'll bundle the certificates in a single .crt file in PEM format. This format is applicable for updating certificates on Linux container hosts.

To bundle your updated proxy server certificates:

  1. Create a single .crt file with the bundled certificates for Linux hosts. Use the concatenate (cat) command with the following format:

    cat [leaf].crt  [intermediate].crt  [Root].crt > [bundle].crt

    You must concatenate the certificates in the order of: leaf certificate > intermediate certificate > root certificate. For detailed certificate requirements and an example, see Update certificate bundle for your AKS hybrid deployment.


    The contents of the certificate file aren't validated. Check carefully to ensure the file contains the right certificates and is in the correct format.

  2. Store the path to your updated certificate bundle in a PowerShell variable:

    $certFile ="/../[certificate-bundle].crt" # path to the bundled .crt file

Step 3: Update proxy settings

The next step is to use the Set-AksHciProxySetting command to update your noProxy settings and certificates.

  1. Before you update the proxy settings and certificates, confirm that your PowerShell variables have the right changes:

    echo $noProxy
    echo $certFile
  2. To update both your proxy settings and proxy certificates, run the following command:

    Set-AksHciProxySetting -noProxy $noProxy -certFile $certFile

Step 4: Apply updated proxy settings to your AKS deployment

The updates to your global proxy settings and certificate are applied automatically after you update the AKS deployment.

To apply the proxy updates:

  1. Check whether an update is available for your AKS host management cluster by running the following command:

  2. If an update is available, update your AKS host management cluster by running the following command. This command applies the proxy changes on your AKS host management cluster.

  3. Update all of the workload clusters in your AKS hybrid deployment. Proxy changes won't be applied unless you update your workload clusters.

    1. To check whether workload cluster updates are available, run the following command on each of your AKS workload clusters:

      Get-AksHciClusterUpdates -name mycluster
    2. If an update is available (either a Kubernetes version or an updated OS image), update each of your workload clusters by running the Update-AksHciCluster command.

      • To update the Kubernetes version and OS version on a workload cluster, run the following command:

        Update-AksHciCluster -name mycluster
      • To update the OS without updating the Kubernetes version, include the -operatingSystem parameter:

        Update-AksHciCluster -name mycluster -operatingSystem

        If an OS image-only update isn't available for your workload cluster, you won't be able to apply the proxy changes unless you update the Kubernetes version.

Next steps