HashiCorp Developer AI Private beta now available Sign up today
HashiCorp Cloud Platform
HashiCorp Cloud Platform Home

Link new self-managed clusters

This page describes the process for creating a self-managed cluster and linking it to HCP Consul Central as part of a single workflow. By linking a new self-managed 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 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 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 HCP 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 then generates credentials to authenticate and connect your self-managed 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 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 clusters

To unlink a self-managed cluster, start in the HCP portal. If you delete a self-managed cluster without unlinking it from HCP Consul 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 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 cannot access your self-managed cluster after you unlink it. However, the self-managed cluster retains the management token that HCP Consul created and used. If you plan on using your self-managed cluster without HCP Consul, 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 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: