Book a 90-minute product workshop led by HashiCorp engineers and product experts during HashiConf Digital Reserve your spot

Getting Started with Consul Service Mesh

Deploy Consul Service Mesh on Kubernetes

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

By the end of this guide, 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 guide is not for production use. By default, the chart will install an insecure configuration of Consul. Please refer to the Kubernetes documentation to determine how you can secure Consul on Kubernetes in production. Additionally, it is highly recommended to use a properly secured Kubernetes cluster or make sure that you understand and enable the recommended security features.


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

»Configure kubectl to talk to your cluster

At the end of the Kubernetes cluster creation process, Shipyard creates a kubectl configuration file in your home directory, ~/.shipyard/config/k8s/kubeconfig.yaml. This file configures your kubectl command line tool to communicate with your Kubernetes cluster.

To use the Shipyard generated configuration, define the KUBECONFIG environment variable to locate that file.

$ export KUBECONFIG="$HOME/.shipyard/config/k8s/kubeconfig.yaml"

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            metrics-server-6d684c7b5-86mn5               1/1     Running   0          119s
kube-system            local-path-provisioner-58fb86bdfd-6v7s5      1/1     Running   0          119s
kube-system            coredns-d798c9dd-t6gxx                       1/1     Running   0          119s
kubernetes-dashboard   dashboard-metrics-scraper-566cddb686-chxwz   1/1     Running   0          36s
kubernetes-dashboard   kubernetes-dashboard-77f85889d5-n69wr        1/1     Running   0          36s

»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, 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.
    • Consul to Kubernetes. Consul services will be synced to Kubernetes services 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.
  • 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.

Using the blueprint for Shipyard you can use the helm-charts folder inside the blueprint folder. The blueprint you are using for this guide ships with consul-helm-0.18.0 so you can deploy Consul using that chart version out-of-the-box.

The Helm chart resides in the blueprints folder in your Shipyard configuration directory.

$ cd ~/.shipyard/blueprints/

»Configure the Helm chart

The Helm chart directory contains a values.yaml file with default configuration values. For this guide you will override these values by creating your own consul-values.yml file and passing it to helm install with the -f flag, e.g. helm install hashicorp ./consul-helm -f consul-values.yml.

The Shipyard blueprint provides a sample configuration file located at helm-charts/consul-values.yml. In this guide you will use this file to provision Consul as your Kubernetes service mesh, however you should consider your particular production needs when configuring your chart for production environments.

$ cat consul-values.yml
  domain: consul
  datacenter: hashidc1
  image: "consul:1.7.0"

  replicas: 1
  bootstrapExpect: 1
  storage: 64Mi
  storageClass: local-path

  enabled: true
  grpc: true

  enabled: true

  enabled: true
  imageEnvoy: envoyproxy/envoy:v1.13.1

You can find additional details on the different sections configured in the sections below.

»Global configuration

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

  • image is the name and tag of the Consul Docker image.
  • datacenter is the name of your Consul datacenter.
  • domain is the domain Consul uses for DNS queries.

»Server and client configuration

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

The blueprint used for this guide creates a single node Kubernetes cluster so the configuration creates one replica and sets bootstrapExpect :1. The other two keys in the default configuration storage and storageClass help you define the storage resources assigned to the server instances.

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.

»Consul connectInject security configuration

You can enable the Consul “connect” service mesh by setting the connectInject key to true.

When the “connect” injector is installed, then a sidecar proxy is automatically added to all pods. This sidecar can both accept and establish connections using Consul, enabling the pod to communicate to clients and dependencies exclusively over authorized and encrypted connections.

»Deploy Consul service mesh

You will use helm install to deploy Consul using the configuration defined in consul-values.yml. This should only take a few minutes. The Consul pods should appear in the Kubernetes dashboard immediately and you can monitor the deployment process there.

$ helm install hashicorp ./consul-helm-0.18.0 -f consul-values.yml
NAME: hashicorp
## ... 
NAMESPACE: default
STATUS: deployed
Thank you for installing HashiCorp Consul!

Now that you have deployed Consul, you should look over the docs on using
Consul with Kubernetes available here:

Your release is named hashicorp. To learn more about the release, try:

  $ helm status hashicorp
  $ helm get hashicorp

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 see which services are being exposed from the Kubernetes cluster.

$ kubectl get services
NAME                                    TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                                                                   AGE
kubernetes                              ClusterIP     <none>        443/TCP                                                                   22m
hashicorp-consul-server                 ClusterIP   None          <none>        8500/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP   15m
hashicorp-consul-connect-injector-svc   ClusterIP   <none>        443/TCP                                                                   15m
hashicorp-consul-dns                    ClusterIP    <none>        53/TCP,53/UDP                                                             15m
hashicorp-consul-ui                     ClusterIP   <none>        80/TCP                                                                    15m

»Interact with Consul service mesh

Kubernetes requires you to create an ingress in order to access services from outside the cluster. An ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster.

Ingresses can be created using several different ingress controllers to manage the traffic. An example file for this guide is provided by the blueprint in the ingress_config folder.

This configuration creates an ingress that permits you to access the svc/hashicorp-consul-ui service in Kubernetes listening on port 80 using port 18500 on your local machine at http://localhost:18500.

$ cd ~/.shipyard/blueprints/
$ cat consul-ui.hcl
ingress "consul-ui" {
  target = "k8s_cluster.k8s"
  service  = "svc/hashicorp-consul-ui"
  network  {
    name = "network.local"

  port {
    local  = 80
    remote = 80
    host   = 18500

Use shipyard run to apply the ingress to your Kubernetes cluster.

$ shipyard run ./consul-ui.hcl
Running configuration from:  ./blueprints/consul-base-lab/ingresses/consul-ui.hcl

2020-02-20T15:19:04.386+0100 [INFO]  Creating Ingress: ref=consul-ui
2020-02-20T15:19:04.389+0100 [DEBUG] Image exists in local cache: image=shipyardrun/ingress:latest
2020-02-20T15:19:04.389+0100 [INFO]  Creating Container: ref=consul-ui
2020-02-20T15:19:04.420+0100 [DEBUG] Attaching container to network: ref=consul-ui network=network.local

Once the command completes, use docker ps to verify the ingress is running.

$ docker ps
CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS              PORTS                      NAMES
2cfd74201e82        shipyardrun/ingress:latest   "ingress --proxy-typ…"   18 seconds ago      Up 17 seconds>80/tcp      consul-ui.ingress.shipyard
## ...

»Access Consul UI

Once the Shipyard ingress is created the Consul UI is 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 hashicorp-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
hashicorp-consul-server-0  alive   server  1.7.0  2         hashidc1  <all>
server.k8s          alive   client  1.7.0  2         hashidc1  <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 guide.

$ 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
hashicorp-consul-server-0  alive   server  1.7.0  2         hashidc1  <all>
server.k8s          alive   client  1.7.0  2         hashidc1  <default>

»Next steps

In this guide you configured Consul “connect” service mesh on an existing Kubernetes cluster using the official Helm chart. You enabled the UI and configured an ingress to access it. Finally, you used kubectl to interact with your service mesh.

In the next guide you will learn how to deploy “connect” enabled services on Kubernetes using Envoy as sidecar proxy.