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.
- 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
.
- 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
»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 consul-values.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 > consul-values.yaml <<EOF
global:
domain: consul
datacenter: dc1
server:
replicas: 1
bootstrapExpect: 1
client:
enabled: true
grpc: true
ui:
enabled: true
connectInject:
enabled: true
controller:
enabled: true
EOF
Before you install Consul with the 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 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.
Whether you used Minikube or kind
, the cluster creation command for this tutorial
creates a single node Kubernetes cluster so the Consul configuration creates one
replica
and sets bootstrapExpect :1
.
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 connectInject security configuration
You can enable the Consul service mesh by setting the connectInject
key to true.
When the injector is installed, then a sidecar proxy is automatically added to all pods. This sidecar can both accept and establish connections using Consul, thus enabling the pod to communicate with 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 Kubernetes immediately and you can monitor the deployment process using
kubectl.
$ helm install -f consul-values.yml hashicorp hashicorp/consul
NAME: hashicorp
...TRUNCATED...
$ 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 get a list of
services running in the Kubernetes cluster.
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.43.0.1 443/TCP 22m
hashicorp-consul-server ClusterIP None 8500/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP 15m
hashicorp-consul-connect-injector-svc ClusterIP 10.43.2.103 443/TCP 15m
hashicorp-consul-dns ClusterIP 10.43.22.2 53/TCP,53/UDP 15m
hashicorp-consul-ui ClusterIP 10.43.85.85 80/TCP 15m
»Interact with Consul service mesh
To access the Consul UI you will setup port forwarding.
$ kubectl port-forward service/hashicorp-consul-ui 18500:80 --address 0.0.0.0
This will forward port 80
from service/hashicorp-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.
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
Example output:
Node Address Status Type Build Protocol DC Segment
hashicorp-consul-server-0 172.17.0.5:8301 alive server 1.8.2 2 dc1
minikube 172.17.0.3:8301 alive client 1.8.2 2 dc1
»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
Example output:
Node Address Status Type Build Protocol DC Segment
hashicorp-consul-server-0 172.17.0.5:8301 alive server 1.8.2 2 dc1
minikube 172.17.0.3:8301 alive client 1.8.2 2 dc1
»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.