Deploy Consul dataplanes

This page provides usage information for running Consul dataplanes with HCP Consul. Dataplanes enable communication between a HashiCorp-managed cluster and services running in a user-managed Kubernetes cluster.

For more information, including architecture, features, and constraints, refer to Simplified Service Mesh with Consul Dataplane in the Consul documentation.

Introduction

Consul dataplanes are lightweight processes for managing Envoy proxies. They remove the need to run client agents on every node in a cluster by leveraging existing Kubernetes sidecar orchestration capabilities. As of Consul v1.14.0, Kubernetes deployments use Consul dataplanes instead of client agents by default.

When using dataplanes with HCP Consul, you run a configured Consul container in your Kubernetes cluster. This Consul instance connects to the external HashiCorp-managed servers and enables Consul to inject dataplanes into sidecar containers.

Prerequisites

To deploy dataplanes with HCP Consul, you must meet the following minimum version requirements:

Consul v1.14.0
Consul K8s v1.0.0

Refer to Consul on Kubernetes Version Compatibility for more information about Kubernetes version requirements with specifc Consul versions.

Deploy dataplanes with HCP Consul

Complete the following steps to connect services in your Kubernetes cluster to HashiCorp-managed servers:

These steps reflect the Consul documentation's guidance to Join Kubernetes clusters to external Consul servers. For more information about configuring Consul on Kubernetes, refer to the Consul documentation's Helm Chart Reference.

This page describes the process to deploy dataplanes and connect them to a HashiCorp-managed cluster that already exists in your organization. If you have not done so, refer to Create a HashiCorp-managed cluster.

Prepare your Kubernetes cluster

To automate the process for deploying dataplanes, you must create a Kubernetes Secret containing your HCP Consul cluster admin token in the Kubernetes Namespace where you install Consul. This secret initializes the ACL system in the Consul workload scheduled on your Kubernetes cluster with credentials that enable secure access to the ACL system running on the HashiCorp-managed cluster.

Complete the following steps to create the Secret in the consul Namespace on Kubernetes:

Create a consul Namespace in your Kubernetes cluster.

$ kubectl create namespace consul
namespace/consul created

Create a Kubernetes secret with your cluster's admin token.

$ kubectl create secret generic "consul-bootstrap-token" --from-literal="token=<HCP-Consul-cluster-admin-token>" --namespace consul
secret/consul-bootstrap-token created

Configure Consul for your Kubernetes cluster

Set the following configurations in the Helm chart or values.yaml file:

The global.enabled value should be false. This setting disables all chart components by default so that each component is opt-in.
The datacenter name must match the cluster ID of your HashiCorp-managed cluster.
The version of Consul in global.image should match the version running on the HashiCorp-managed cluster.
The ACL system's bootstrapToken must invoke the consul-bootstrap-token Secret that contains the HashiCorp-managed cluster's admin token.
Use server.enabled: false to disable server agent features.
Configure an externalServers stanza with the HCP-managed cluster's IP address and your K8s cluster's API server URL.

The following example demonstrates required values and their configurations:

values.yaml

global:
  name: consul
  enabled: false
  datacenter: <hcp-cluster-id>
  image: "hashicorp/consul:<latest>"
  acls:
    manageSystemACLs: true
    bootstrapToken:
      secretName: consul-bootstrap-token
      secretKey: token
  tls:
    enabled: true
  enableConsulNamespaces: true
externalServers:
  enabled: true
  hosts: ["<hcp-managed-cluster-address>"]
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: <k8s-cluster-api-server-endpoint>
server:
  enabled: false
connectInject:
  enabled: true

Refer to the official Helm chart reference for more information about values and their specifications.

Install Consul on your Kubernetes cluster

Use either Helm or the consul-k8s CLI to apply the configuration to your Kubernetes cluster and deploy Consul. Be sure to install Consul in the Kubernetes Namespace that contains the consul-bootstrap-token secret. The consul-k8s CLI installs to the consul Namespace by default.

If necessary, you can include a --version flag to install Consul according to the Helm chart or consul-k8s release that is compatible with your Kubernetes cluster. Refer to Consul on Kubernetes Version Compatibility for more information about Kubernetes version requirements with specifc Consul releases.

Run either of the following commands for your preferred installation method:

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

The installation process should finish within a few minutes.

After you install Consul on your Kubernetes cluster, Consul does not deploy dataplanes until you register a service with Consul. Refer to Define services in the Consul documentation for more information.

Upgrading

Before you upgrade Consul to a version that uses Consul Dataplane, you must edit your Helm chart so that client agents are removed from your deployments. Refer to upgrading to Consul Dataplane for more information.

Tutorials

Consul Dataplane is supported on Kubernetes deployments. To learn more about using Kubernetes with HCP Consul, refer to the following tutorials: