Book a 90-minute product workshop led by HashiCorp engineers and product experts during HashiConf Digital Reserve your spot

HashiCorp Consul Service on Azure

Connect an Azure Kubernetes Service (AKS) cluster to HashiCorp Consul Service on Azure

HashiCorp Consul Service (HCS) on Azure enables any organization that runs at least part of its infrastructure in Azure to adopt Consul with minimal operational overhead. These advantages apply to single region VM-based Azure environments in need of basic service discovery as well as more complex multi-environment scenarios that require service mesh-related features like dynamic traffic routing and service segmentation.

In this guide you will deploy a Consul service mesh on an existing Azure Kubernetes Service (AKS) cluster and connect it to an instance of a HCS on Azure.


To successfully complete this guide you will need access to HCS on Azure and the Consul servers. You will need Consul client configuration information, the CA certificate, and the gossip encryption key. Complete the Discover HashiCorp Consul Service Configuration guide to retrieve this information.

You will also need an AKS cluster. If you are using the "Advanced" network configuration for the AKS cluster, ensure that the cluster VNet CIDR doesn't overlap with the CIDR range selected for the HCS on Azure, otherwise, you will not be able to peer the AKS and HCS networks.

Additionally, you will need the following:

  • Permissions to create and edit VNets. Check Microsoft documentation to learn more on these permissions.
  • Azure CLI tool installed on a machine.
  • helm to deploy your Consul service mesh in the AKS cluster.
  • kubectl to interact with your Kubernetes cluster and deploy services.

»Setup environment

In this guide you will be using a local machine to setup your AKS cluster and to deploy your Consul Helm chart on it. You should also have the following files containing the configuration extracted from your HCS on Azure servers.

  • consul-config.json containing the Consul client configuration
  • ca.pem containing the CA certificates to be used for TLS encryption

You will use the data contained in the files to generate configuration for your Consul service mesh Helm chart configuration.

»Configure the AKS cluster

The following recommendations provide guidance on how to simplify the configuration process for test environments. You should always follow your internal policies when planning for production.

»AKS cluster considerations

Note: Ensure that the CIDR for your AKS cluster and the VNet associated with it don't overlap with the CIDR range selected for the HCS on Azure. If you use Azure and HCS default address ranges, you should have no issues with the following steps.

If you do not have any configuration requirements, you can create your AKS cluster using the Basic (kubenet) option in the Networking tab.

»Peer VNets

To enable communication between your AKS cluster and HCS on Azure, you must establish network connectivity between the VNet created with the cluster and the VNet that was created as part of HCS on Azure. To do this, you will need to establish bi-directional peering.

Note: When peering VNets, ensure you are leveraging the VNet that was automatically created by HCS on Azure (not one you have manually created). You can see this by going into your Consul managed resource, selecting the managed resource name, and observing the name of the VNet.

Peering HCS VNet with AKS VNet

»Connect to the AKS cluster

To interact with your AKS cluster, you need to configure kubectl. Use the az aks command to retrieve the Kubernetes cluster configuration.

Retrieve the kubectl credentials from the cluster. Using the following command will automatically merge the new configuration into your pre-existing kubectl configuration. You will need the name of your AKS cluster and the resource group that it is located in.

$ az aks get-credentials --name <aks_cluster_name> --resource-group <resource_group>
Merged "learn-hcs-aks-client" as current context in /home/user/.kube/config

Set your kubectl context to your AKS cluster:

$ kubectl config use-context <aks_cluster_name>
Switched to context "learn-hcs-aks-client".

»Create Kubernetes secrets

Once kubectl is configured, you can continue configuring the AKS cluster by adding three Kubernetes secrets to store the CA certificate for mTLS, the encryption key that is used for Consul gossip encryption, and the Consul bootstrap token.

Extract this information from the configuration files produced in the Discover HashiCorp Consul Service on Azure Configuration guide when retrieving the configuration parameters from the Consul service.

First, define the deployment name that you will use for the rest of the guide.

$ export HELM_RELEASE=hcs-test-aks

Create the Kubernetes secret to store the Consul CA certificate.

$ kubectl create secret generic "${HELM_RELEASE}-consul-ca-cert" --from-file='tls.crt=./ca.pem'
secret/hcs-test-aks-consul-ca-cert created

