Link existing self-managed clusters
This page describes the process for linking an existing self-managed cluster to HCP Consul Central. By linking an existing self-managed cluster, you are able to take advantage of HCP Consul Central’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.
Your cluster must have ACLs enabled and the ACL system must be bootstrapped in order to link it to HCP Consul in read-only mode. To enable Consul's ACL system:
- On VMs, set
acl.enabled=truein the agent's configuration file.
- On Kubernetes, set
global.acls.manageSystemACLs: truein the Consul Helm chart.
consul-k8s CLI automatically bootstraps ACLs on your behalf when you update
global.acls.manageSystemACLs in your
values.yaml configuration and apply the change to your cluster. To manually bootstrap ACLs so that HCP can link to it, you must create the initial management token.
Follow the instructions according to your existing cluster’s runtime. After you successfully initiate the link, HCP Consul 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 link an existing self-managed Consul cluster running on virtual machines, complete the following steps:
- From the HCP Consul overview, click Create or link a Consul cluster.
- Select Self-managed Consul.
- Click Link existing and then 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.
- Optionally, click Read-only and enter the
SecretIDof a dedicated ACL token. For help creating this token, refer to Add a dedicated read-only token for HCP Consul. For information about the difference between linking a cluster in read/write or read-only mode, refer to cluster access permissions.
- Click 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
Cloud configuration block required to link the cluster to HCP.
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, 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.
Once your self-managed cluster is successfully linked, HCP Consul Central 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, you must use HCP to remove the link. If you delete a cluster without unlinking it from HCP first, the cluster will continue to appear in HCP as an unhealthy cluster.
In the Consul overview section of HCP Consul Central, 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 Central 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: