Consul
Deploy Consul on Windows nodes in Kubernetes
Consul is a service networking solution that enables teams to manage secure network connectivity between services and across on-prem and multi-cloud environments and runtimes. Consul offers service discovery, service mesh, traffic management, and automated updates to network infrastructure devices. Check out the What is Consul? page to learn more.
In this tutorial, you will deploy a Consul datacenter onto a Kubernetes cluster containing Windows and Linux nodes. After deploying Consul, you will interact with Consul using the CLI, UI, and/or the API. You will then deploy a demo application and integrate it with Consul service mesh.
In this tutorial, you will:
- Deploy an Elastic Kubernetes Service (EKS) cluster with Terraform
- Install Consul using Helm
- Deploy a demo application
- Configure your terminal to communicate with the Consul datacenter
- View Consul services with the CLI, UI, and/or API
Note
The Consul Kubernetes on Windows nodes feature is a preview release meant for testing purposes. This release is designed to be run on EKS and does not currently support GKE deployments.
Prerequisites
The tutorial assumes that you are familiar with Consul and its core functionality. If you're new to Consul, refer to the Consul Getting Started tutorials collection.
For this tutorial, you will need:
- An AWS account configured for use with Terraform
- aws-cli >= 2.0
- terraform >= 1.0
- consul >= 1.14.4
- git >= 2.0
- helm >= 3.0
- kubectl <= 1.24
Clone GitHub repository
In this section, you will clone two repositories; one containing the alpha release of the Consul Helm chart that supports Windows Kubernetes nodes, and the other containing the configuration files and resources for building your tutorial environment.
Clone the alpha release Helm chart
Clone the Consul Kubernetes GitHub repository.
$ git clone https://github.com/hashicorp/consul-k8s
Change into the directory of the repository you cloned.
$ cd consul-k8s/
Checkout the branch containing the alpha release of the Consul Helm chart that supports Windows Kubernetes nodes.
$ git checkout windows-alpha
Set this directory to the CONSUL_HELM_DIR environment variable.
$ export CONSUL_HELM_DIR=$(pwd)/charts/consul
Clone configuration files and resources
Open a separate terminal and clone the GitHub repository containing the configuration files and resources.
$ git clone https://github.com/hashicorp-education/learn-consul-k8s-windows
Change into the directory that contains the complete configuration files for this tutorial.
$ cd learn-consul-k8s-windows/self-managed/eks
Create infrastructure
With these Terraform configuration files, you are ready to deploy your infrastructure.
Issue the terraform init command from your working directory to download the necessary providers and initialize the backend.
$ terraform init
Initializing the backend...
Initializing provider plugins...
## ...
Terraform has been successfully initialized!
## ...
Then, deploy the resources. Confirm the run by entering yes.
$ terraform apply
## ...
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
## ...
Apply complete! Resources: 63 added, 0 changed, 0 destroyed.
Note
The Terraform deployment could take up to 15 minutes to complete. Feel free to explore the next sections of this tutorial while waiting for the environment to complete initialization.
Connect to your infrastructure
Kubernetes stores cluster connection information in a file called kubeconfig. You can retrieve the Kubernetes configuration settings for your EKS cluster and merge them into your local kubeconfig file by issuing the following command:
$ aws eks --region $(terraform output -raw region) update-kubeconfig --name $(terraform output -raw kubernetes_cluster_id)
Review and deploy Consul datacenter
You will now review the values file for deploying a Consul datacenter in your Kubernetes cluster using Helm.
Open helm/values-v1.yaml. This file defines the Consul datacenter you will deploy to Kubernetes. Review the comments in the file for an explanation of each parameter.
helm/values-v1.yaml
# Contains values that affect multiple components of the chart.
global:
# The main enabled/disabled setting.
# If true, servers, clients, Consul DNS and the Consul UI will be enabled.
enabled: true
# The prefix used for all resources created in the Helm chart.
name: consul
# The Consul image version.
image: hashicorp/consul:1.14.3
# The Consul K8S images with Windows support.
imageK8S: hashicorppreview/consul-k8s-control-plane:1.0.0-alpha1
imageK8SWindows: hashicorppreview/consul-k8s-control-plane:1.0.0-alpha1-windows
imageConsulDataplaneWindows: hashicorppreview/consul-dataplane:1.0.0-alpha1-windows
# The name of the datacenter that the agents should register as.
datacenter: dc1
# Enables TLS across the cluster to verify authenticity of the Consul servers and clients.
tls:
enabled: false
# Enables ACLs across the cluster to secure access to data and APIs.
acls:
# ACLs are not currently supported with the Windows alpha release
manageSystemACLs: no
# Configures values that configure the Consul server cluster.
server:
enabled: true
# The number of server agents to run. This determines the fault tolerance of the cluster.
replicas: 3
# When running mixed clusters, nodeSelector MUST be specified.
nodeSelector: |
kubernetes.io/os: linux
kubernetes.io/arch: amd64
# Contains values that configure the Consul UI.
ui:
enabled: true
# Registers a Kubernetes Service for the Consul UI as a LoadBalancer.
service:
type: LoadBalancer
# Configures and installs the automatic Consul Connect sidecar injector.
connectInject:
enabled: true
# When running mixed clusters, nodeSelector MUST be specified
nodeSelector: |
kubernetes.io/os: linux
kubernetes.io/arch: amd64
webhookCertManager:
# When running mixed clusters, nodeSelector MUST be specified
nodeSelector: |
kubernetes.io/os: linux
kubernetes.io/arch: amd64
Note
The Consul Kubernetes on Windows nodes feature is a preview release meant for testing purposes. This release does not currently support Consul ACLs or TLS.
For a complete list of Helm chart parameters and configuration, refer to the Consul Helm chart documentation.
Deploy Consul datacenter
Deploy a Consul datacenter to your Kubernetes environment with the alpha release Helm chart you cloned earlier.
Install Consul to your Kubernetes cluster with the Helm chart. Notice that this command installs Consul into the consul namespace.
$ helm install consul --create-namespace -n consul -f helm/values-v1.yaml $CONSUL_HELM_DIR
Verify Helm successfully created the Consul resources.
$ kubectl get pods --namespace consul
NAME READY STATUS RESTARTS AGE
consul-connect-injector-6ccc9fb587-598nz 1/1 Running 0 62s
consul-server-0 1/1 Running 0 62s
consul-server-1 1/1 Running 0 62s
consul-server-2 1/1 Running 0 62s
consul-webhook-cert-manager-5d645f6497-pbzgk 1/1 Running 0 62s
Deploy the counting and dashboard demo application
In this section, you will deploy the demo application to explore Consul's service mesh features.
The nodeSelector attribute defines which Kubernetes nodes will host the workload. In this scenario, the counting service will run on Linux Kubernetes nodes and the dashboard service will run on Windows Kubernetes nodes.
demo-app/counting.yaml
## ...
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: counting
name: counting
spec:
replicas: 1
selector:
matchLabels:
app: counting
template:
metadata:
annotations:
consul.hashicorp.com/connect-inject: 'true'
labels:
app: counting
spec:
## ...
nodeSelector:
kubernetes.io/os: linux
kubernetes.io/arch: amd64
Deploy the counting and dashboard demo application.
$ kubectl apply --filename demo-app/
serviceaccount/counting created
service/counting created
deployment.apps/counting created
serviceaccount/dashboard created
service/dashboard created
deployment.apps/dashboard created
Tip
The initial demo application deployment will take about 10-15 minutes to complete. Windows containers are much larger than Linux containers and generally take more time to reach a running status.Check the pods to confirm they are all running.
$ kubectl get pods --namespace default
NAME READY STATUS RESTARTS AGE
counting-6884c54f59-g4trx 2/2 Running 0 15m40s
dashboard-5676d5878f-q6q79 2/2 Running 0 15m40s
Test the demo application
In a new terminal window, port forward the dashboard service to locally view the demo application's dashboard.
$ kubectl port-forward svc/dashboard --namespace default 9002:9002
Open http://localhost:9002 in your browser.
The dashboard UI shows it is connected to the counting backend. This indicates that the dashboard service running on the Kubernetes Linux node and the counting service running on the Kubernetes Windows node can communicate through Consul service mesh.
Configure your CLI to interact with Consul datacenter
In this section, you will set environment variables in your terminal so your Consul CLI can interact with your Consul datacenter. The Consul CLI reads these environment variables for behavior defaults and will reference these values when you run consul commands.
Set the Consul destination address. By default, Consul runs on port 8500 for http and 8501 for https.
$ export CONSUL_HTTP_ADDR=http://$(kubectl get services/consul-ui --namespace consul -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
View Consul services
In this section, you will view your Consul services with the CLI, UI, and/or API to explore the details of your service mesh.
In your terminal, run the CLI command consul catalog services to return the list of services registered in Consul.
$ consul catalog services
consul
counting
counting-sidecar-proxy
dashboard
dashboard-sidecar-proxy
Agents run in either server or client mode. Server agents store all state information, including service and node IP addresses, health checks, and configuration. Client agents are lightweight processes that make up the majority of the datacenter. They report service health status to the server agents. Clients must run on every pod where services are running.
Run the CLI command consul members to return the list of Consul agents in your environment.
$ consul members
Node Address Status Type Build Protocol DC Partition Segment
consul-server-0 10.0.5.121:8301 alive server 1.15.0 2 dc1 default <all>
consul-server-1 10.0.6.192:8301 alive server 1.15.0 2 dc1 default <all>
consul-server-2 10.0.4.174:8301 alive server 1.15.0 2 dc1 default <all>
All services listed in your Consul catalog are empowered with Consul's service discovery capabilities that simplify scalability challenges and improve application resiliency. Review the Service Discovery overview page to learn more.
Clean up
Destroy the Terraform resources to clean up your environment. Confirm the destroy operation by inputting yes.
$ terraform destroy
Note
Due to race conditions with the various cloud resources created in this tutorial, you may need to run the destroy operation twice to ensure all resources have been properly removed.
Next steps
In this tutorial, you integrated Consul into your environment containing both Linux and Windows Kubernetes nodes. After deploying Consul, you interacted with Consul using the CLI, UI, and/or API.
For more information about the topics covered in this tutorial, refer to the following resources: