Getting Started with Consul Service Mesh for Kubernetes

15min
Consul

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 v1.0.2

Clone the Demo Configuration and Application

The learn-consul-service-mesh-deploy 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-education/learn-consul-service-mesh-deploy.git

Change to the repository directory, which contains all of the artifacts used in this tutorial.

$ cd learn-consul-service-mesh-deploy

Deploy Consul

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...
## ...
Update Complete. ⎈Happy Helming!⎈

Deploy the Consul Helm chart using the values in consul-values.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 consul-values.yaml consul hashicorp/consul --create-namespace -n consul --version 1.0.2
NAME: consul
## ...
  $ 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-connect-injector-7f9d65c66b-tspzl       1/1     Running   1             17h
consul-server-0                                1/1     Running   0             17h
consul-webhook-cert-manager-6b787686d5-89xxk   1/1     Running   0             17h

The Consul K8s tool automatically implements the official Helm chart during installation. First, make sure you have the correct version installed.

$ consul-k8s version
    consul-k8s v1.0.2

Next, issue the consul-k8s install command and specify the project configuration file with the -config-file to deploy Consul:

$ consul-k8s install -config-file consul-values.yaml

==> Pre-Install Checks
 ✓ No existing installations found
 ✓ No previous persistent volume claims found
 ✓ No previous secrets found

==> Consul Installation Summary
    Name: consul
    Namespace: consul

    Helm value overrides
    --------------------
    connectInject:
      default: true
      enabled: true
      metrics:
        defaultEnableMerging: true
        defaultEnabled: true
        defaultMergedMetricsPort: 20100
        defaultPrometheusScrapePath: /metrics
        defaultPrometheusScrapePort: 20200
    controller:
      enabled: true
    global:
      datacenter: dc1
      image: hashicorp/consul:1.14.2
      imageK8S: hashicorp/consul-k8s-control-plane:1.0.2
      metrics:
        agentMetricsRetentionTime: 1m
        enableAgentMetrics: true
        enabled: true
      name: consul
    prometheus:
      enabled: true
    server:
      replicas: 1
    ui:
      enabled: true
      metrics:
        baseURL: http://prometheus-server
        enabled: true
        provider: prometheus

Proceed with installation? (y/N) y

Confirm that you want to proceed with the installation when prompted.

Tip

You can use the -auto-approve flag when issuing the install command to bypass the confirmation prompt and proceed with the installation.

Details about the installation will be printed to the terminal:

==> Installing Consul
 ✓ Downloaded charts.
 --> creating 1 resource(s)
 --> checking 39 resources for changes

##...

 --> beginning wait for 39 resources with timeout of 10m0s
 --> StatefulSet is ready: consul/consul-server. 1 out of 1 expected pods are ready
 ✓ Consul installed in namespace "consul".

When the installation finishes, Consul will be deployed to the consul namespace. Validate the installation by checking for running Consul pods.

$ kubectl get pods --namespace consul
NAME                                           READY   STATUS    RESTARTS   AGE
consul-connect-injector-d4fc689d9-s7pbs        1/1     Running   0          105s
consul-server-0                                1/1     Running   0          105s
consul-webhook-cert-manager-6b787686d5-wgvbv   1/1     Running   0          105s
prometheus-server-8fd7967f5-l6n2z              2/2     Running   0          105s

If the installation fails, delete the existing artifacts and retry the command. Follow the instructions for uninstalling Consul in the documentation for additional information.

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

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

consul ui showing services tab with consul

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.14.2  2         dc1  default    <all>

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.

Tip

If you are using Docker Desktop and the demo application fails to launch, the reason may be that the default resource limits for containers are set too low. We recommend setting the RAM to 4GB or more and CPUs to 4 or more.

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

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

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

hashicups demo app front page

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

consul ui showing hashicups services registered as healthy

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.

consul ui showing topology and graph for requests to product api

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/
```

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
```

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: