Deploy Consul on Windows nodes in Kubernetes

12min
|
Consul

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.

# 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.

## ...
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

## ...
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: dashboard
  name: dashboard
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dashboard
  template:
    metadata:
      annotations:
        consul.hashicorp.com/connect-inject: 'true'
        consul.hashicorp.com/connect-service-upstreams: 'counting:9001'
      labels:
        app: dashboard
    spec:
      ## ...
      nodeSelector:
        kubernetes.io/os: windows

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.

Dashboard to Counting service connection success

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>

Output the Consul URL value to your terminal and paste it in your browser to find the Consul UI. Since this environment uses a self-signed TLS certificate for its resources, click to proceed through the certificate warnings.

$ echo $CONSUL_HTTP_ADDR
http://a55925452f7214a1cad0a0d564ae1872-646141274.us-west-2.elb.amazonaws.com

On the left navigation pane, click Services to review your deployed services.

Consul UI Services Page

On the left navigation pane, click on Nodes.

Consul UI View Nodes

In your terminal, view the list of services registered in Consul.

$ curl -k \
    $CONSUL_HTTP_ADDR/v1/catalog/services

Sample output:

{"consul":[],"counting":[],"counting-sidecar-proxy":[],"dashboard":[],"dashboard-sidecar-proxy":[]}

View the list of server and client Consul agents in your environment.

$ curl -k \
    $CONSUL_HTTP_ADDR/v1/agent/members

Sample output:

[{"Name":"consul-server-2","Addr":"10.0.4.174","Port":8301,"Tags":{"acls":"0","build":"1.15.0:53f65dc3","dc":"dc1","expect":"3","ft_fs":"1","ft_si":"1","grpc_port":"8502","id":"a332301a-2a69-49f3-3669-532417e646c9","port":"8300","raft_vsn":"3","role":"consul","segment":"","vsn":"2","vsn_max":"3","vsn_min":"2","wan_join_port":"8302"},"Status":1,"ProtocolMin":1,"ProtocolMax":5,"ProtocolCur":2,"DelegateMin":2,"DelegateMax":5,"DelegateCur":4},{"Name":"consul-server-1","Addr":"10.0.6.192","Port":8301,"Tags":{"acls":"0","build":"1.15.0:53f65dc3","dc":"dc1","expect":"3","ft_fs":"1","ft_si":"1","grpc_port":"8502","id":"167c0efe-9c97-6cf1-6c48-ce53db544ada","port":"8300","raft_vsn":"3","role":"consul","segment":"","vsn":"2","vsn_max":"3","vsn_min":"2","wan_join_port":"8302"},"Status":1,"ProtocolMin":1,"ProtocolMax":5,"ProtocolCur":2,"DelegateMin":2,"DelegateMax":5,"DelegateCur":4},{"Name":"consul-server-0","Addr":"10.0.5.121","Port":8301,"Tags":{"acls":"0","build":"1.15.0:53f65dc3","dc":"dc1","expect":"3","ft_fs":"1","ft_si":"1","grpc_port":"8502","id":"099b08a3-6ffc-b0b9-540c-417b48a8da00","port":"8300","raft_vsn":"3","role":"consul","segment":"","vsn":"2","vsn_max":"3","vsn_min":"2","wan_join_port":"8302"},"Status":1,"ProtocolMin":1,"ProtocolMax":5,"ProtocolCur":2,"DelegateMin":2,"DelegateMax":5,"DelegateCur":4}]

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:

Windows workloads

Next Collection

Control network traffic