Getting Started with Consul Service Mesh for Kubernetes

This tutorial installs and configures Consul service mesh on a Kubernetes cluster.

By the end of this tutorial, you will be able to identify the installation prerequisites, install Consul with the official Helm chart, and deploy an example application.

»Prerequisites

The following components are required to complete this tutorial:

Docker.
A local Kubernetes cluster. Popular options for starting clusters include Minikube, kind, and k3s. This tutorial uses Minikube.
Helm
Consul K8s CLI

»Clone the Demo Configuration and Application

The learn-consul-kubernetes repository contains resources to help you understand how to use Consul in your Kubernetes clusters. Clone the repository to download the demo configuration and application used in this tutorial:

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

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

Change to the /service-mesh/deploy directory, which contains all of the artifacts used in this tutorial.

$ cd learn-consul-kubernetes/service-mesh/deploy

$ cd learn-consul-kubernetes/service-mesh/deploy

»Deploy Consul

First, start a Kubernetes cluster.

$ minikube start --driver=docker

$ minikube start --driver=docker

After you start Kubernetes, you can deploy Consul with Helm or with the consul-k8s command line tool.

To deploy Consul service mesh using Helm, you need a copy of the official chart. You can add the official HashiCorp Consul Helm chart repo from the command line using the Helm CLI.

$ helm repo add hashicorp https://helm.releases.hashicorp.com

"hashicorp" has been added to your repositories

$ helm repo add hashicorp https://helm.releases.hashicorp.com

"hashicorp" has been added to your repositories

Update your local Helm repositories to ensure you have the latest Consul Helm chart.

$ helm repo update

Hang tight while we grab the latest from your chart repositories...
...TRUNCATED...
Update Complete. ⎈Happy Helming!⎈

$ helm repo update

Hang tight while we grab the latest from your chart repositories...
...TRUNCATED...
Update Complete. ⎈Happy Helming!⎈

Deploy the Consul Helm chart using the values in config.yaml. This configuration deploys the control plane for the service mesh, which includes a Consul server, client, controller, and injector in a dedicated consul Kubernetes namespace. It also installs a demo instance of Prometheus and Grafana for metrics.

$ helm install -f config.yaml consul hashicorp/consul --create-namespace -n consul

NAME: consul
...TRUNCATED...
  $ helm status consul
  $ helm get all consul

$ helm install -f config.yaml consul hashicorp/consul --create-namespace -n consul

NAME: consul
...TRUNCATED...
  $ helm status consul
  $ helm get all consul

Validate the installation by checking for running Consul pods.

$ kubectl get pods --namespace consul --selector app=consul

NAME                                           READY   STATUS    RESTARTS   AGE
consul-client-5m8x6                            1/1     Running   0          107s
consul-connect-injector-779f47bd5c-lz29v       1/1     Running   0          107s
consul-connect-injector-779f47bd5c-mg82l       1/1     Running   0          107s
consul-controller-8685544b44-24qhf             1/1     Running   0          107s
consul-server-0                                1/1     Running   0          107s
consul-webhook-cert-manager-5ccc876d58-6bqf8   1/1     Running   0          107s

$ kubectl get pods --namespace consul --selector app=consul

NAME                                           READY   STATUS    RESTARTS   AGE
consul-client-5m8x6                            1/1     Running   0          107s
consul-connect-injector-779f47bd5c-lz29v       1/1     Running   0          107s
consul-connect-injector-779f47bd5c-mg82l       1/1     Running   0          107s
consul-controller-8685544b44-24qhf             1/1     Running   0          107s
consul-server-0                                1/1     Running   0          107s
consul-webhook-cert-manager-5ccc876d58-6bqf8   1/1     Running   0          107s

»Interact with Consul

To access the Consul UI, set up port forwarding to port 8500.

$ kubectl port-forward pods/consul-server-0 8500:8500 --namespace consul

$ kubectl port-forward pods/consul-server-0 8500:8500 --namespace consul

Then, open your browser and go to http://localhost:8500. Explore the Consul UI by clicking the Nodes and Services tabs.

