Installing and Managing Consul on Kubernetes with Helm and consul-k8s

This guide provides instructions for installing Consul on Kubernetes using Helm and the consul-k8s CLI, including how to list available versions, configure secure deployments, and perform a rolling restart of Consul server pods.

1. Prerequisites

Ensure you have the following tools installed:

• Helm (version compatible with your Kubernetes cluster)

• kubectl configured for your Kubernetes cluster

• consul-k8s CLI (optional, for simplified installations)

2. Adding the HashiCorp Helm Repository

To access Consul Helm charts, add the HashiCorp Helm repository:

helm repo add hashicorp https://helm.releases.hashicorp.com
helm repo update

3. Listing Available Consul-k8s Versions

To view all available versions of the Consul Helm chart:

helm search repo hashicorp/consul --versions

This command lists all versions of the hashicorp/consul chart, helping you select the appropriate version for your deployment.

4. Installing Consul with Helm

Basic Installation

Install Consul using a specific chart version and a custom values.yaml file.

# values.yaml
controller:
  enabled: true
connectInject:
  enabled: true
global:
  acls:
    manageSystemACLs: true
  gossipEncryption:
    autoGenerate: true
  name: consul
  tls:
    enableAutoEncrypt: true
    enabled: true
server:
  replicas: 1
ui:
  enabled: true
  service:
    type: LoadBalancer

Use the --debug flag to observe the installation process in detail:

helm install consul hashicorp/consul --version "0.49.1" -f values.yaml --wait --debug

Note: The --wait flag ensures the installation completes before returning control, and --debug provides verbose output for troubleshooting.

Secure Installation with consul-k8s CLI

For a streamlined installation with ACLs, TLS, and Prometheus enabled, use the consul-k8s CLI with the secure preset:

consul-k8s install --preset secure \
  --set server.replicas=3 \
  --set ui.service.type=LoadBalancer \
  --set prometheus.enabled=true

This command configures:

• Enable ACLs and TLS

• 3 server replicas

• A LoadBalancer service for the Consul UI

• Built-in Prometheus monitoring

Custom Helm Installation with Overrides

To customize settings beyond the values.yaml file, use --set flags to override specific parameters:

helm install consul hashicorp/consul --version="1.0.3" -f values.yaml \
  --set global.acls.createReplicationToken=true \
  --set global.federation.enabled=true \
  --set global.federation.createFederationSecret=true \
  --set meshGateway.enabled=true \
  --set meshGateway.replicas=1 \
  --set meshGateway.service.port=8443 \
  --wait --debug

This example enables federation, ACL replication, and a single mesh gateway on port 8443.

5. Performing a Rolling Restart of Consul Server Pods

To gracefully restart a Consul server pod (e.g., consul-server-0):

1. Initiate the pod's graceful leave:

    kubectl exec consul-server-0 -- consul leave -token $CONSUL_TOKEN
   

   Replace $CONSUL_TOKEN with your Consul ACL token.

2. Monitor the rolling update:

    kubectl rollout status statefulset/consul-server --watch
   

   This command tracks the progress of the StatefulSet rolling update until completion.