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:
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.
Set your kubectl context to your AKS cluster:
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.
Create Kubernetes secret
Create a Kubernetes secret containing HCS cluster information that the Helm chart will use.
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
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.
Note
Depending on your AKS network configuration, you may want to change the value of client.exposeGossipPorts
. If you are using Kubenet, set this value to true by uncommenting the correspondent line.
Deploy Consul on AKS with Helm
First, add the Hashicorp Helm repository
.
Then install the Helm chart using the config.yaml
file from the previous step.
Once the install has finished, wait for all components to become running and ready.
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
:
Then using that secret name, get the bootstrap acl token:
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.