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.
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.
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.
Complete the following steps to connect services in your Kubernetes cluster to HashiCorp-managed servers:
- Prepare your Kubernetes cluster
- Configure Consul for your Kubernetes cluster
- Install Consul on your Kubernetes cluster
- Apply services to your Kubernetes cluster
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.
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:
consulNamespace 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
Set the following configurations in the Helm chart or
global.enabledvalue 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.imageshould match the version running on the HashiCorp-managed cluster.
- The ACL system's
bootstrapTokenmust invoke the
consul-bootstrap-tokenSecret that contains the HashiCorp-managed cluster's admin token.
server.enabled: falseto disable server agent features.
- Configure an
externalServersstanza 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:
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.
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.
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.
Consul Dataplane is supported on Kubernetes deployments. To learn more about using Kubernetes with HCP Consul, refer to the following tutorials: