Consul
Deploy Consul on EKS
This topic describes how to deploy a Consul datacenter to an AWS Elastic Kubernetes Services (EKS) cluster. After deploying Consul, you will interact with Consul using the CLI, UI, and/or API.
Requirements
To deploy Consul on AKS, you will need:
- An AWS account with the ability to create a Kubernetes cluster
- aws-cli
- kubectl >= 1.21
- consul >= 1.14.0
- Helm v3.6+
- consul-k8s v1.0.2+
Create an EKS cluster
You need at least a three node EKS cluster to deploy Consul using the official Consul Helm chart or the Consul K8S CLI. Create a three node cluster on EKS by following the EKS documentation.
Configure kubectl to talk to your cluster
Configure kubectl
to talk to your EKS cluster.
$ aws eks update-kubeconfig --region <region where you deployed your cluster> --name <your cluster name>
Verify you are connected to your Kubernetes cluster.
$ kubectl cluster-info
Kubernetes master is running at https://<your K8s master location>.eks.amazonaws.com
CoreDNS is running at https://<your CoreDNS location>.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Refer to the AWS documentation for additional information and help to configuring kubectl
and EKS.
Deploy Consul
You can deploy a complete Consul datacenter using the official Consul Helm chart or the Consul K8S CLI. By default, these methods will install a total of three Consul servers. You can review the Consul Kubernetes installation documentation to learn more about these installation options.
Create a values file
To customize your deployment, create a values.yaml
file to customization your Consul deployment.
values.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 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: true
# Enables ACLs across the cluster to secure access to data and APIs.
acls:
# If true, automatically manage ACL tokens and policies for all Consul components.
manageSystemACLs: true
# 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
# 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
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.
Install Consul onto the AKS cluster with consul-k8s
. Confirm the installation with a y
when prompted.
$ consul-k8s install -config-file=values.yaml -set global.image=hashicorp/consul:1.14.0
Review the official Consul K8S CLI documentation to learn more about additional settings.
Verify the Consul resources were successfully created.
$ kubectl get pods --namespace consul
NAME READY STATUS RESTARTS AGE
consul-connect-injector-6fc8d669b8-2n82l 1/1 Running 0 2m34s
consul-connect-injector-6fc8d669b8-9mqfm 1/1 Running 0 2m34s
consul-controller-554c7f79c4-2xc64 1/1 Running 0 2m34s
consul-server-0 1/1 Running 0 2m34s
consul-server-1 1/1 Running 0 2m34s
consul-server-2 1/1 Running 0 2m34s
consul-webhook-cert-manager-64889c4964-wxc9b 1/1 Running 0 2m34s
Configure your CLI to interact with Consul cluster
In this section, you will set environment variables in your terminal so your Consul CLI can interact with your Consul cluster. The Consul CLI reads these environment variables for behavior defaults and will reference these values when you run consul
commands.
Tokens are artifacts in the ACL system used to authenticate users, services, and Consul agents. Since ACLs are enabled in this Consul datacenter, entities requesting access to a resource must include a token that is linked with a policy, service identity, or node identity that grants permission to the resource. The ACL system checks the token and grants or denies access to resources based on the associated permissions. A bootstrap token has unrestricted privileges to all resources and APIs.
Retrieve the ACL bootstrap token from the respective Kubernetes secret and set it as an environment variable.
$ export CONSUL_HTTP_TOKEN=$(kubectl get --namespace consul secrets/consul-bootstrap-acl-token --template={{.data.token}} | base64 -d)
Set the Consul destination address.
$ export CONSUL_HTTP_ADDR=https://$(kubectl get services/consul-ui --namespace consul -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
Remove SSL verification checks to simplify communication to your Consul cluster.
$ export CONSUL_HTTP_SSL_VERIFY=false
Note
In a production environment, we recommend keeping this SSL verification set to true
. Only remove this verification for if you have a Consul cluster without TLS configured in development environment and demonstration purposes.
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.
Run the CLI command consul catalog services
to return the list of services registered in Consul. Notice this returns only the consul
service since it is the only running service in your Consul cluster.
$ consul catalog services
consul
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.4.117:8301 alive server 1.14.0beta1 2 dc1 default <all>
consul-server-1 10.0.5.11:8301 alive server 1.14.0beta1 2 dc1 default <all>
consul-server-2 10.0.4.55:8301 alive server 1.14.0beta1 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.
Next steps
You learned how to deploy a Consul datacenter onto an EKS cluster. After deploying Consul, you interacted with Consul using the CLI, UI, and API.
To learn more about deployment best practices, review the Kubernetes reference architecture tutorial.