Configure AKS as a Consul Client for HCP Consul

HashiCorp Cloud Platform (HCP) Consul is a fully managed Service Mesh as a Service (SMaaS) version of Consul. After you deploy an HCP Consul server cluster, you must deploy Consul clients into your network so you can leverage Consul's full feature set including service mesh and service discovery. For Azure, HCP Consul supports Consul clients running on Azure Kubernetes Service (AKS) and virtual machine (VM) workloads.

In this tutorial, you will configure an AKS cluster to connect to your HCP Consul cluster. Then, you will deploy HashiCups, a demo application that lets you view and order customized HashiCorp branded coffee, to your AKS cluster to leverage HCP Consul's service mesh and API Gateway capabilities.

»Prerequisites

For this tutorial, you will need:

the Terraform 0.14+ CLI installed locally.
An HCP account configured for use with Terraform
an Azure account
the Azure CLI
kubectl
helm
jq

In order for Terraform to run operations on your behalf, login into Azure.

$ az login

$ az login

»Clone example repository

In your terminal, clone the example repository. This repository contains Terraform configuration to deploy different types of Consul clusters, including the one you will need in this tutorial.

$ git clone https://github.com/hashicorp/learn-consul-terraform

$ git clone https://github.com/hashicorp/learn-consul-terraform

Navigate to the project directory in the cloned repository.

$ cd learn-consul-terraform/datacenter-deploy-aks-hcp

$ cd learn-consul-terraform/datacenter-deploy-aks-hcp

»Review configuration

The project directory contains three sub-directories:

The azure subdirectory contains Terraform configuration to deploy an Azure resource group, virtual network (VNet) and underlying networking resources, and an AKS cluster. Notice these specific AKS configuration:

The vnet_subnet_id is set to the VNet's subnet. By default, AKS creates a virtual network and subnet for you. By specifying the VNet subnet, you ensure the AKS node pool must reside in the VNet peered with HCP Consul.
The network_plugin is set to azure. By default, AKS clusters use kubenet. By specifying the network_plugin, you ensure that the AKS cluster uses the Azure networking.
The service_principal stanza lets you access your AKS cluster without using managed identity.

resource "azurerm_kubernetes_cluster" "default" {
  ## ...

  default_node_pool {
    name            = "default"
    node_count      = 3
    vm_size         = "Standard_D2_v2"
    os_disk_size_gb = 30
    vnet_subnet_id  = module.network.vnet_subnets[0]
  }

  network_profile {
    network_plugin = "azure"
  }

  service_principal {
    client_id     = var.appId
    client_secret = var.password
  }

  ## ...
}

datacenter-deploy-aks-hcp/azure

resource "azurerm_kubernetes_cluster" "default" {
  ## ...

  default_node_pool {
    name            = "default"
    node_count      = 3
    vm_size         = "Standard_D2_v2"
    os_disk_size_gb = 30
    vnet_subnet_id  = module.network.vnet_subnets[0]
  }

  network_profile {
    network_plugin = "azure"
  }

  service_principal {
    client_id     = var.appId
    client_secret = var.password
  }

  ## ...
}

Note: The hashicorp/hcp-consul/azurerm Terraform module creates a security group that allows TCP/UDP ingress traffic on port 8301 and allows all egress. The egress security rule lets the VM instance download dependencies required for the Consul client including the Consul binary and Docker.

The hcp subdirectory contains Terraform configuration that creates an HCP HashiCorp Virtual Network (HVN), and an HCP Consul. In addition, it uses the hashicorp/hcp-consul/azurerm Terraform module to set up all networking rules to allow a Consul client to communicate with the HCP Consul servers. This includes setting up the peering connection between the HVN and your VNet, setting up the HCP routes, and creating VNet ingress rules.
In addition, this configuration defines an ingress rule that allows port 8080 traffic. This ensures that users can visit the HashiCups demo application.
The hashicups subdirectory contains the HashiCups demo application yaml files for Kubernetes. These files define the Deployments and Services for each HashiCups microservices, in addition to setting up Consul service intentions and API Gateway.

This tutorial intentionally separates the Terraform configuration into two discrete steps. This process reflects Terraform best practices. By dividing the HCP Consul cluster management from the Consul client management (AKS), you can separate the duties and reduce the blast radius.

»Deploy Azure resources

Now that you have reviewed the Terraform configuration, you will now deploy an Azure resource group, virtual network (VNet) and underlying networking resources, and an AKS cluster.

