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. For details on how to unlink a cluster, refer to Unlink self-managed 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.
4. Re-link the cluster with HCP Consul. Follow the steps to link an existing self-managed cluster to HCP Consul 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's cluster management tools.

1. From the HCP Consul 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
   

   Copy

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

   $ consul leave -token=<TOKEN>
   

   Copy

   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>
   

   Copy

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

Update read-only token

To rotate HCP Consul'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.
2. From the HCP Consul 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 cluster.

Best practices

We recommend following these security best practices when managing HCP Consul's access tokens.

• After granting read/write access to HCP Consul, 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 cluster to HCP Consul. A dedicated token helps you track which requests came from HCP Consul. Refer to audit logging in the Consul documentation for more information.
• After unlinking a read-only cluster, HCP Consul's dedicated read-only token is no longer used. Delete unneccessary ACL tokens from your self-managed cluster to ensure cluster security.