You can use kubectl exec to get direct access to any container, including the Consul server. Use this command to check for a list of Consul's servers and clients. Consul servers configure and control the service mesh, while clients help with service discovery.

$ kubectl exec -it consul-server-0 --namespace consul -- consul members

Node             Address          Status  Type    Build   Protocol  DC   Partition  Segment
consul-server-0  172.17.0.5:8301  alive   server  1.12.0  2         dc1  default    <all>
minikube         172.17.0.4:8301  alive   client  1.12.0  2         dc1  default    <default>

$ kubectl exec -it consul-server-0 --namespace consul -- consul members

Node             Address          Status  Type    Build   Protocol  DC   Partition  Segment
consul-server-0  172.17.0.5:8301  alive   server  1.12.0  2         dc1  default    <all>
minikube         172.17.0.4:8301  alive   client  1.12.0  2         dc1  default    <default>

»Deploy a demo application

You can explore Consul service mesh by installing a demo application. The demo application, named HashiCups, includes a set of services and a PostgreSQL database. It allows you to order a cup of coffee.

Open a new terminal and deploy the demo application to your cluster.

$ kubectl apply -f hashicups/

$ kubectl apply -f hashicups/

The services use an annotation that allows Consul to automatically inject a proxy for each service. The proxies create a data plane to handle requests between services based on configuration from Consul. You can check for applications with proxies by selecting the label for Consul injection.

$ kubectl get pods --selector consul.hashicorp.com/connect-inject-status=injected

NAME                           READY   STATUS    RESTARTS   AGE
frontend-7755cf85bf-rxq7p       3/3     Running   0          119s
nginx-6887ddb866-c4j4s          3/3     Running   0          119s
payments-9f76969c7-pntv9        3/3     Running   0          119s
postgres-d74c7cbf8-rm2gw        3/3     Running   0          119s
products-api-587cfbf4d8-v8jzt   3/3     Running   0          118s
public-api-6db5c68b79-46wcz     4/4     Running   0          118s

$ kubectl get pods --selector consul.hashicorp.com/connect-inject-status=injected

NAME                           READY   STATUS    RESTARTS   AGE
frontend-7755cf85bf-rxq7p       3/3     Running   0          119s
nginx-6887ddb866-c4j4s          3/3     Running   0          119s
payments-9f76969c7-pntv9        3/3     Running   0          119s
postgres-d74c7cbf8-rm2gw        3/3     Running   0          119s
products-api-587cfbf4d8-v8jzt   3/3     Running   0          118s
public-api-6db5c68b79-46wcz     4/4     Running   0          118s

»Explore the application

You can now explore the demo application and how it uses Consul service mesh. Forward the nginx service to port 18080.

$ kubectl port-forward service/nginx 18080:80 --address 0.0.0.0

$ kubectl port-forward service/nginx 18080:80 --address 0.0.0.0

The HashiCups UI will be available at http://localhost:18080 in your browser. Refresh the page a few times.

Go to the Consul UI on http://localhost:8500. You'll find the HashiCups services registered to Consul service mesh with proxies.

Select the products-api service. The Topology tab indicates that requests to the public-api goes to the product-api before accessing the database. Consul embeds a graph aggregating successful requests and error metrics.

»Clean up

After you complete this tutorial, you can stop Consul, the demo application, and the Kubernetes cluster.

Remove all HashiCups resources.

$ kubectl delete -f hashicups/

$ kubectl delete -f hashicups/

Remove all Consul resources.

$ consul-k8s uninstall -auto-approve -wipe-data && kubectl delete pvc/data-consul-consul-server-0 --namespace consul

$ consul-k8s uninstall -auto-approve -wipe-data && kubectl delete pvc/data-consul-consul-server-0 --namespace consul

Terminate you local Kubernetes cluster.

$ minikube delete --all

$ minikube delete --all

»Next steps

In this tutorial, you configured Consul service mesh on an existing Kubernetes cluster using the official Helm chart. You also deployed an example application to explore the service topology and track requests.

For a detailed explanation of Consul service mesh, review our tutorial explaining its design and features.

Learn more about using Consul on Kubernetes in the following tutorials:

Infrastructure

Security

Applications

Networking

cloud