Deploy Consul on Google Kubernetes Engine (GKE)

13min
|
Consul

In this tutorial you will deploy a Consul datacenter to the Google Kubernetes Engine (GKE) on Google Cloud Platform (GCP) with HashiCorp’s official Helm chart or the Consul K8S CLI. After deploying Consul, you will interact with Consul using the CLI, UI, and/or API.

Prerequisites

For this tutorial, you will need:

A GCP account with the ability to create a Kubernetes cluster
Google Cloud CLI
kubectl >= 1.21
helm >= 3.0
consul >= 1.14.0

Initialize Google Cloud CLI

Run gcloud init to initialize the Google Cloud CLI.

$ gcloud init

Service account authentication (optional)

You should create a GCP IAM service account and authenticate with it on the command line.

To review the GCP IAM service account documentation, go here
To interact with GCP IAM service accounts, go here

Once you have obtained your GCP IAM service account key-file, you can authenticate your local gcloud cli by running the following:

$ gcloud auth activate-service-account --key-file="<path-to/my-consul-service-account.json>"

Create a GKE cluster

At least a three node GKE cluster is required to deploy Consul using the official Consul Helm chart or the Consul K8S CLI. Create a three node cluster on GKE by following the GKE documentation.

Configure kubectl to talk to your cluster

From the GCP console, where you previously created your cluster, click the "Connect" button. Copy the snippet provided and paste it into your terminal.

$ gcloud container clusters get-credentials my-consul-cluster --zone us-west1-b --project my-project

You can then run kubectl cluster-info to verify you are connected to your Kubernetes cluster:

$ kubectl cluster-info

Kubernetes master is running at https://<your GKE ip(s)>
GLBCDefaultBackend is running at https://<your GKE ip(s)>/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
Heapster is running at https://<your GKE ip(s)>/api/v1/namespaces/kube-system/services/heapster/proxy
KubeDNS is running at https://<your GKE ip(s)>/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://<your GKE ip(s)>/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

To further debug and diagnose cluster problems, use kubectl cluster-info dump.

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.

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

$ brew tap hashicorp/tap

$ brew install hashicorp/tap/consul-k8s

$ consul-k8s install -config-file=values.yaml -set global.image=hashicorp/consul:1.14.0

Note

You can review the official Consul K8S CLI documentation to learn more about additional settings.

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

$ helm install --values values.yaml consul hashicorp/consul --create-namespace --namespace consul --version "1.0.0"

Note

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

Run the command kubectl get pods to 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].ip}')

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>

Output the token value to your terminal and copy the value to your clipboard. You will use this ACL token to authenticate in the Consul UI.

$ echo $CONSUL_HTTP_TOKEN
fe0dd5c3-f2e1-81e8-cde8-49d26cee5efc

Open a separate terminal window and expose the Consul UI with kubectl port-forward using the consul-ui service name as the target. By default, Consul UI runs on port 6443 when you enable TLS, and port 8500 when TLS is disabled.

$ kubectl port-forward svc/consul-ui --namespace consul 6443:443

Open https://localhost:6443 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.

On the left navigation pane, click Services to review your deployed services. At this time, you will only find the consul service.

Consul UI Services Page

By default, the anonymous ACL policy allows you to view the contents of Consul services, nodes, and intentions. To make changes and see more details within the Consul UI, click Log In in the top right and insert your bootstrap ACL token.

Consul UI Login Page

After successfully authenticating with your ACL token, you are now able to view additional Consul components and make changes in the UI. Notice you can view and manage more options under the Access Controls section on the left navigation pane.

Consul UI Post Authentication

On the left navigation pane, click on Nodes.

Consul UI Nodes

View the list of services registered in Consul.

$ curl -k \
    --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
    $CONSUL_HTTP_ADDR/v1/catalog/services

Sample output:

{"consul":[]}

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

$ curl -k \
    --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
    $CONSUL_HTTP_ADDR/v1/agent/members\?pretty

Sample output:

[
    {
        "Name": "consul-server-0",
        "Addr": "10.244.0.13",
        "Port": 8301,
        "Tags": {
            "acls": "1",
            "bootstrap": "1",
            "build": "1.14.0",
            "dc": "dc1",
            "ft_fs": "1",
            "ft_si": "1",
            "grpc_port": "8502",
            "id": "8016fc4d-767f-8552-b018-0812228bd135",
            "port": "8300",
            "raft_vsn": "3",
            "role": "consul",
            "segment": "",
            "use_tls": "1",
            "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
    }
...TRUNCATED
]

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

In this tutorial, you deployed a Consul datacenter onto an Google Kubernetes Engine (GKE) 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.

Consul on Kubernetes design patterns

L7 observability