Link existing self-managed clusters
This page describes the process for linking an existing self-managed cluster to the HCP Consul management plane service. By linking an existing self-managed cluster, you are able to take advantage of HCP Consul’s features, such as observability insights and global workflows, while retaining full management over your cluster.
Kubernetes users have the option to use either Consul on Kubernetes or Helm. To get started with the
consul-k8s CLI, refer to the installation guide in the Consul documentation.
Linking a self-managed cluster is supported in Consul v1.14.7, v1.15.3, and later. If necessary, upgrade your existing cluster before attempting to link it to HCP.
consul-k8s CLI supports linking clusters to HCP in v1.0.7, v1.1.2, and later.
Follow the instructions for your existing cluster’s runtime.
To link an existing self-managed Consul cluster running on virtual machines, complete the following steps:
- From the HCP Consul overview, click Deploy Consul.
- Select Self-managed Consul.
- Click Link an existing self-managed cluster and then click Get Started.
- Enter a name for your cluster. This name must have 3 to 36 characters and be unique to your organization. This name does not need to match names in your existing deployment. It is used only within the management plane service to identify your linked cluster.
- Click Virtual machine and then Continue.
HCP Consul then generates credentials to authenticate and connect your self-managed cluster and provides them in a JSON code snippet that contains the entire
Global.Cloud configuration block required to link the cluster to HCP.
Global.Cloud configuration block to the agent configuration file and then restart the
consul service on each server.
You can also merge the configuration block into your existing agent configuration. For this approach, complete the following steps:
- Copy the JSON configuration and paste it into a
config.jsonto the same directory as your agent’s configuration file.
consul leaveto stop running the server agent.
consul agent -server -config-dir=<path>to load and merge the agent configurations.
After the agent restarts, the linking process begins automatically. When the linking process is complete, your self-managed cluster appears in the list on the Consul overview. When you click its name, the HCP Consul management plane shows information about the cluster, such as individual server IP addresses and port assignments, as well as the cluster’s current health status.
Once your self-managed cluster is successfully linked, the management plane may take up to 10 minutes to create the access policies that allow users with other HCP roles to access the cluster. Refer to user roles and ACL policies for more information.
To unlink a self-managed cluster, remove the linking from the HCP portal first. If you delete a cluster without unlinking it from HCP first, the cluster will continue to appear in the HCP portal as an unhealthy cluster.
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 the cluster.
To learn more about what you can do with your self-managed cluster after you link it to HCP Consul, refer to the following topics: