Deploy Consul Service Mesh on Kubernetes | Consul

This tutorial covers the necessary steps to install and configure Consul service mesh on an existing Kubernetes cluster.

By the end of this tutorial, you will be able to identify the installation prerequisites, download and configure the official Helm chart for Consul, and deploy Consul service mesh in your Kubernetes cluster.

Security Warning: This tutorial is not for production use. By default, the chart will install an insecure configuration of Consul. Please refer to the the Secure Agents and Registered Services tutorial to determine how you can secure Consul on Kubernetes in production. It is highly recommended that you understand and enable the recommended security features.

»Prerequisites

Kubernetes cluster. In the previous tutorial, Understand Consul Service Mesh, you used kind or Minikube to create a Kubernetes cluster locally on your local development machine. You can use that cluster to test the commands provided in this tutorial.

To complete this tutorial you will need:

Helm installed locally to deploy your Consul service mesh.
kubectl installed locally to interact with your Kubernetes cluster and deploy services.

NOTE: A similar, Minikube based interactive hands-on lab is also available if you do not have a Consul environment to perform the steps described in this tutorial. Click the Show Tutorial button to launch the lab experience.

»Configure kubectl to talk to your cluster

At the end of the Kubernetes cluster creation process, minikube or kind created or modified the kubectl configuration file in your home directory, ~/.kube/config. This file configures your kubectl command line tool to communicate with your Kubernetes cluster.

The kubectl command should automatically find that configuration and connect to your Kubernetes cluster but, if for some reason that is not the case, you can set the KUBECONFIG environment variable to the path of that file, and kubectl should now be able to interact with your cluster.

$ export KUBECONFIG="$HOME/.kube/config"

Before continuing, you should test that the kubectl is configured to interact with your Kubernetes cluster by using kubectl get pods to query for pods.

$ kubectl get pods --all-namespaces

NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
kube-system   coredns-66bff467f8-vldj2           1/1     Running   0          42s
kube-system   etcd-minikube                      1/1     Running   0          48s
kube-system   kube-apiserver-minikube            1/1     Running   0          48s
kube-system   kube-controller-manager-minikube   1/1     Running   0          48s
kube-system   kube-proxy-cm78b                   1/1     Running   0          43s
kube-system   kube-scheduler-minikube            1/1     Running   0          48s
kube-system   storage-provisioner                1/1     Running   1          48s

»Get the official Helm chart

Consul offers first-class Kubernetes support by providing an official Helm chart. The chart helps you automate the installation and configuration of Consul’s core features for Kubernetes which are listed below.

Auto-join for Kubernetes. Consul's cloud auto-join feature supports discovering and joining Kubernetes-based agents. This enables external Consul agents in different datacenters to join a Consul datacenter running in Kubernetes.
Service Catalog Sync:
- Kubernetes to Consul: Kubernetes services will be automatically synced to the Consul catalog, enabling non-Kubernetes services to discover and connect to services running within Kubernetes. The Kubernetes services will be discoverable with the Consul UI, CLI, and API. We do not recommend setting syncCatalog.toConsul=true when connectInject.enabled=true because the sidecar lifecycle pod is already registering the service and its proxy into Consul.
- Consul to Kubernetes: Consul services will be automatically synced to the Kubernetes catalog so that applications can use Kubernetes-native service discovery to discover and connect to services running outside of Kubernetes. The non-Kubernetes services will be discoverable with the Kubernetes UI and kubectl. We do not recommend setting syncCatalog.toK8S=true when connectInject.enabled=true because if you have a service in front of your Consul inject pods, then that service will be synced to Consul by the syncCatalog process, potentially overwriting the registration that was created by the injector. This situation could happen if your Consul service and your Kubernetes service have the same name.
Connect Auto-Inject. Pods deployed in Kubernetes can be configured to automatically use Consul to securely communicate using mutual TLS.

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!⎈

»Configure the Helm chart

The Helm chart repository contains a values.yaml file that illustrates all possible configuration values. For this tutorial, you will create your own config.yaml file and pass it to helm install with the -f flag.

You can use the example below to provision Consul as your Kubernetes service mesh; however, you should consider your particular production needs when configuring your chart for production environments.

$ cat > config.yaml <<EOF
global:
  name: consul
  datacenter: dc1
  metrics:
    enabled: true
    enableAgentMetrics: true

server:
  replicas: 1

ui:
  enabled: true

connectInject:
  enabled: true
  default: true
  metrics:
      defaultEnableMerging: true

controller:
  enabled: true

prometheus:
  enabled: true

grafana:
  enabled: true
EOF

Before you install Consul with your values file, review these additional details on the different configuration options contained in the file.

»Global configuration

The values under the global key will affect all the other parameters in the chart.

datacenter is the name of your Consul datacenter.
domain is the domain Consul uses for DNS queries.

