Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

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 tutorial 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 tutorial you will need access to HCS on Azure and the Consul servers.

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.

»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 confirm 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

»Install the HashiCorp extension

You can install the extension directly from your shell using the az command:

$ az extension add \
Are you sure you want to install this extension? (y/n): y
The installed extension 'hcs' is in preview.

»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 an ACL token

Use HCS CLI to create an ACL token and save it as a Kubernetes secret. Note that the ACL token created will have global-management policy attached to it. You need to provide the name of the resource group and the name of your HCS cluster to the command.

$ az hcs create-token \
  --name <hcs_application_name> \
  --resource-group <resource_group> \
  --output-kubernetes-secret | kubectl apply -f -
secret/learnlab-bootstrap-token created

»Create Kubernetes secret

Create a Kubernetes secret containing HCS cluster information that the Helm chart will use.

az hcs generate-kubernetes-secret \
  --name <hcs_application_name> \
  --resource-group <resource_group> | kubectl apply -f - 
secret/learnlab-hcs created

»Generate Helm values overrides

Lastly, you need to generate Helm overrides for your HCS cluster. You will save it to a file called config.yaml

az hcs generate-helm-values \
  --name <hcs_application_name> \
  --resource-group <resource_group> \
  --aks-cluster-name <aks-cluster-name> > config.yaml

Open config.yaml file and make sure that it is configured correctly for your installation. By default it enables Consul clients and the Consul Service Mesh.

vim config.yaml
  enabled: false
  name: consul
  datacenter: dc1
    manageSystemACLs: true
      secretName: learnlab-bootstrap-token
      secretKey: token
    secretName: learnlab-hcs
    secretKey: gossipEncryptionKey
    enabled: true
    enableAutoEncrypt: true
      secretName: learnlab-hcs
      secretKey: caCert
  enabled: true
  hosts: ['']
  httpsPort: 443
  useSystemRoots: true
  enabled: true
  # If you are using Kubenet in your AKS cluster (the default network),
  # uncomment the line below.
  # exposeGossipPorts: true
  join: ['']
  enabled: true

»Deploy Consul on AKS with Helm

First, add the Hashicorp Helm repository

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

. Then install the Helm chart using the config.yaml file from the previous step.

$ helm install hcs -f config.yaml hashicorp/consul
NAME: hcs
LAST DEPLOYED: Wed Jul 22 17:42:49 2020
NAMESPACE: default
STATUS: deployed
Thank you for installing HashiCorp Consul!

Now that you have deployed Consul, you should look over the docs on using 
Consul with Kubernetes available here:

Your release is named hcs.

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

  $ helm status hcs
  $ helm get hcs

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

  $ helm status hcs
  $ helm get all hcs

Once the install has finished, wait for all components to become running and ready.

$ kubectl get pods
NAME                                             READY   STATUS    RESTARTS   AGE
consul-8ckbs                                     1/1     Running   0          73s
consul-connect-injector-webhook-deployment-...   1/1     Running   0          72s
consul-gx5j2                                     1/1     Running   0          73s
consul-twxzp                                     1/1     Running   0          73s

»Verify Consul installation

Once the client on AKS is running, it should create some default Kubernetes services in Consul. You could go to the Consul UI and check that the client nodes appear in the node page.

Follow the documentation in the main HCS cluster setup tutorial for navigating to the Consul UI. When you first access the UI, you will be asked to login because you don’t have an ACL token set:

Consul UI browser tab login page

To use the bootstrap acl token, retrieve it via kubectl. First, list all secrets with the suffix -bootstrap-token:

$ kubectl get secret | grep bootstrap-token
learnlab-bootstrap-token   Opaque     1       9m10s

Then using that secret name, get the bootstrap acl token:

$ kubectl get secrets/learnlab-bootstrap-token \
    --template={{.data.token}} | base64 --decode

Navigate to the ACL tab in the Consul UI, paste the token and click Log In:

Consul UI browser tab login page token

Once logged in open the Nodes tab and verify that the client nodes from your AKS cluster are registered and healthy in Consul.

Consul UI browser tab nodes tab with one server and three client nodes

»Next steps

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

If you are ready to deploy Consul on Kubernetes in production review the Consul and Kubernetes Reference Architecture recommendations tutorial 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