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.
The following components are required to complete this tutorial:
- A local Kubernetes cluster. Popular options for starting clusters include Minikube, kind, and k3s. This tutorial uses Minikube.
- Consul K8s CLI
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
Change to the
/service-mesh/deploy directory, which contains all of the artifacts used in this tutorial.
$ cd learn-consul-kubernetes/service-mesh/deploy
First, start a Kubernetes cluster.
$ 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
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!⎈
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
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
To access the Consul UI, set up port forwarding to port
$ 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>
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/
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
You can now explore the demo application and how it uses Consul service mesh.
nginx service to port
$ 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.
products-api service. The Topology tab indicates that requests to
public-api goes to the
product-api before accessing the database.
Consul embeds a graph aggregating successful requests and error metrics.
After you complete this tutorial, you can stop Consul, the demo application, and the Kubernetes cluster.
Remove all HashiCups resources.
$ 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
Terminate you local Kubernetes cluster.
$ minikube delete --all
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: