Deploy Consul Dataplane on Kubernetes

This page describes the requirements to set up Consul on Kubernetes deployments to use dataplanes instead of client agents, as well as the process to update existing deployments to use dataplanes instead of agents.

If you already have a Consul cluster deployed on Kubernetes and would like to turn on TLS for internal Consul communication, refer to Configuring TLS on an Existing Cluster.

Requirements

• Dataplanes can connect to Consul servers v1.14.0 and newer.
• Dataplanes on Kubernetes requires Consul K8s v1.0.0 and newer.
• Consul Dataplane is not supported on Windows.
• Consul Dataplane requires the NET_BIND_SERVICE capability. Refer to Set capabilities for a Container in the Kubernetes Documentation for more information.

Installation

To install Consul Dataplane, set VERSION to 1.0.0 and then follow the instructions to install a specific version of Consul with the Helm Chart or with the Consul-k8s CLI.

Helm

$ export VERSION=1.0.0
$ helm install consul hashicorp/consul --set global.name=consul --version ${VERSION} --create-namespace --namespace consul

Consul-k8s CLI

$ export VERSION=1.0.0 && \
    curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip

Upgrading to Consul Dataplane

In earlier versions, Consul on Kubernetes used client agents in its deployments. As of v1.14.0, Consul uses Consul Dataplane in Kubernetes deployments instead of client agents.

If you upgrade Consul from a version that uses client agents to a version the uses dataplanes, complete the following steps to upgrade your deployment safely and without downtime.

1. If ACLs are enabled, you must first upgrade to consul-k8s 0.49.8 or above. These versions expose the setting connectInject.prepareDataplanesUpgrade which is required for no-downtime upgrades when ACLs are enabled.

   Set connectInject.prepareDataplanesUpgrade to true and then perform the upgrade to 0.49.8 or above (whichever is the latest in the 0.49.x series)

   connectInject:
     prepareDataplanesUpgrade: true
   

2. Consul dataplanes disables Consul clients by default, but during an upgrade you need to ensure Consul clients continue to run. Edit your Helm chart configuration and set the client.enabled field to true and specify an action for Consul to take during the upgrade process in the client.updateStrategy field:

   client:
     enabled: true
     updateStrategy: |
       type: OnDelete
   

3. Follow our recommended procedures to upgrade servers on Kubernetes deployments to upgrade Helm values for the new version of Consul. The latest version of consul-k8s components may be in a CrashLoopBackoff state during the performance of the server upgrade from versions <1.14.x until all Consul servers are on versions >=1.14.x. Components in CrashLoopBackoff will not negatively affect the cluster because older versioned components will still be operating. Once all servers have been fully upgraded, the latest consul-k8s components will automatically restore from CrashLoopBackoff and older component versions will be spun down.

4. Run kubectl rollout restart to restart your service mesh applications. Restarting service mesh application causes Kubernetes to re-inject them with the webhook for dataplanes.

5. Restart all gateways in your service mesh.

6. Now that all services and gateways are using Consul dataplanes, disable client agents in your Helm chart by deleting the client stanza or setting client.enabled to false and running a consul-k8s or Helm upgrade.

7. If ACLs are enabled, outdated ACL tokens will persist a result of the upgrade. You can manually delete the tokens to declutter your Consul environment.

   Outdated connect-injector tokens have the following description: token created via login: {"component":"connect-injector"}. Do not delete the tokens that have a description where pod is a key, for example token created via login: {"component":"connect-injector","pod":"default/consul-connect-injector-576b65747c-9547x"}). The dataplane-enabled connect inject pods use these tokens.

   You can also review the creation date for the tokens and only delete the injector tokens created before your upgrade, but do not delete all old tokens without considering if they are still in use. Some tokens, such as the server tokens, are still necessary.