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.

Minikube - 图1

Minikube - 图2

Install kubectl with Homebrew.

  1. $ brew install kubernetes-cli
  1. $ brew install kubernetes-cli

Install helm with Homebrew.

  1. $ brew install kubernetes-helm
  1. $ brew install kubernetes-helm

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.

  1. $ minikube start --memory 4096
  1. $ minikube start --memory 4096

The output will be similar to the following.

  1. 😄  minikube v1.16.0 on Darwin 10.15.7
  2. 🎉  minikube 1.25.1 is available! Download it: https://github.com/kubernetes/minikube/releases/tag/v1.25.1
  3. 💡  To disable this notice, run: 'minikube config set WantUpdateNotification false'
  5. ✨  Automatically selected the docker driver. Other choices: hyperkit, virtualbox
  6. 👍  Starting control plane node minikube in cluster minikube
  7. 🔥  Creating docker container (CPUs=2, Memory=4096MB) ...
  8. 🐳  Preparing Kubernetes v1.20.0 on Docker 20.10.0 ...
  9.     ▪ Generating certificates and keys ...
  10.     ▪ Booting up control plane ...
  11.     ▪ Configuring RBAC rules ...
  12. 🔎  Verifying Kubernetes components...
  13. 🌟  Enabled addons: storage-provisioner, default-storageclass
  14. 🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
  1. 😄  minikube v1.16.0 on Darwin 10.15.7
  2. 🎉  minikube 1.25.1 is available! Download it: https://github.com/kubernetes/minikube/releases/tag/v1.25.1
  3. 💡  To disable this notice, run: 'minikube config set WantUpdateNotification false'
  5. ✨  Automatically selected the docker driver. Other choices: hyperkit, virtualbox
  6. 👍  Starting control plane node minikube in cluster minikube
  7. 🔥  Creating docker container (CPUs=2, Memory=4096MB) ...
  8. 🐳  Preparing Kubernetes v1.20.0 on Docker 20.10.0 ...
  9.     ▪ Generating certificates and keys ...
  10.     ▪ Booting up control plane ...
  11.     ▪ Configuring RBAC rules ...
  12. 🔎  Verifying Kubernetes components...
  13. 🌟  Enabled addons: storage-provisioner, default-storageclass
  14. 🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

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

Minikube - 图3

  • With Transparent Proxy
  • Without Transparent Proxy
  1. $ cat > helm-consul-values.yaml <<EOF
  2. global:
  3.   name: consul
  4.   datacenter: dc1
  5. server:
  6.   replicas: 1
  7.   securityContext:
  8.     runAsNonRoot: false
  9.     runAsGroup: 0
  10.     runAsUser: 0
  11.     fsGroup: 0
  12. ui:
  13.   enabled: true
  14.   service:
  15.     type: 'NodePort'
  16. connectInject:
  17.   enabled: true
  18. controller:
  19.   enabled: true
  20. EOF
  1. $ cat > helm-consul-values.yaml <<EOF
  2. global:
  3.   name: consul
  4.   datacenter: dc1
  5. server:
  6.   replicas: 1
  7.   securityContext:
  8.     runAsNonRoot: false
  9.     runAsGroup: 0
  10.     runAsUser: 0
  11.     fsGroup: 0
  12. ui:
  13.   enabled: true
  14.   service:
  15.     type: 'NodePort'
  16. connectInject:
  17.   enabled: true
  18. controller:
  19.   enabled: true
  20. EOF
  1. $ cat > helm-consul-values.yaml <<EOF
  2. global:
  3.   name: consul
  4.   datacenter: dc1
  5. server:
  6.   replicas: 1
  7.   securityContext:
  8.     runAsNonRoot: false
  9.     runAsGroup: 0
  10.     runAsUser: 0
  11.     fsGroup: 0
  12. ui:
  13.   enabled: true
  14.   service:
  15.     type: 'NodePort'
  16. connectInject:
  17.   enabled: true
  18.   transparentProxy:
  19.     defaultEnabled: false
  20. controller:
  21.   enabled: true
  22. EOF
  1. 1 2 3 4 5 6 7 8 9 10111213141516171819202122$ cat > helm-consul-values.yaml <<EOF
  2. global:
  3.   name: consul
  4.   datacenter: dc1
  5. server:
  6.   replicas: 1
  7.   securityContext:
  8.     runAsNonRoot: false
  9.     runAsGroup: 0
  10.     runAsUser: 0
  11.     fsGroup: 0
  12. ui:
  13.   enabled: true
  14.   service:
  15.     type: 'NodePort'
  16. connectInject:
  17.   enabled: true
  18.   transparentProxy:
  19.     defaultEnabled: false
  20. controller:
  21.   enabled: true
  22. EOF

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.

Minikube - 图4

Minikube - 图5

  1. $ helm repo add hashicorp https://helm.releases.hashicorp.com
  2. "hashicorp" has been added to your repositories
  1. $ helm repo add hashicorp https://helm.releases.hashicorp.com
  2. "hashicorp" has been added to your repositories
  1. $ helm install --values helm-consul-values.yaml consul hashicorp/consul --create-namespace --namespace consul --version "0.43.0"
  1. $ helm install --values helm-consul-values.yaml consul hashicorp/consul --create-namespace --namespace consul --version "0.43.0"

Note: You can review the official Helm chart values to learn more about the default settings.

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.

  1. $ minikube service list
  2. |-------------|---------------------------|--------------|-----|
  3. |  NAMESPACE  |           NAME            | TARGET PORT  | URL |
  4. |-------------|---------------------------|--------------|-----|
  5. | default     | consul-connect-injector   | No node port |
  6. | default     | consul-controller-webhook | No node port |
  7. | default     | consul-dns                | No node port |
  8. | default     | consul-server             | No node port |
  9. | default     | consul-ui                 | http/80      |     |
  10. | default     | kubernetes                | No node port |
  11. | kube-system | kube-dns                  | No node port |
  12. |-------------|---------------------------|--------------|-----|
  1. $ minikube service list
  2. |-------------|---------------------------|--------------|-----|
  3. |  NAMESPACE  |           NAME            | TARGET PORT  | URL |
  4. |-------------|---------------------------|--------------|-----|
  5. | default     | consul-connect-injector   | No node port |
  6. | default     | consul-controller-webhook | No node port |
  7. | default     | consul-dns                | No node port |
  8. | default     | consul-server             | No node port |
  9. | default     | consul-ui                 | http/80      |     |
  10. | default     | kubernetes                | No node port |
  11. | kube-system | kube-dns                  | No node port |
  12. |-------------|---------------------------|--------------|-----|

Run minikube service with the consul-ui service name as the argument. It will open the service in your web browser.

  1. $ minikube service consul-ui
  1. $ minikube service consul-ui

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.

Minikube Consul UI

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.

  1. $ kubectl exec --stdin --tty consul-server-0 --namespace consul -- /bin/sh
  1. $ kubectl exec --stdin --tty consul-server-0 --namespace consul -- /bin/sh

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.

  1. $ consul members
  2. Node             Address          Status  Type    Build   Protocol  DC   Partition  Segment
  3. consul-server-0  172.17.0.8:8301  alive   server  1.11.2  2         dc1  default    <all>
  4. minikube         172.17.0.4:8301  alive   client  1.11.2  2         dc1  default    <default>
  1. $ consul members
  2. Node             Address          Status  Type    Build   Protocol  DC   Partition  Segment
  3. consul-server-0  172.17.0.8:8301  alive   server  1.11.2  2         dc1  default    <all>
  4. minikube         172.17.0.4:8301  alive   client  1.11.2  2         dc1  default    <default>

When you have finished interacting with the pod, exit the shell.

  1. $ exit
  1. $ exit

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

