Link existing self-managed Community and Enterprise clusters

Warning

HashiCorp will deprecate HCP Consul Central on November 6, 2024. Learn more.

This page describes the process for linking an existing self-managed Community or Enterprise cluster to HCP Consul Central. By linking an existing self-managed Community or Enterprise 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.

Prerequisites

Linking a self-managed Community or Enterprise 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.

The 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=true in the agent's configuration file.
On Kubernetes, set global.acls.manageSystemACLs: true in the Consul Helm chart.

The 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.

Link an existing self-managed-cluster

Follow the instructions according to your existing cluster’s runtime. After you successfully initiate the link, 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 link an existing self-managed Consul cluster running on virtual machines, complete the following steps:

From the 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 SecretID of a dedicated ACL token. For help creating this token, refer to Add a dedicated read-only token for HCP Consul Central. 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 Central then generates credentials to authenticate and connect your self-managed Community or Enterprise cluster and provides them in a JSON code snippet that contains the entire Cloud configuration block required to link the cluster to HCP.

Add the 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.json file. Add config.json to the same directory as your agent’s configuration file.
Run consul leave to stop running the server agent.
Run 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 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.

To link an existing self-managed Consul cluster running on Kubernetes, complete the following steps:

From the 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 Kubernetes.
Optionally, click Read-only and enter the SecretID of a dedicated ACL token. For help creating this token, refer to Add a dedicated read-only token for HCP Consul Central. For information about the difference between linking a cluster in read/write or read-only mode, refer to cluster access permissions.
Click Continue.
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 series of code snippets. These snippets contains all of the information needed to create and link your cluster.
Copy the kubectl commands in the first code block and run them in the CLI to set Kubernetes secrets for securely connecting your new cluster to HCP. If necessary for your network, edit the --namespace=consul flag at the end of each command to match the namespace where you deployed Consul.
If you do not have a values.yaml file already, run consul-k8s config read > values.yaml to create one.

Copy the cloud configuration stanza and add it to your values.yaml file. Nest the stanza under the global value, as demonstrated in the following example:

global:
  cloud:
    enabled: true
    resourceId:
      secretName: "consul-hcp-resource-id"
      secretKey: "resource-id"
    clientId:
      secretName: "consul-hcp-client-id"
      secretKey: "client-id"
    clientSecret:
      secretName: "consul-hcp-client-secret"
      secretKey: "client-secret"

Copy the consul-k8s upgrade command and run it in the CLI.

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.

To link an existing self-managed Consul cluster running on Kubernetes, complete the following steps:

From the 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 Kubernetes.
Optionally, click Read-only and enter the SecretID of a dedicated ACL token. For help creating this token, refer to Add a dedicated read-only token for HCP Consul Central. For information about the difference between linking a cluster in read/write or read-only mode, refer to cluster access permissions.
Click Continue.
Click Helm 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 series of code snippets. These snippets contains all of the information needed to create and link your cluster.
Copy the kubectl commands in the first code block and run them in the CLI to set Kubernetes secrets for securely connecting your new cluster to HCP. If necessary for your network, edit the --namespace=consul flag at the end of each command to match the namespace where you want to deploy Consul.

Copy the cloud configuration stanza and add it to your Helm values file. Nest the stanza under the global value, as demonstrated in the following example:

global:
  cloud:
    enabled: true
    resourceId:
      secretName: "consul-hcp-resource-id"
      secretKey: "resource-id"
    clientId:
      secretName: "consul-hcp-client-id"
      secretKey: "client-id"
    clientSecret:
      secretName: "consul-hcp-client-secret"
      secretKey: "client-secret"

Copy the helm upgrade consul command and run it in the CLI. If necessary for your network, edit the --namespace=consul flag at the end of the command to match the namespace where you want to deploy Consul.

Once your self-managed Community or Enterprise 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.

Unlink self-managed Community and Enterprise clusters

To unlink a self-managed Community or Enterprise 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 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 the cluster.

Next steps

To learn more about what you can do with your self-managed Community or Enterprise cluster after you link it to HCP Consul Central, refer to the following topics: