Link new self-managed Community and Enterprise clusters

This page describes the process for creating a self-managed Community or Enterprise cluster and linking it to HCP Consul Central as part of a single workflow. By linking a new self-managed Community or Enterprise cluster at the same time you create it, you are able to take advantage of HCP Consul’s features, including automated cluster creation, observability insights, and global workflows, for the entirety of the cluster’s lifecycle.

Creating and linking a self-managed Community or Enterprise cluster at the same time requires Consul on Kubernetes. To get started with the consul-k8s CLI, refer to the installation guide in the Consul documentation.

Prerequisites

Linking a self-managed Community or Enterprise cluster is supported in Consul v1.14.7, v1.15.3, and later.

The consul-k8s CLI supports linking clusters to HCP in v1.0.7, v1.1.2, and later.

Usage

To create and link a self-managed Consul cluster running on Kubernetes using the consul-k8s CLI, complete the following steps:

1. From the Consul overview, click Deploy Consul.
2. Click Create and link a new self-managed cluster and then click Get Started.
3. Enter a name for your cluster. This name must have 3 to 36 characters and be unique to your organization.
4. Click Kubernetes and then Continue.
5. Click Consul-K8s CLI to generate the appropriate CLI commands.

HCP Consul Central then generates credentials to authenticate and connect your self-managed Community or Enterprise cluster and provides them in a code snippet. This snippet contains all of the information needed to create and link your cluster.

By default, HCP generates a command that includes a demo application. To install Consul without the demo application, uncheck Include demo application as part of Consul install or manually remove the -demo flag from the end of the command.

After you run the command, the linking process begins automatically. After the linking process is complete, your self-managed Community or Enterprise cluster appears in the list on the Consul overview. When you click its name, HCP Consul Central shows information about the cluster, such as individual server IP addresses and port assignments, as well as the cluster’s current health status.

Unlink self-managed Community and Enterprise clusters

To unlink a self-managed Community or Enterprise cluster, start in the HCP portal. If you delete a self-managed Community or Enterprise cluster without unlinking it from HCP Consul Central first, the cluster and its service instances will continue to appear in the HCP portal as unhealthy.

In the Consul overview section of the HCP portal, click the name of the self-managed Community or Enterprise cluster you want to unlink. Then, click Manage and then Unlink from HCP. Type UNLINK in the text entry field and then click Unlink to confirm.

HCP Consul Central cannot access your self-managed Community or Enterprise cluster after you unlink it. However, the self-managed Community or Enterprise cluster retains the management token that HCP Consul Central created and used. If you plan on using your self-managed Community or Enterprise cluster without HCP Consul Central, use the consul acl token command to list and delete tokens associated with HCP Consul Central.

Next steps

After you link a new self-managed Community or Enterprise cluster, continue the process to configure and secure your new cluster. Common next steps when deploying a new cluster include the following topics in the Consul documentation:

• Register services and health checks to your cluster
• Create and manage service intentions
• Configure the ACL system to secure the cluster