This tutorial installs and configures Consul service mesh on an existing 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 workload.
»Prerequisites
Check that you have access to a Kubernetes cluster. You can deploy one locally using kind or Minikube.
Validate you have kubectl installed.
$ kubectl version --short
Client Version: v1.19.7
Server Version: v1.20.2
Validate you have helm installed.
$ helm version --short
v3.5.3+g041ce5a
Clone the demo configuration and application.
$ git clone https://github.com/hashicorp/learn-consul-kubernetes.git
Change directory to use the demo configuration and application.
$ cd learn-consul-kubernetes/service-mesh/deploy
»Deploy Consul
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 deploys the
control plane for the service mesh, which includes a Consul server,
client, controller, and injector. It also installs a demo instance of
Prometheus and Grafana for metrics.
$ helm install -f config.yaml consul hashicorp/consul --version "0.31.1"
NAME: consul
...TRUNCATED...
$ helm status consul
$ helm get all consul
Validate the installation by checking for running Consul pods.
$ kubectl get pods --selector app=consul
NAME READY STATUS RESTARTS AGE
consul-8pdzr 1/1 Running 0 3m41s
consul-connect-injector-webhook-deployment-5c857b8d5f-q5g5s 1/1 Running 0 3m41s
consul-controller-5788b8f6c7-qhlmd 1/1 Running 0 3m41s
consul-server-0 1/1 Running 0 3m30s
consul-webhook-cert-manager-5745cbb9d-kh74m 1/1 Running 0 3m41s
»Interact with Consul
To access the Consul UI, set up port forwarding to port 18500.
$ kubectl port-forward service/consul-ui 18500:80 --address 0.0.0.0
Then, go to http://localhost:18500 in your browser. Explore the Consul UI by examining 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 -- consul members
Node Address Status Type Build Protocol DC Segment
consul-server-0 172.17.0.9:8301 alive server 1.9.4 2 dc1 <all>
minikube 172.17.0.8:8301 alive client 1.9.4 2 dc1 <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 three 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-6f548678bb-tmjmn 3/3 Running 0 11m
postgres-7847fc4696-ljswz 3/3 Running 0 11m
product-api-7f45c88999-687t5 3/3 Running 0 11m
public-api-7bb69fcfd6-vn27f 3/3 Running 0 11m
»Explore the application
You can now explore the demo application and how it uses Consul service mesh.
Forward the frontend service to port 18080.
$ kubectl port-forward service/frontend 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:18500. You'll find the HashiCups services registered to Consul service mesh with proxies.
Select the product-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.
»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:
