Manage HCP's cluster access permissions

This page describes the process and best practices for maintaining token security when linking self-managed Consul clusters with HCP Consul Central. For more information, refer to cluster access permissions.

Change read/write cluster permissions to read-only

To change a cluster's read-write permissions to read-only, you must unlink the cluster from HCP Consul and then re-link it with read-only permissions. Complete the following steps to change your cluster's access permissions:

1. Unlink the existing cluster from HCP Consul Central. For details on how to unlink a cluster, refer to Unlink self-managed Community and Enterprise clusters.
2. Delete the token with HCP Management Token in its description field. Do not delete the Bootstrap Token or the global-management ACL policy.
3. Create a dedicated read-only token for HCP by following the steps in Add a dedicated read-only token for HCP Consul Central.
4. Re-link the cluster with HCP Consul Central. Follow the steps to link an existing self-managed Community or Enterprise cluster to HCP Consul Central and add the SecretID of the dedicated read-only token you created.

Change read-only cluster permissions to read/write

You can change a cluster's read-only permissions to allow read/write access using HCP Consul Central's cluster management tools.

1. From the HCP Consul Central overview, click the name of the linked cluster you want to change permissions for.

2. Click Manage and then Change to read/write mode.

3. Type CONFIRM in the text entry field and then click Confirm.

4. Restart the Consul servers so that the change to read/write mode takes effect. Because the agent has a cloud configuration linking it to your HCP organization, the agent shuts down and then rejoins HCP when a graceful leave is triggered. To restart a server by gracefully leaving the cluster and rejoining, follow the instructions for your chose runtime:

   HTTP APICLIKubernetes

   Issue the following cURL request to trigger a graceful shutdown of the Consul server:

   $ curl \
     --header "X-Consul-Token: <bootstrap-token>" \
     -X PUT http://127.0.0.1:8500/v1/agent/leave
   

   To restart the Consul server, use the consul leave command to trigger a graceful shurdown.

   $ consul leave -token=<TOKEN>
   

   To restart the Consul server, use the kubectl exec command to interact with the Consul CLI in the server's container. The following example restarts a Consul server named consul-server-0.

   $ kubectl exec consul-server-0 --namespace consul -- consul leave -token=<TOKEN>
   

After your cluster re-connects to HCP Consul Central in read/write mode, delete the dedicated read-only token you created for HCP Consul Central from your self-managed Consul cluster.

Update read-only token

To rotate HCP Consul Central's dedicated read-only token, complete the following steps:

1. Create a new dedicated read-only token for HCP by following the steps in Add a dedicated read-only token for HCP Consul Central.
2. From the HCP Consul Central overview, click the name of the linked cluster you want to change permissions for.
3. Click Manage and then Update read-only token.
4. Enter the secret ID of the newly created read-only token in the Secret ID field. Then, click Confirm.

On the cluster details page, the status badge changes from Running to Updating token. When the update is complete, the badge reverts to Running.

After you update your dedicated read-only token, delete the old dedicated token from your self-managed Community or Enterprise cluster.

Best practices

We recommend following these security best practices when managing access tokens for HCP Consul Central.

• After granting read/write access to HCP Consul Central, do not modify the management token generated by HCP. In the event of a disaster, a modified management token may prevent recovery.
• Use a dedicated read-only token when linking your self-managed Community or Enterprise cluster to HCP Consul Central. A dedicated token helps you track which requests came from HCP. Refer to audit logging in the Consul documentation for more information.
• After unlinking a read-only cluster, HCP Consul Central's dedicated read-only token is no longer used. Delete unnecessary ACL tokens from your self-managed Community or Enterprise cluster to ensure cluster security.