Navigate to the azure directory.

$ cd azure

$ cd azure

Next, create an Active Directory service principal account. You will use this AD service principal account to authenticate to the AKS cluster.

$ az ad sp create-for-rbac --skip-assignment
{
  "appId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "azure-cli-2021-04-22-17-52-06",
  "name": "http://azure-cli-2021-04-22-17-52-06",
  "password": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tenant": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

$ az ad sp create-for-rbac --skip-assignment
{
  "appId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "azure-cli-2021-04-22-17-52-06",
  "name": "http://azure-cli-2021-04-22-17-52-06",
  "password": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tenant": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

Rename the terraform.tfvars.example file to terraform.tfvars.

$ mv terraform.tfvars.example terraform.tfvars

$ mv terraform.tfvars.example terraform.tfvars

Note: The .gitignore file in this repository includes any .tfvars files to prevent you from accidentally committing your credentials to version control.

Open the terraform.tfvars file and replace the appId and password values with those displayed in your output from the previous command.

appId    = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
password = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

azure/terraform.tfvars

appId    = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
password = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Initialize the Terraform configuration.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/Azure/vnet/azurerm 2.6.0 for network...
- network in .terraform/modules/network

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/azurerm from the dependency lock file
- Reusing previous version of hashicorp/hcp from the dependency lock file
- Installing hashicorp/azurerm v3.6.0...
- Installed hashicorp/azurerm v3.6.0 (signed by HashiCorp)
- Installing hashicorp/hcp v0.29.0...
- Installed hashicorp/hcp v0.29.0 (signed by HashiCorp)

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/Azure/vnet/azurerm 2.6.0 for network...
- network in .terraform/modules/network

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/azurerm from the dependency lock file
- Reusing previous version of hashicorp/hcp from the dependency lock file
- Installing hashicorp/azurerm v3.6.0...
- Installed hashicorp/azurerm v3.6.0 (signed by HashiCorp)
- Installing hashicorp/hcp v0.29.0...
- Installed hashicorp/hcp v0.29.0 (signed by HashiCorp)

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Next, apply the configuration. Respond yes to the prompt to confirm.

$ terraform apply

## ...

Plan: 14 to add, 0 to change, 0 to destroy.

Outputs:

azure_nsg_name = "learn-hcp-consul-aks-client-nsg"
azure_rg_name = "learn-hcp-consul-aks-client-gid"
azure_subnet_ids = [
  "/subscriptions/c9ed8610-47a3-4107-a2b2-a322114dfb29/resourceGroups/learn-hcp-consul-aks-client-gid/providers/Microsoft.Network/virtualNetworks/learn-hcp-consul-aks-client-vnet/subnets/subnet1",
## ...
]
azure_vnet_id = "/subscriptions/c9ed8610-47a3-4107-a2b2-a322114dfb29/resourceGroups/learn-hcp-consul-aks-client-gid/providers/Microsoft.Network/virtualNetworks/learn-hcp-consul-aks-client-vnet"
azure_vnet_name = "learn-hcp-consul-aks-client-vnet"
kubernetes_cluster_name = "learn-hcp-consul-aks-client-aks"

$ terraform apply

## ...

Plan: 14 to add, 0 to change, 0 to destroy.

Outputs:

azure_nsg_name = "learn-hcp-consul-aks-client-nsg"
azure_rg_name = "learn-hcp-consul-aks-client-gid"
azure_subnet_ids = [
  "/subscriptions/c9ed8610-47a3-4107-a2b2-a322114dfb29/resourceGroups/learn-hcp-consul-aks-client-gid/providers/Microsoft.Network/virtualNetworks/learn-hcp-consul-aks-client-vnet/subnets/subnet1",
## ...
]
azure_vnet_id = "/subscriptions/c9ed8610-47a3-4107-a2b2-a322114dfb29/resourceGroups/learn-hcp-consul-aks-client-gid/providers/Microsoft.Network/virtualNetworks/learn-hcp-consul-aks-client-vnet"
azure_vnet_name = "learn-hcp-consul-aks-client-vnet"
kubernetes_cluster_name = "learn-hcp-consul-aks-client-aks"

Notice that Terraform displays the outputs created from the apply.

»Create terraform.tfvars file for Consul client directory

Since you created the underlying infrastructure with Terraform, you can use the outputs to help you deploy the HCP resources in the next section.

Create a terraform.tfvars file in the hcp directory with the Terraform outputs from this project.

$ echo "azure_vnet_name=\"$(terraform output -raw azure_vnet_name)\"
azure_vnet_id=\"$(terraform output -raw azure_vnet_id)\"
azure_rg_name=\"$(terraform output -raw azure_rg_name)\"
azure_nsg_name=\"$(terraform output -raw azure_nsg_name)\"
azure_subnet_ids=$(terraform output -json azure_subnet_ids)" > ../hcp/terraform.tfvars

$ echo "azure_vnet_name=\"$(terraform output -raw azure_vnet_name)\"
azure_vnet_id=\"$(terraform output -raw azure_vnet_id)\"
azure_rg_name=\"$(terraform output -raw azure_rg_name)\"
azure_nsg_name=\"$(terraform output -raw azure_nsg_name)\"
azure_subnet_ids=$(terraform output -json azure_subnet_ids)" > ../hcp/terraform.tfvars

»Configure kubectl

Run the following command to retrieve the access credentials for your cluster and automatically configure kubectl.

$ az aks get-credentials --resource-group $(terraform output -raw azure_rg_name) --name $(terraform output -raw kubernetes_cluster_name)
Merged "learn-hcp-consul-aks-client-aks" as current context in /Users/user/.kube/config

$ az aks get-credentials --resource-group $(terraform output -raw azure_rg_name) --name $(terraform output -raw kubernetes_cluster_name)
Merged "learn-hcp-consul-aks-client-aks" as current context in /Users/user/.kube/config

»Deploy HCP Consul and resources

Navigate to the hcp directory.

$ cd ../hcp

$ cd ../hcp

Initialize the Terraform configuration.

$ terraform init

$ terraform init

Next, apply the configuration. Respond yes to the prompt to confirm.

$ terraform apply

## ...

Plan: 13 to add, 0 to change, 0 to destroy.

Outputs:

consul_root_token = <sensitive>
consul_url = "https://servers-public-consul-f3239351.7171f9f3.z1.hashicorp.cloud"
next_steps = "Hashicups Application will be ready in ~2 minutes. Use 'terraform output consul_root_token' to retrieve the root token."

$ terraform apply

## ...

Plan: 13 to add, 0 to change, 0 to destroy.

Outputs:

consul_root_token = <sensitive>
consul_url = "https://servers-public-consul-f3239351.7171f9f3.z1.hashicorp.cloud"
next_steps = "Hashicups Application will be ready in ~2 minutes. Use 'terraform output consul_root_token' to retrieve the root token."

Notice that Terraform displays the outputs created from the apply.

»Configure development host

Now that you have deployed HCP Consul, you need to retrieve the Consul client configuration information. You will use this information to configure the Consul client so it can connect to the HCP Consul cluster. In addition, you will retrieve the ACL token and HCP Consul public URL to authenticate your Consul CLI.

Tip: If you started from the HCP Portal, select Start from HCP Portal for instructions pertinent to your deployment method.

You can use the HCP Portal to retrieve the client configuration information that you need to connect your AKS cluster client agents to your HCP Consul cluster. Navigate to the Consul resource page in the HCP portal, and then select the Consul cluster you want to join your AKS cluster client agents to. Click the Access Consul dropdown and then click Download to install Client Agents to download a zip archive that contains the necessary files to join your client agents to the cluster.

The archive includes a default client configuration and certificate. Both should be considered secrets, and should be kept in a secure location.

Unzip the client config package into the current working directory, and then use ls to confirm that both the client_config.json and ca.pem files are available.

$ ls
ca.pem             client_config.json

$ ls
ca.pem             client_config.json

Now you will set your CONSUL_HTTP_ADDR and CONSUL_HTTP_TOKEN environment variables so you can verify Consul installation later.

First, set your CONSUL_HTTP_ADDR environment variable.

$ export CONSUL_HTTP_ADDR=$(terraform output -raw consul_url)

$ export CONSUL_HTTP_ADDR=$(terraform output -raw consul_url)

Then, set your CONSUL_HTTP_TOKEN environment variable.

$ export CONSUL_HTTP_TOKEN=$(terraform output -raw consul_root_token)

$ export CONSUL_HTTP_TOKEN=$(terraform output -raw consul_root_token)

Create a consul namespace in your Kubernetes cluster. Your Consul secrets and resources will be created in this namespace.

$ kubectl create namespace consul
namespace/consul created

$ kubectl create namespace consul
namespace/consul created

»Configure Consul secrets

In this tutorial, you will apply HCP Consul's secure-by-default design by configuring the Consul clients with the gossip encryption key, the Consul CA cert, and a permissive ACL token. You need to store all three of these secrets in the Kubernetes secrets engine so that you can reference them during the helm chart installation.

Use the ca.pem file in the current directory to create a Kubernetes secret to store the Consul CA certificate.

$ kubectl create secret generic "consul-ca-cert" --from-file='tls.crt=./ca.pem' --namespace consul
secret/consul-ca-cert created

$ kubectl create secret generic "consul-ca-cert" --from-file='tls.crt=./ca.pem' --namespace consul
secret/consul-ca-cert created

The Consul gossip encryption key is embedded in the client_config.json file that you downloaded and extracted into your current directory. Issue the following command to create a Kubernetes secret that stores the Consul gossip key encryption key. The following command uses jq to extract the value from the client_config.json file.

$ kubectl create secret generic "consul-gossip-key" --from-literal="key=$(jq -r .encrypt client_config.json)" --namespace consul
secret/consul-gossip-key created

$ kubectl create secret generic "consul-gossip-key" --from-literal="key=$(jq -r .encrypt client_config.json)" --namespace consul
secret/consul-gossip-key created

The last secret you need to add is an ACL bootstrap token. You can use the one you set to your CONSUL_HTTP_TOKEN environment variable earlier. Issue the following command to create a Kubernetes secret to store the bootstrap ACL token.

Note: If you are configuring a production environment, you should create a client token with a minimum set of privileges. For an in depth review of how to configure ACLs for Consul, refer to the Secure Consul with Access Control Lists tutorial or the official documentation.

$ kubectl create secret generic "consul-bootstrap-token" --from-literal="token=${CONSUL_HTTP_TOKEN}" --namespace consul
secret/consul-bootstrap-token created

$ kubectl create secret generic "consul-bootstrap-token" --from-literal="token=${CONSUL_HTTP_TOKEN}" --namespace consul
secret/consul-bootstrap-token created

»Create Consul configuration file

Extract some more configuration values from the client_config.json file and set them to environment variables that can be used to generate your Helm values file. Issue the following command to set the DATACENTER environment variable.

$ export DATACENTER=$(jq -r .datacenter client_config.json)

$ export DATACENTER=$(jq -r .datacenter client_config.json)

Extract the private server URL from the client config so that it can be set in the Helm values file as the externalServers:hosts entry. This value will be passed as the retry-join option to the Consul clients.

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

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

Extract the public server URL from the client config so that it can be set in the Helm values file as the k8sAuthMethodHost entry.

Note: The following script relies on your cluster matching your current-context name. If you have created an alias for your context, or the current-context name does not match the cluster name for any other reason, you must manually set the KUBE_API_URL to your AKS cluster's API server URL. You can use kubectl config view to view your cluster, and retrieve API server URL.

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

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

Validate that you have set environment variables correctly.

$ echo $DATACENTER && \
  echo $RETRY_JOIN && \
  echo $KUBE_API_URL

$ echo $DATACENTER && \
  echo $RETRY_JOIN && \
  echo $KUBE_API_URL

The output should look similar to the following:

learn-hcp-consul-aks-client
["servers-private-consul-f3239351.7171f9f3.z1.hashicorp.cloud"]
https://learn-hcp-consul-aks-client-k8s-9f690a3c.hcp.westus2.azmk8s.io:443

learn-hcp-consul-aks-client
["servers-private-consul-f3239351.7171f9f3.z1.hashicorp.cloud"]
https://learn-hcp-consul-aks-client-k8s-9f690a3c.hcp.westus2.azmk8s.io:443

Note: If any of these environment variables are not correctly set, the following script will generate an incomplete Helm values file, and the Consul Helm installation will not succeed.

Generate the Helm values file. Note that this configuration sets up an ingress gateway. This will be covered in more depth later.

Note: The value for the global.name configuration must be unique for each Kubernetes cluster where Consul clients are installed and configured to join Consul as a shared service, such as HCP Consul. You can change the global name through the global.name value in the Helm chart.

How you install Consul Clients depends on your HCP Consul Cluster:

To install clients on a single Consul cluster, choose the Single Consul Cluster tab.
To install clients on a primary or secondary Consul cluster that is part of a federated environment, select the Federated Consul Cluster tab.

$ cat > config.yaml << EOF
global:
  name: consul
  enabled: false
  datacenter: ${DATACENTER}
  acls:
    manageSystemACLs: true
    bootstrapToken:
      secretName: consul-bootstrap-token
      secretKey: token
  gossipEncryption:
    secretName: consul-gossip-key
    secretKey: key
  tls:
    enabled: true
    enableAutoEncrypt: true
    caCert:
      secretName: consul-ca-cert
      secretKey: tls.crt
  enableConsulNamespaces: true
externalServers:
  enabled: true
  hosts: ${RETRY_JOIN}
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: ${KUBE_API_URL}
client:
  enabled: true
  join: ${RETRY_JOIN}
connectInject:
  enabled: true
controller:
  enabled: true
ingressGateways:
  enabled: true
  defaults:
    replicas: 1
  gateways:
    - name: ingress-gateway
      service:
        type: LoadBalancer
EOF

$ cat > config.yaml << EOF
global:
  name: consul
  enabled: false
  datacenter: ${DATACENTER}
  acls:
    manageSystemACLs: true
    bootstrapToken:
      secretName: consul-bootstrap-token
      secretKey: token
  gossipEncryption:
    secretName: consul-gossip-key
    secretKey: key
  tls:
    enabled: true
    enableAutoEncrypt: true
    caCert:
      secretName: consul-ca-cert
      secretKey: tls.crt
  enableConsulNamespaces: true
externalServers:
  enabled: true
  hosts: ${RETRY_JOIN}
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: ${KUBE_API_URL}
client:
  enabled: true
  join: ${RETRY_JOIN}
connectInject:
  enabled: true
controller:
  enabled: true
ingressGateways:
  enabled: true
  defaults:
    replicas: 1
  gateways:
    - name: ingress-gateway
      service:
        type: LoadBalancer
EOF

Open your config.yaml file to validate that the config file is populated correctly.

global:
  name: consul
  enabled: false
  datacenter: learn-hcp-consul-aks-client
  ## ...

config.yaml

global:
  name: consul
  enabled: false
  datacenter: learn-hcp-consul-aks-client
  ## ...

»Deploy Consul on AKS

Now that you have customized your config.yaml file, you can deploy Consul with Helm or the Consul K8S CLI. We recommend you deploy Consul into its own dedicated namespace as shown below. This should only take a few minutes. The Consul pods should appear in the pod list immediately.

Note: HCP offers Enterprise features. To interact with these enterprise features, you need to install the Enterprise Consul binary for your client agents. You can find more information about Consul Enterprise and the Helm Chart in the Consul Enterprise Helm Chart documentation.

First, install the HashiCorp tap, a repository of all HashiCorp's Homebrew packages.

$ brew tap hashicorp/tap

$ brew tap hashicorp/tap

Now, install consul-k8s.

$ brew install hashicorp/tap/consul-k8s

$ brew install hashicorp/tap/consul-k8s

Finally, deploy Consul on your AKS cluster. When prompted, confirm the installation with a y.

$ consul-k8s install -config-file=config.yaml -set global.image=hashicorp/consul-enterprise:1.12.0-ent

$ consul-k8s install -config-file=config.yaml -set global.image=hashicorp/consul-enterprise:1.12.0-ent

Visit the official Consul K8S CLI documentation to learn more about additional settings.

Confirm you deployed Consul successfully onto your AKS cluster.

$ kubectl get pods --namespace consul
NAME                                           READY   STATUS    RESTARTS   AGE
consul-client-2b762                            1/1     Running   0          111s
consul-client-gf9ts                            1/1     Running   0          111s
consul-client-vdb8m                            1/1     Running   0          111s
consul-connect-injector-7fb8b94886-8fplq       1/1     Running   0          111s
consul-connect-injector-7fb8b94886-h74hc       1/1     Running   0          111s
consul-controller-68c4cd7954-kxf5g             1/1     Running   0          111s
consul-ingress-gateway-74884cf8bf-pdvh2        2/2     Running   0          111s
consul-webhook-cert-manager-859c76cdf6-sv5mw   1/1     Running   0          111s

$ kubectl get pods --namespace consul
NAME                                           READY   STATUS    RESTARTS   AGE
consul-client-2b762                            1/1     Running   0          111s
consul-client-gf9ts                            1/1     Running   0          111s
consul-client-vdb8m                            1/1     Running   0          111s
consul-connect-injector-7fb8b94886-8fplq       1/1     Running   0          111s
consul-connect-injector-7fb8b94886-h74hc       1/1     Running   0          111s
consul-controller-68c4cd7954-kxf5g             1/1     Running   0          111s
consul-ingress-gateway-74884cf8bf-pdvh2        2/2     Running   0          111s
consul-webhook-cert-manager-859c76cdf6-sv5mw   1/1     Running   0          111s

»Verify Consul on AKS

Now that you have deployed Consul on AKS, verify that the Consul datacenter contains both your HCP Consul server nodes and your client nodes running on AKS. Notice there are 3 client nodes — one for each node in your AKS node pool.

$  consul members
Node                                  Address           Status  Type    Build       Protocol  DC                           Segment
1cbbd45e-c487-587a-8ff8-7747fef301a6  172.25.16.4:8301  alive   server  1.11.6+ent  2         learn-hcp-consul-aks-client  <all>
aks-default-35547382-vmss000000       10.1.1.5:8301     alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>
aks-default-35547382-vmss000001       10.1.1.45:8301    alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>
aks-default-35547382-vmss000002       10.1.1.68:8301    alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>

$  consul members
Node                                  Address           Status  Type    Build       Protocol  DC                           Segment
1cbbd45e-c487-587a-8ff8-7747fef301a6  172.25.16.4:8301  alive   server  1.11.6+ent  2         learn-hcp-consul-aks-client  <all>
aks-default-35547382-vmss000000       10.1.1.5:8301     alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>
aks-default-35547382-vmss000001       10.1.1.45:8301    alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>
aks-default-35547382-vmss000002       10.1.1.68:8301    alive   client  1.12.0      2         learn-hcp-consul-aks-client  <default>

»Deploy an example workload

Now you have set up Consul clients on your AKS cluster, it is time to deploy an application workload. This tutorial will use the HashiCups demo application.

Navigate to the hashicups directory.

$ cd ../hashicups

$ cd ../hashicups

This directory contains the necessary yaml files to deploy the HashiCups application. Issue the following command to deploy the application to your AKS cluster.

$ kubectl apply -f .
service/frontend created
serviceaccount/frontend created
servicedefaults.consul.hashicorp.com/frontend created
deployment.apps/frontend created
service/nginx created
configmap/nginx-config created
serviceaccount/nginx created
servicedefaults.consul.hashicorp.com/nginx created
deployment.apps/nginx created
service/payments created
serviceaccount/payments created
servicedefaults.consul.hashicorp.com/payments created
deployment.apps/payments created
service/product-api-db created
servicedefaults.consul.hashicorp.com/product-api-db created
serviceaccount/product-api-db created
deployment.apps/product-api-db created
service/product-api created
serviceaccount/product-api created
servicedefaults.consul.hashicorp.com/product-api created
configmap/db-configmap created
deployment.apps/product-api created
service/public-api created
serviceaccount/public-api created
servicedefaults.consul.hashicorp.com/public-api created
deployment.apps/public-api created

$ kubectl apply -f .
service/frontend created
serviceaccount/frontend created
servicedefaults.consul.hashicorp.com/frontend created
deployment.apps/frontend created
service/nginx created
configmap/nginx-config created
serviceaccount/nginx created
servicedefaults.consul.hashicorp.com/nginx created
deployment.apps/nginx created
service/payments created
serviceaccount/payments created
servicedefaults.consul.hashicorp.com/payments created
deployment.apps/payments created
service/product-api-db created
servicedefaults.consul.hashicorp.com/product-api-db created
serviceaccount/product-api-db created
deployment.apps/product-api-db created
service/product-api created
serviceaccount/product-api created
servicedefaults.consul.hashicorp.com/product-api created
configmap/db-configmap created
deployment.apps/product-api created
service/public-api created
serviceaccount/public-api created
servicedefaults.consul.hashicorp.com/public-api created
deployment.apps/public-api created

»Register a Consul ingress gateway

In Consul, an ingress gateway is a kind of resources called a Config Entry. An ingress gateway is an endpoint that allows external traffic to reach specific resources, such as the application user interface, that are hosted within the datacenter.

Open ingress-gateway/ingress-gateway.yaml. You will use this to register an ingress gateway with Consul. Notice the Name value matches the ingressGateways:gateways:name entry in config.yaml. These fields must match.

Notice that the ingress-gateway listener is set to port 8080. This is the default ingress gateway port when you set up ingress gateway through Helm or consul-k8s.

---
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
  name: ingress-gateway
spec:
  listeners:
    - port: 8080
      protocol: http
      services:
        - name: nginx
          hosts: ["*"]

hashicups/ingress-gateway/ingress-gateway.yaml

---
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
  name: ingress-gateway
spec:
  listeners:
    - port: 8080
      protocol: http
      services:
        - name: nginx
          hosts: ["*"]

Now, register the config entry with Consul.

$ kubectl apply -f ./ingress-gateway
ingressgateway.consul.hashicorp.com/ingress-gateway created

$ kubectl apply -f ./ingress-gateway
ingressgateway.consul.hashicorp.com/ingress-gateway created

»Create the necessary intentions

Since HCP Consul on Azure is secure by default, the datacenter is created with a "default deny" intention in place. This means that, by default, no services can interact with each other until an operator explicitly allows them to do so by creating intentions for each inter-service operation they wish to allow.

As of Consul 1.9, service-intentions config entries can be created using CRDs. Open intentions/intentions.yaml. This file defines the intentions necessary for HashiCups. Notice this also creates an intention from the ingress-gateway to the nginx service, the HashiCups entrypoint.

---
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: nginx
spec:
  # Name of the destination service affected by this ServiceIntentions entry
  destination:
    name: nginx
  # The set of traffic sources affected by this ServiceIntentions entry
  sources:
    - name: ingress-gateway
      action: allow
## ...

hashicups/intentions/intentions.yaml

---
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: nginx
spec:
  # Name of the destination service affected by this ServiceIntentions entry
  destination:
    name: nginx
  # The set of traffic sources affected by this ServiceIntentions entry
  sources:
    - name: ingress-gateway
      action: allow
## ...

Run the following command to create the service-intentions config entries the HashiCups application requires to run.

$ kubectl apply -f ./intentions
serviceintentions.consul.hashicorp.com/nginx created
serviceintentions.consul.hashicorp.com/frontend created
serviceintentions.consul.hashicorp.com/public-api created
serviceintentions.consul.hashicorp.com/product-api created
serviceintentions.consul.hashicorp.com/product-api-db created
serviceintentions.consul.hashicorp.com/payments created

$ kubectl apply -f ./intentions
serviceintentions.consul.hashicorp.com/nginx created
serviceintentions.consul.hashicorp.com/frontend created
serviceintentions.consul.hashicorp.com/public-api created
serviceintentions.consul.hashicorp.com/product-api created
serviceintentions.consul.hashicorp.com/product-api-db created
serviceintentions.consul.hashicorp.com/payments created

»Access the HashiCups UI

With the intentions in place, all that remains is to retrieve the public URL and port of the ingress gateway. Do this by retrieving a list of services.

$ kubectl get services --namespace consul
NAME                        TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                         AGE
consul-ingress-gateway      LoadBalancer   10.0.249.82    20.99.177.218   8080:30694/TCP,8443:30943/TCP   11m
## ...

$ kubectl get services --namespace consul
NAME                        TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                         AGE
consul-ingress-gateway      LoadBalancer   10.0.249.82    20.99.177.218   8080:30694/TCP,8443:30943/TCP   11m
## ...

Use the following command to verify you have successfully deployed the application.

$ echo "http://$(kubectl get svc/consul-ingress-gateway --namespace consul -o json | jq -r '.status.loadBalancer.ingress[0].ip'):8080"
http://20.99.177.218:8080

$ echo "http://$(kubectl get svc/consul-ingress-gateway --namespace consul -o json | jq -r '.status.loadBalancer.ingress[0].ip'):8080"
http://20.99.177.218:8080

Open the URL in your browser to find the HashiCups UI.

Note: If you are unable to load the HashiCups UI, verify you have an Azure ingress rule that allows port 8080.

This validates that Consul service discovery is working, because the services are able to resolve the upstreams. This also validates that Consul service mesh is working, because the intentions that were created are allowing services to interact with one another.

»Next steps

In this tutorial, you connected Consul clients on AKS to HCP Consul and deployed a demo application. To keep learning about Consul's features, and for step-by-step examples of how to perform common Consul tasks, complete one of the following tutorials.

If you encounter any issues, please contact the HCP team at support.hashicorp.com.

Infrastructure

Security

Applications

Networking

cloud