Minikube - 图7

  • With Transparent Proxy
  • Without Transparent Proxy
  1. $ cat > counting.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: counting
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: counting
  11. spec:
  12.   selector:
  13.     app: counting
  14.   ports:
  15.   - port: 9001
  16.     targetPort: 9001
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: counting
  23.   name: counting
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: counting
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: counting
  35.     spec:
  36.       containers:
  37.       - name: counting
  38.         image: hashicorp/counting-service:0.0.2
  39.         ports:
  40.         - containerPort: 9001
  41. EOF
  1. $ cat > counting.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: counting
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: counting
  11. spec:
  12.   selector:
  13.     app: counting
  14.   ports:
  15.   - port: 9001
  16.     targetPort: 9001
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: counting
  23.   name: counting
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: counting
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: counting
  35.     spec:
  36.       containers:
  37.       - name: counting
  38.         image: hashicorp/counting-service:0.0.2
  39.         ports:
  40.         - containerPort: 9001
  41. EOF
  1. $ cat > counting.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: counting
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: counting
  11. spec:
  12.   selector:
  13.     app: counting
  14.   ports:
  15.   - port: 9001
  16.     targetPort: 9001
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: counting
  23.   name: counting
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: counting
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: counting
  35.     spec:
  36.       containers:
  37.       - name: counting
  38.         image: hashicorp/counting-service:0.0.2
  39.         ports:
  40.         - containerPort: 9001
  41. EOF
  1. $ cat > counting.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: counting
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: counting
  11. spec:
  12.   selector:
  13.     app: counting
  14.   ports:
  15.   - port: 9001
  16.     targetPort: 9001
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: counting
  23.   name: counting
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: counting
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: counting
  35.     spec:
  36.       containers:
  37.       - name: counting
  38.         image: hashicorp/counting-service:0.0.2
  39.         ports:
  40.         - containerPort: 9001
  41. EOF

Create a deployment definition, service, and service account for the dashboard service named dashboard.yaml.

With Transparent Proxy

Minikube - 图8

  • With Transparent Proxy
  • Without Transparent Proxy
  1. $ cat > dashboard.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: dashboard
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: dashboard
  11. spec:
  12.   selector:
  13.     app: dashboard
  14.   ports:
  15.   - port: 9002
  16.     targetPort: 9002
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: dashboard
  23.   name: dashboard
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: dashboard
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: dashboard
  35.     spec:
  36.       containers:
  37.       - name: dashboard
  38.         image: hashicorp/dashboard-service:0.0.4
  39.         ports:
  40.         - containerPort: 9002
  41.         env:
  42.         - name: COUNTING_SERVICE_URL
  43.           value: 'http://counting:9001'
  44. EOF
  1. $ cat > dashboard.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: dashboard
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: dashboard
  11. spec:
  12.   selector:
  13.     app: dashboard
  14.   ports:
  15.   - port: 9002
  16.     targetPort: 9002
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: dashboard
  23.   name: dashboard
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: dashboard
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.       labels:
  34.         app: dashboard
  35.     spec:
  36.       containers:
  37.       - name: dashboard
  38.         image: hashicorp/dashboard-service:0.0.4
  39.         ports:
  40.         - containerPort: 9002
  41.         env:
  42.         - name: COUNTING_SERVICE_URL
  43.           value: 'http://counting:9001'
  44. EOF
  1. $ cat > dashboard.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: dashboard
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: dashboard
  11. spec:
  12.   selector:
  13.     app: dashboard
  14.   ports:
  15.   - port: 9002
  16.     targetPort: 9002
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: dashboard
  23.   name: dashboard
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: dashboard
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.         'consul.hashicorp.com/connect-service-upstreams': 'counting:9001'
  34.       labels:
  35.         app: dashboard
  36.     spec:
  37.       containers:
  38.       - name: dashboard
  39.         image: hashicorp/dashboard-service:0.0.4
  40.         ports:
  41.         - containerPort: 9002
  42.         env:
  43.         - name: COUNTING_SERVICE_URL
  44.           value: 'http://localhost:9001'
  45. EOF
  1. 1 2 3 4 5 6 7 8 9 101112131415161718192021222324252627282930313233343536373839404142434445$ cat > dashboard.yaml <<EOF
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5.   name: dashboard
  6. ---
  7. apiVersion: v1
  8. kind: Service
  9. metadata:
  10.   name: dashboard
  11. spec:
  12.   selector:
  13.     app: dashboard
  14.   ports:
  15.   - port: 9002
  16.     targetPort: 9002
  17. ---
  18. apiVersion: apps/v1
  19. kind: Deployment
  20. metadata:
  21.   labels:
  22.     app: dashboard
  23.   name: dashboard
  24. spec:
  25.   replicas: 1
  26.   selector:
  27.     matchLabels:
  28.       app: dashboard
  29.   template:
  30.     metadata:
  31.       annotations:
  32.         'consul.hashicorp.com/connect-inject': 'true'
  33.         'consul.hashicorp.com/connect-service-upstreams': 'counting:9001'
  34.       labels:
  35.         app: dashboard
  36.     spec:
  37.       containers:
  38.       - name: dashboard
  39.         image: hashicorp/dashboard-service:0.0.4
  40.         ports:
  41.         - containerPort: 9002
  42.         env:
  43.         - name: COUNTING_SERVICE_URL
  44.           value: 'http://localhost:9001'
  45. EOF

