In this tutorial, you will start a local Kubernetes cluster using minikube
. You will then deploy Consul with the official Helm chart or the Consul K8S CLI. After deploying Consul, you will learn how to access the agents. You will then deploy two services that use Consul to discover each other.
Security Warning This tutorial is not for production use. By default, the chart will install an insecure configuration of Consul. Please refer to the Kubernetes deployment guide 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.
ยปPrerequisites
First, you will need to follow the directions for installing Minikube.
You'll also need to install kubectl
and helm
.
Install kubectl
with Homebrew.
Install helm
with Homebrew.
ยปStart Minikube
Start Minikube with the optional --memory
flag specifying the equivalent of 4-8GB of memory, so your pods will have plenty of resources to use. Starting Minikube may take several minutes. It will download a 100-300MB of dependencies and container images.
The output will be similar to the following.
Note: minikube
does not ship with the kubernetes dashboard by default. If, you wish to install the Kubernetes Dashboard, refer to the Kubernetes Dashboard project for instructions on how to install and view it.
ยปInstall Consul with the official Helm chart
Tip: You can deploy a complete Consul datacenter using the official Helm chart. You can review the official Helm chart values to learn more about the default settings.
ยปDeploy Consul
You can deploy a complete Consul datacenter using the official Consul Helm chart or the Consul K8S CLI. You can review the Consul Kubernetes installation documentation to learn more about these installation options.
ยปCreate a values file
To customize your deployment, you can pass a yaml file to be used during the deployment;
it will override the Helm chart's default values. The chart comes with reasonable defaults, however, you will override a few values to integrate more easily with minikube
and enable useful features.
Create a custom values file called helm-consul-values.yaml
with the
following contents. This configuration will:
- Set the prefix used for all resources in the Helm chart to
consul
- Name the Consul datacenter
dc1
- Configure the datacenter to run only 1 server
- Configure the server to use the
root
user - Enable the Consul UI and expose it via a
NodePort
- Enable Consul service mesh features by setting
connectInject.enabled
to true - Enable Consul service mesh CRDs by setting
controller.enabled
to true
- With Transparent Proxy
- Without Transparent Proxy
Note Transparent proxy is the default method for service to service communication within the service mesh since Consul 1.10. Check out the transparent proxy documentation to learn more.
ยปInstall Consul in your cluster
You can now deploy a complete Consul datacenter in your Kubernetes cluster using the official Consul Helm chart or the Consul K8S CLI.
ยปAccess the Consul UI
Verify Consul was deployed properly by accessing the Consul UI. Run minikube service list
to list your services. Find the one with consul-ui
in the name.
Run minikube service
with the consul-ui
service name as the argument. It will open the service in your web browser.
You can now visit the Consul UI with a list of Consul's services, nodes, and other resources. Currently, you should only find the consul
service listed.
ยปAccess Consul with kubectl and the HTTP API
In addition to accessing Consul with the UI, you can manage Consul with the
HTTP API or by directly connecting to the pod with kubectl
.
ยปKubectl
To access the pod and data directory, you can remote execute into the pod with the command kubectl
to start a shell session.
This will allow you to navigate the file system and run Consul CLI commands on the pod. For example you can view the Consul members.
When you have finished interacting with the pod, exit the shell.
ยปConsul HTTP API
You can use the Consul HTTP API by communicating with the local agent running on the Kubernetes node. Read the documentation to learn more about using the Consul HTTP API with Kubernetes.
ยปDeploy services with Kubernetes
Now that you have a running Consul service mesh, you can deploy services to it.
ยปDeploy two services
You will now deploy a two-tier application made of a backend data service that
returns a number (the counting
service), and a frontend dashboard
that pulls
from the counting
service over HTTP and displays the number.
Create a deployment definition, service, and service account for the counting
service named counting.yaml
.
- With Transparent Proxy
- Without Transparent Proxy
Create a deployment definition, service, and service account for
the dashboard
service named dashboard.yaml
.
- With Transparent Proxy
- Without Transparent Proxy
Use kubectl
to deploy the counting service.
Use kubectl
to deploy the dashboard service.
To verify the services were deployed, refresh the Consul UI until you observe
that the counting
and dashboard
services are running.
ยปVisit the dashboard
To visit the dashboard, forward the pod's port where the dashboard
service is running to your local machine on the same port by providing
the pod name (dashboard
), which you specified in the service definition YAML file.
Visit localhost:9002 in your web browser. It will display
the dashboard
UI with a number retrieved from the counting
service using
Consul service discovery.
ยปSecure service communication with intentions
Consul intentions provide you the ability to control which services are allowed
to communicate. Next, you will use intentions to test the communication between
the dashboard
and counting
services.
ยปCreate an intention that denies communication
You can use a Consul ServiceIntention
CRD to create an intention that prevents the dashboard
service from reaching
its upstream counting service
.
Create a file named deny.yaml
that denies communication between the two services.
Use kubectl
to apply the intention.
Verify the services are no longer allowed to communicate by returning to the dashboard UI. The service will display a message that the "Counting Service is Unreachable", and the count will display as "-1".
ยปAllow the application dashboard to communicate with the Counting service
Finally, remove the intention so that the services can communicate again.
Intentions take effect rather quickly. The next time you visit the dashboard
you'll notice that it's successfully communicating with the backend counting
service again.
ยปNext steps
To learn more about Consul service mesh on Kubernetes, review the service mesh tutorials. To learn how to deploy Consul on a Kubernetes cluster, review the production deployment tutorial. To learn how to secure Consul and services for production, read the Secure Consul and Registered Services on Kubernetes tutorial.