Configure Cluster Access Credentials

Capella Operational

Cluster access credentials provide programmatic and application-level access to data on a cluster. Only cluster access credentials can access data.

This page provides information about cluster access credentials and how they work. You’ll also find procedures for creating and managing cluster access credentials for a cluster, allowing you to provide programmatic and application-level access to data.

About Cluster Access Credentials

Cluster access credentials are separate from organization roles. While organization roles control what you can do within an organization, such as creating projects, a cluster access credential is still required to access data on a cluster. Cluster access credentials are also distinct from project roles, but only project members with the Project Owner role can create them.

A cluster access credential is specific to a cluster and consists of a cluster access name, secret, and a set of bucket and scope access levels. It’s required for applications to remotely authenticate on a cluster and access bucket data.

Cluster access credentials are distinct and not associated with a particular user. They do not control access to data tools like the Query tab in the Capella UI.

Cluster Access Credentials and Access

You assign cluster access credentials on a per bucket or per scope basis. For example, you could assign a cluster access credential to access all buckets and scopes in a cluster, assign different access levels to individual buckets, or assign access to just a single scope. This system allows you to mix and match access levels to different buckets and scopes in a cluster to satisfy your application and security requirements.

The following table describes the available bucket access options and their associated privileges.

Table 1. Cluster Access Privileges
Access	Description
`Read`	Grants the privileges of the following Couchbase roles: `data_reader` `data_dcp_reader` `data_monitoring` `fts_searcher` `query_select` `analytics_reader` `query_execute_global_functions` `query_execute_global_external_functions` `analytics_select` `external_stats_reader` ^[1] `query_execute_functions` `query_execute_external_functions` 1. The `external_stats_reader` role is only granted when a cluster access credential is given read access to all buckets in a cluster.
`Write`	Grants the privileges of the following Couchbase roles: `data_writer` `fts_admin` `query_insert` `query_update` `query_delete` `query_manage_index` `replication_target` `analytics_admin` `query_manage_global_functions` `query_manage_global_external_functions` `analytics_manager` `scope_admin` `query_manage_functions` `query_manage_external_functions`
`Read/Write`	Grants the privileges of the following Couchbase roles: All the privileges of Read. All the privileges of Write.

View Cluster Access Credentials

Permissions Required

To view the cluster access credentials for a cluster, you must have any of the following roles for the project containing the cluster:

Only the Project Owner role allows you to create and modify cluster access credentials.

The Cluster Access page lists any existing cluster access credentials for a cluster and allows you to create new ones. To open the Cluster Access page:

Open the cluster’s Settings tab.
1. With the Projects tab in your organization open, click the name of the project you’re working with.
2. Click the name of the cluster that you’re working with.
3. Click the Settings tab.
In the navigation menu, click Cluster Access.

The Cluster Access page is shown for the current cluster:

Cluster Access Summary

The cluster access page is in a table format, with sortable columns and rows for each cluster access credential.

The following information is shown about each cluster access credential:

Cluster Access Name

The name that identifies the cluster access credential.

Created By

The organization user that created the cluster access credential.

Created On

The creation date of the cluster access credential and its age. The color-coded status indicator in this column is based on age to help identify older credentials that need rotation. The colors indicate the following:

Green: Under 90 days old
Yellow: 90—180 days old
Red: Over 180 days old

A Trash icon shown at the end of each row can be used to delete the corresponding cluster access credential.

Create Cluster Access Credentials

Permissions Required

To create a cluster access credential, you must have the Project Owner role for the project containing the cluster where you’re creating the cluster access credential.

Open the Cluster Access page for your cluster:
1. With the Projects tab in your organization open, click the project with the cluster you’re working with.
2. With the Operational tab open, select your cluster.
3. Click the Settings tab.
4. In the navigation menu, click Cluster Access.
Click Create Cluster Access

Specify the cluster access name and secret.

Cluster Access Name

The cluster access name cannot exceed 35 characters in length and can’t contain the following characters: ( ) < > @ , ; : \ " / [ ] ? = { }

Secret

Secrets must be at least eight characters in length. They need one or more uppercase letters, lowercase letters, numbers, and special characters: @ % + \ \ / ' \ " ! # $ ^ ? : , ( ) { } [ ] ~ ` - _

Once you create a cluster access credential, you cannot change the secret. This prevents situations where a credential’s secret is changed in Capella, but not in an application. The best practice to follow when rotating credentials is to:

Create a new cluster access credential in Capella
Update your application to use the new cluster access credential
Delete the old cluster access credential

Select bucket-level access.

In the Bucket Level Access section, use the Bucket drop-down menu to specify a bucket you want this cluster access credential to access To grant access to all current and future buckets in the cluster, choose the All Buckets option.
Select scope-level access

Use the Scope drop-down menu to specify a scope you want this cluster access credential to access. To grant access to all current and future scopes in the selected bucket, choose the All Scopes option.
Select access level.

Use the Access drop-down menu to specify Read, Write, or Read/Write access to the chosen bucket and scope selection.
(Optional) Add another level of access.

Cluster access credentials can access a selection of multiple buckets and scopes within a cluster.
1. Click Add Another.
  
  The Bucket Level Access section adds another line where you can select another bucket and scope for this cluster access credential to access.
Once you have finished making the desired configurations, click Create Cluster Access.

Remember that you cannot use cluster access credentials to log into the Couchbase Capella UI or manage Capella features. Cluster access credentials are used for reading or writing bucket data using the Couchbase SDK and other supported tools.

Modify Cluster Access Credentials

Permissions Required

To modify a cluster access credential, you must have the Project Owner role for the project with the cluster access credential

Open the Cluster Access page for your cluster:
1. With the Projects tab in your organization open, click the project with the cluster you’re working with.
2. With the Operational tab open, select your cluster.
3. Click the Settings tab.
4. In the navigation menu, click Cluster Access.
Click the access name of the cluster access credential you’re modifying.
In the Bucket Level Access section, change any existing levels of access or add more.

See the access selection steps for creating a cluster access credential for details on choosing bucket and scope access levels.
Once you have made your changes, click Apply.

Delete Cluster Access Credentials

Deleting a cluster access credential can cause an application that’s using it to stop functioning. Always make sure that you have updated your application to use new credentials before deleting a cluster access credential.

Permissions Required

To delete a cluster access credential, you must have the Project Owner role for the project with the cluster access credential.

Open the Cluster Access page for your cluster:
1. With the Projects tab in your organization open, click the project with the cluster you’re working with.
2. With the Operational tab open, select your cluster.
3. Click the Settings tab.
4. In the navigation menu, click Cluster Access.
At the end of the row for the cluster access credential that you want to delete, click the Trash icon .

This opens the Delete Cluster Access dialog.
Type delete into the provided field and click Delete Cluster Access.

A small notification indicates that the cluster access credential is deleted.

Manage Cluster Access Credentials with Hashicorp Vault

Our Hashicorp Vault plug-in can serve as a centralized hub for secrets management. In addition to managing existing secrets, Vault’s Cluster Secrets Engine generates dynamic, short-lived cluster access credentials. This streamlines the management of cluster connections and roles, and you can even customize permissions and TTL settings.

Full details can be found on the plug-in site.