Use kubectl to deploy the counting service.

  1. $ kubectl apply -f counting.yaml
  2. serviceaccount/counting created
  3. service/counting created
  4. deployment.apps/counting created
  1. $ kubectl apply -f counting.yaml
  2. serviceaccount/counting created
  3. service/counting created
  4. deployment.apps/counting created

Use kubectl to deploy the dashboard service.

  1. $ kubectl apply -f dashboard.yaml
  2. serviceaccount/dashboard created
  3. service/dashboard created
  4. deployment.apps/dashboard created
  1. $ kubectl apply -f dashboard.yaml
  2. serviceaccount/dashboard created
  3. service/dashboard created
  4. deployment.apps/dashboard created

To verify the services were deployed, refresh the Consul UI until you observe that the counting and dashboard services are running.

Services

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.

  1. $ kubectl port-forward deploy/dashboard 9002:9002
  2. Forwarding from 127.0.0.1:9002 -> 9002
  3. Forwarding from [::1]:9002 -> 9002
  1. $ kubectl port-forward deploy/dashboard 9002:9002
  2. Forwarding from 127.0.0.1:9002 -> 9002
  3. Forwarding from [::1]:9002 -> 9002

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.

Application Dashboard

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.

  1. $ cat > deny.yaml <<EOF
  2. apiVersion: consul.hashicorp.com/v1alpha1
  3. kind: ServiceIntentions
  4. metadata:
  5.   name: dashboard-to-counting
  6. spec:
  7.   destination:
  8.     name: counting
  9.   sources:
  10.     - name: dashboard
  11.       action: deny
  12. EOF
  1. $ cat > deny.yaml <<EOF
  2. apiVersion: consul.hashicorp.com/v1alpha1
  3. kind: ServiceIntentions
  4. metadata:
  5.   name: dashboard-to-counting
  6. spec:
  7.   destination:
  8.     name: counting
  9.   sources:
  10.     - name: dashboard
  11.       action: deny
  12. EOF

Use kubectl to apply the intention.

  1. $ kubectl apply -f deny.yaml
  2. serviceintentions.consul.hashicorp.com/dashboard-to-counting created
  1. $ kubectl apply -f deny.yaml
  2. serviceintentions.consul.hashicorp.com/dashboard-to-counting created

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.

  1. $ kubectl delete -f deny.yaml
  2. serviceintentions.consul.hashicorp.com "dashboard-to-counting" deleted
  1. $ kubectl delete -f deny.yaml
  2. serviceintentions.consul.hashicorp.com "dashboard-to-counting" deleted

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.