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.
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:
- Unlink the existing cluster from HCP Consul. For details on how to unlink a cluster, refer to Unlink self-managed clusters.
- Delete the token with
HCP Management Tokenin its description field. Do not delete the
Bootstrap Tokenor the
- Create a dedicated read-only token for HCP by following the steps in Add a dedicated read-only token for HCP Consul.
- Re-link the cluster with HCP Consul. Follow the steps to link an existing self-managed cluster to HCP Consul and add the
SecretIDof the dedicated read-only token you created.
You can change a cluster's read-only permissions to allow read/write access using HCP Consul's cluster management tools.
From the HCP Consul overview, click the name of the linked cluster you want to change permissions for.
Click Manage and then Change to read/write mode.
CONFIRMin the text entry field and then click Confirm.
Restart the Consul servers so that the change to read/write mode takes effect. Because the agent has a
cloudconfiguration 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:
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
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.
To rotate HCP Consul's dedicated read-only token, complete the following steps:
- Create a new dedicated read-only token for HCP by following the steps in Add a dedicated read-only token for HCP Consul.
- From the HCP Consul overview, click the name of the linked cluster you want to change permissions for.
- Click Manage and then Update read-only token.
- 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.
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.