Add a dedicated read-only token for HCP Consul

This page describes how to create a dedicated read-only token in a self-managed Consul cluster when linking it to HCP Consul. This token enables HCP Consul Central to provide secure access to your Consul deployment without giving HCP access to a token with the cluster's global-management policy attached.

Requirements

Linking a self-manged cluster in read-only mode is supported in Consul v1.14.9, v1.15.5, and v1.16.1 or later. If necessary, upgrade your existing cluster before attempting to link it to HCP.

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.

ACL bootstrap token requirements

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 retrieve the bootstrap token from your the Consul namespace of your Kubernetes Secrets, run the following command:

$ kubectl get secrets/consul-bootstrap-acl-token --template='{{.data.token | base64decode }}' --namespace=consul

When linking clusters to HCP Consul, the ACL bootstrap token is the minimum requirement in order to authorize the API, CLI, and UI interactions detailed on this page. For production-ready environments, we recommend completing the entire process detailed in the Bootstrap and explore Consul's access control system tutorial to fully secure your cluster. This tutorial begins with steps for manually bootstrapping the ACL system by creating the initial management token, and includes instructions for creating UI access tokens.

For a list of software versions required to link a self-managed cluster, refer to Link existing self-managed clusters prerequisites.

Create a read-only ACL token for HCP Consul

To link a self-managed cluster in read-only mode, you must create a read-only ACL token in your Consul cluster and then add the token's SecretID to HCP Consul. You can create a new ACL token and attach Consul's builtin/global-read-only ACL policy using the CLI, HTTP API, or Consul UI. A token with acl:write permissions is required to create a new ACL token.

Refer to view catalog in Consul Enterprise for additional guidance on creating policies and attaching them to tokens. For step-by-step guidance on creating tokens for different uses, refer to the Secure Consul with access control lists (ACLs) tutorial in the Consul documentation.

Issue the following cURL request to create a new ACL token and attach the builtin/global-read-only policy.

$ curl -X PUT http://127.0.0.1:8500/v1/agent/acl/token \
  -H "content-type: application/json" \
  -d "{ "Description": "HCP read-only token", "Policies": [{"Name": "builtin/global-read-only"}], "Local": false }"

The API responds with a JSON payload that contains the token's SecretID.

For more information, including a request body schema, sample payload, and sample response, refer to /agent/acl endpoint in the Consul documentation.

Run the following command to create a new ACL token and attach the builtin/global-read-only policy.

$ consul acl token create -description "HCP read-only token" -policy-name builtin/global-read-only

This command generates output that includes the SecretID of the token associated with the policy.

For more information about creating and viewing ACL tokens using the CLI, refer to consul acl token in the Consul documentation.

To access the server's Consul UI, open http://localhost:8500/ in your web browser.

Complete the following steps to create a new ACL token and attach the builtin/global-read-only policy.

Select Tokens.
Select Create.
Under "Description," enter HCP read-only token.
Under "Policies," in the dropdown menu, select builtin/global-read-only.
Click Save.

After you create your token, the Consul UI returns you to the list of tokens. Find your newly-created token in the list and click it to copy its SecretID to your clipboard.

To create a read-only token in your cluster, use the kubectl exec command to interact with the Consul CLI in the server's container. The following example creates a read-only ACL token in a Consul server named consul-server-0.

$ kubectl exec consul-server-0 --namespace consul -- consul acl token create -description "HCP read-only token" -policy-name builtin/global-read-only -token=<token-with-write-priviliges>

After you copy the SecretID of your dedicated read-only token, you can complete the process to link a self-managed cluster to HCP Consul Central in read-only mode. Refer to Link existing self-managed clusters for more information about the linking process.