Create the Kubernetes secret to store the Consul gossip encryption key.

$ export gossip_key=$(jq -r .encrypt consul.json)
$ kubectl create secret generic "${HELM_RELEASE}-gossip-key" --from-literal="key=${gossip_key}"
secret/hcs-test-aks-gossip-key created

Create the Kubernetes secret to store the Consul bootstrap ACL token.

$ kubectl create secret generic "${HELM_RELEASE}"-bootstrap-token --from-literal='token=<your bootstrap secret>'
secret/hcs-test-aks-gossip-key created

»Configure Consul clients

After creating the Kubernetes secrets for Consul, you can proceed in downloading and configuring the official Helm chart.

»Get the official Helm chart

Add the official HashiCorp Helm Repository.

$ helm repo add hashicorp
"hashicorp" has been added to your repositories

»Generate the Helm configuration

To connect clients running on Kubernetes to HCS on Azure, you need to configure the Helm chart with custom configuration.

You already defined the CA certificate, gossip encryption key, and the bootstrap ACL token as Kubernetes secrets. The last information you need for your Helm values file is the endpoint the clients will use to join the HCS on Azure servers and the URL of your AKS cluster. Extract the endpoint from the configuration file consul.json and store it as a variable.

$ export retry_join=$(jq -r --compact-output .retry_join consul.json)

You can check that the variable is correctly populated using echo.

$ echo $retry_join

Set the URL of your AKS cluster as a variable.

$ export kube_api_server=$(kubectl config view -o jsonpath="{.clusters[?( == \"$(kubectl config current-context)\")].cluster.server}")

You can check that the variable is correctly populated using echo.

$ echo $kube_api_server

Finally, generate the config.yaml file, containing the configuration for your Helm chart.

$ cat > config.yaml << EOF
  enabled: false
  datacenter: $(jq -r .datacenter consul.json)
    manageSystemACLs: true
      secretName: ${HELM_RELEASE}-bootstrap-token
      secretKey: token
    secretName: ${HELM_RELEASE}-gossip-key
    secretKey: key
    enabled: true
    enableAutoEncrypt: true
      secretName: ${HELM_RELEASE}-consul-ca-cert
      secretKey: tls.crt
  enabled: true
  hosts: ${retry_join}
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: ${kube_api_server}
  enabled: true
  join: ${retry_join}
  // If you are using basic networking (Kubenet) in
  // your AKS cluster, uncomment the line below.
  //exposeGossipPorts: true
  enabled: true

»Install the Consul Helm Chart

Once the configuration file is created you can proceed to the actual deploy.

$ helm install "${HELM_RELEASE}" -f config.yaml hashicorp/consul
NAME: hcs-test-aks
## ...
NAMESPACE: default
STATUS: deployed
## ...

Your release is named hcs-test-aks.

To learn more about the release if you are using Helm 2, run:

  $ helm status hcs-test-aks
  $ helm get hcs-test-aks

To learn more about the release if you are using Helm 3, run:

  $ helm status hcs-test-aks
  $ helm get all hcs-test-aks

You can check the state of the pods deployed by the chart using the kubectl command.

$ kubectl get pods
NAME                                                            READY   STATUS  RESTARTS   AGE
hcs-test-aks-consul-connect-injector-webhook-deployment-7bbsp79   1/1   Running   0         1h
hcs-test-aks-consul-crxgz                                       1/1     Running   0         1h
hcs-test-aks-consul-lwcqk                                       1/1     Running   0         1h
hcs-test-aks-consul-phlzp                                       1/1     Running   0         1h
hcs-test-aks-consul-sync-catalog-75b79b8ff8-gfqdf               1/1     Running   0         1h

Unless otherwise specified, your Consul clients will be deployed into the default Kubernetes namespace.

»Next Steps

In this guide you connected Consul clients in your AKS cluster to HCS on Azure servers. To continue learning, review the Consul service mesh sidecar documenation to deploy and secure services.

If you are ready to deploy Consul on Kubernetes in production review the Consul and Kubernetes Reference Architecture recommendations guide and the official Helm chart configuration.

If you have any feedback for the HashiCorp Engineering or SRE team, including leaving comments and filing bugs, please contact