Connect an Azure Kubernetes Service (AKS) cluster to HCS 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.

Prerequisites

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.

Install the HashiCorp extension

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

$ az extension add \
  --source https://releases.hashicorp.com/hcs/0.4.9/hcs-0.4.9-py2.py3-none-any.whl

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.

global:
  enabled: false
  name: consul
  datacenter: dc1
  acls:
    manageSystemACLs: true
    bootstrapToken:
      secretName: learnlab-bootstrap-token
      secretKey: token
  gossipEncryption:
    secretName: learnlab-hcs
    secretKey: gossipEncryptionKey
  tls:
    enabled: true
    enableAutoEncrypt: true
    caCert:
      secretName: learnlab-hcs
      secretKey: caCert
externalServers:
  enabled: true
  hosts:
    ['11eacc1c-bf82-541e-9b72-0242ac110010.private.consul.az.hashicorp.cloud']
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: https://learn-aks-cluster-dns-ba16b7c8.hcp.eastus.azmk8s.io:443
client:
  enabled: true
  # If you are using Kubenet in your AKS cluster (the default network),
  # uncomment the line below.
  # exposeGossipPorts: true
  join:
    ['11eacc1c-bf82-541e-9b72-0242ac110010.private.consul.az.hashicorp.cloud']
connectInject:
  enabled: true
controller:
  enabled: true

Deploy Consul on AKS with Helm

First, add the Hashicorp Helm repository

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"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

$ helm install --name hcs -f config.yaml hashicorp/consul

NAME: hcs
LAST DEPLOYED: Wed Jul 22 17:42:49 2020
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
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:

https://www.consul.io/docs/platform/k8s/index.html


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:

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

3241b494-02f8-c6d1-c115-6a220ae0f466

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

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

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 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 hcs@hashicorp.com.