Use proxy server settings in AKS hybrid

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

This article describes how to configure proxy settings for Azure Kubernetes Service (AKS) in AKS hybrid. If your network requires the use of a proxy server to connect to the internet, this article walks you through the steps to set up proxy support in AKS using the AksHci PowerShell module. The steps are different depending on whether the proxy server requires authentication.


If you want to use Kubernetes and Azure Services via Azure Arc, make sure you also allow the URLs shown in Connect an existing Kubernetes cluster to Azure Arc.

Once you've configured your deployment using the options listed below, you can install an AKS host on Azure Stack HCI and create AKS clusters using PowerShell.

Before you begin

Make sure you have satisfied all the prerequisites on the system requirements page.

Proxy server configuration information

The proxy server configuration for your AKS deployment includes the following settings:

  • HTTP URL and port, such as
  • HTTPS URL and port, such as
  • (Optional) Valid credentials for authentication to the proxy server.
  • (Optional) Valid certificate chain if your proxy server is configured to intercept SSL traffic. This certificate chain will be imported into all AKS control plane and worker nodes as well as the management cluster to establish a trusted connection to the proxy server.

Exclusion list for excluding private subnets from being sent to the proxy

The following table contains the list of addresses that must be excluded by using the -noProxy parameter in New-AksHciProxySetting.

IP Address Reason for exclusion
localhost, Localhost traffic
.svc Internal Kubernetes service traffic (.svc) where .svc represents a wildcard name. This is similar to saying *.svc, but none is used in this schema. private network address space Private network address space - Kubernetes Service CIDR Private network address space - Kubernetes Pod CIDR You may want to exempt your enterprise namespace ( from being directed through the proxy. To exclude all addresses in a domain, you must add the domain to the noProxy list. Use a leading period rather than a wildcard (*) character. In the sample, the addresses excludes addresses,, and so on.

The default value for noProxy is localhost,,.svc,,, While these default values will work for many networks, you may need to add more subnet ranges and/or names to the exemption list. For example, you may want to exempt your enterprise namespace ( from being directed through the proxy. You can achieve that by specifying the values in the noProxy list.

Set proxy for Azure Stack HCI and Windows Server clusters with machine-wide proxy settings

If you already have machine-wide proxy settings on your Azure Stack HCI/Windows Server cluster, the settings might override any AKS-specific proxy settings and lead to a failure during installation.

To detect whether you have machine-wide proxy settings, run the following script on each of your physical cluster nodes:

$http_proxy = [System.Environment]::GetEnvironmentVariable("HTTP_PROXY", "Machine")
$https_proxy = [System.Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
$no_proxy = [System.Environment]::GetEnvironmentVariable("NO_PROXY", "Machine")

if ($http_proxy -or $https_proxy) {
    if (-not $no_proxy) {
        Write-Host "Problem Detected! A machine-wide proxy server is configured, but no proxy exclusions are configured"

Configure machine-wide proxy exclusions on each of the physical cluster hosts where the problem was detected.


We recommend that you use the same proxy settings on all nodes in the failover cluster. Having different proxy settings on different physical nodes in the failover cluster might lead to unexpected results or installation issues.

Run the following PowerShell script and replace the $no_proxy parameter string with a suitable NO_PROXY exclusion string for your environment. For information about how to correctly configure a noProxy list for your environment, see Exclusion list for excluding private subnets from being sent to the proxy.

$no_proxy = "localhost,,.svc,,,,"
[Environment]::SetEnvironmentVariable("NO_PROXY", $no_proxy, "Machine")
$env:NO_PROXY = [System.Environment]::GetEnvironmentVariable("NO_PROXY", "Machine")

Install the AksHci PowerShell modules

Configure the System proxy settings on each of the physical nodes in the cluster and ensure that all nodes have access to the URLs and ports outlined in System requirements.

If you are using remote PowerShell, you must use CredSSP.

Close all open PowerShell windows. before running the following command -

Install-Module -Name AksHci -Repository PSGallery

If your environment uses a proxy server to access the internet, you may need to add proxy parameters to the Install-Module command before installing AKS on Azure Stack HCI. See the Install-Module documentation for details and follow the Azure Stack HCI documentation to configure the proxy settings on the physical cluster nodes.

When you download AksHci PowerShell module, we also download Az PowerShell modules that are required for registering for AKS host to Azure for billing.

Configure an AKS host for a proxy server with basic authentication

If your proxy server requires authentication, open PowerShell as an administrator and run the following command to get credentials and set the configuration details:

$proxyCred = Get-Credential
$proxySetting=New-AksHciProxySetting -name "corpProxy" -http http://contosoproxy:8080 -https https://contosoproxy:8443 -noProxy localhost,,.svc,,,, -credential $proxyCredential

Configure an AKS host for a proxy server without authentication

If your proxy server doesn't require authentication, run the following command:

$proxySetting=New-AksHciProxySetting -name "corpProxy" -http http://contosoproxy:8080 -https https://contosoproxy:8443 -noProxy localhost,,.svc,,,,

Configure an AKS host for a proxy server with a trusted certificate

If your proxy server requires proxy clients to trust a certificate, specify the certificate file when you run Set-AksHciConfig. The format of the certificate file is Base-64 encoded X .509. This will enable you to create and trust the certificate throughout the stack.


If your proxy requires a certificate to be trusted by the physical Azure Stack HCI nodes, make sure that you have imported the certificate chain to the appropriate certificate store on each Azure Stack HCI node before you continue. Follow the procedures for your deployment to enroll the Azure Stack HCI nodes with the required certificates for proxy authentication.

$proxySetting=New-AksHciProxySetting -name "corpProxy" -http http://contosoproxy:8080 -https https://contosoproxy:8443 -noProxy localhost,,.svc,,,, -certFile c:\temp\proxycert.pfx


Proxy certificates must be provided as a personal information exchange (PFX) file format or string, and contain the root authority chain to use the certificate for authentication or for SSL tunnel setup.

Next steps

You can now proceed with installing AKS on your Azure Stack HCI or Windows Server cluster, by running Set-AksHciConfig followed by Install-AksHci.