»Server configuration

The server key contains parameters related to the server pods. The chart is configured to create one Consul server per Kubernetes node.

A Consul client is deployed on every Kubernetes node, so you do not need to specify the number of clients for your deployments. However, you will need to specify resources.

»Consul UI configuration

To enable the Consul web UI, update the ui section and set enabled to true.

Note: You can also set up a LoadBalancer resource or other service type in Kubernetes to make it easier to access the UI. Refer to the helm chart values file for specific instructions.

»Consul service mesh configuration

You can enable the Consul service mesh by setting the connectInject.enabled key to true. When the injector is enabled, Envoy and Consul sidecars are automatically added to all pods. These sidecars work together to provide mesh features such as service discovery, health checking, load balancing, service registration, and all enabled security controls.

»Consul custom resource definitions

When set to true, the controller.enabled setting installs the Consul custom resource controller. This controller extends the Kubernetes API, and allows you to manage your Consul resources as if they were native resources using kubectl with YAML manifests just like you would for any built in Kubernetes API type.

»Consul observability

When set to true, the prometheus.enabled flag instructs the Consul Helm chart to install a demo Prometheus instance into your service mesh. Similarly, setting grafana.enabled to true will install a demo Grafana instance. By setting the global.metrics.enabled, global.metrics.enableAgentMetrics, and connectInject.metrics.defaultEnableMerging values to true, your Consul service mesh will be configured to collect Consul agent, Envoy proxy, Consul gateway, and registered service metrics by default.

»Deploy Consul service mesh

You will use helm install to deploy Consul using the configuration defined in config.yaml. This should only take a few minutes. The Consul pods should appear in Kubernetes immediately, and you can monitor the deployment process using kubectl.

$ helm install -f config.yaml consul hashicorp/consul --version "0.31.1"
NAME: consul
...TRUNCATED...
  $ helm status consul
  $ helm get all consul

To check the deployment process on the command line you can use kubectl get pods --all-namespaces to get the list of pods created or use kubectl get services to get a list of services running in the Kubernetes cluster.

$ kubectl get services

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                   AGE
consul-connect-injector-svc   ClusterIP   10.96.114.127           443/TCP                                                                   30s
consul-controller-webhook     ClusterIP   10.96.191.179           443/TCP                                                                   30s
consul-dns                    ClusterIP   10.96.19.194            53/TCP,53/UDP                                                             30s
consul-server                 ClusterIP   None                    8500/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP   30s
consul-ui                     ClusterIP   10.96.32.31             80/TCP                                                                    30s
grafana                       ClusterIP   10.96.65.6              3000/TCP                                                                  30s
kubernetes                    ClusterIP   10.96.0.1               443/TCP                                                                   3m3s
prometheus-server             ClusterIP   10.96.132.215           80/TCP                                                                    30s

»Interact with Consul service mesh

To access the Consul UI you will set up port forwarding.

$ kubectl port-forward service/consul-ui 18500:80 --address 0.0.0.0

This will forward port 80 from service/consul-ui at port 18500 to your development machine.

»Access Consul UI

Once access is configured, the Consul UI will be available at http://localhost:18500.

consul ui showing nodes tab with consul server and k8s

Explore the Consul UI by viewing the nodes and services tabs.

»Access Consul containers

You can use kubectl exec to get direct access to any container, including Consul containers.

$ kubectl exec -it consul-server-0 -- /bin/sh
/#

Once you have access to one of the Consul agents, use the consul command to interact with your datacenter.

$ consul members
Node               Address           Status  Type    Build        Protocol  DC   Segment
consul-server-0    10.244.0.11:8301  alive   server  1.10.0alpha  2         dc1  <all>
dc1-control-plane  10.244.0.5:8301   alive   client  1.10.0alpha  2         dc1  <default>

»Using Consul environment variable

If you have the consul binary installed on your test machine, you can interact with the datacenter directly.

Set the CONSUL_HTTP_ADDR to point to the ingress you created earlier in the tutorial.

$ export CONSUL_HTTP_ADDR="http://localhost:18500"

You can now use the consul command locally to interact with your datacenter.

$ consul members
Node               Address           Status  Type    Build        Protocol  DC   Segment
consul-server-0    10.244.0.11:8301  alive   server  1.10.0alpha  2         dc1  <all>
dc1-control-plane  10.244.0.5:8301   alive   client  1.10.0alpha  2         dc1  <default>

»Next steps

In this tutorial, you configured Consul Connect service mesh on an existing Kubernetes cluster using the official Helm chart. You enabled the UI and enabled external access to the service. Finally, you used kubectl to interact with your service mesh.

In the next tutorial, Secure Applications with Consul Service Mesh, you will learn how to deploy Connect service mesh enabled services on Kubernetes using Envoy as sidecar proxy.

Infrastructure

Security

Networking

Applications