Cluster Access

Capella Operational

concept

Cluster-level role-based access control (RBAC) defines cluster access permissions for programmatic access to your clusters.

Cluster access credentials provide programmatic and application-level access to data on a cluster. These credentials are separate from organization roles and project roles. Your Capella user account’s organization and project roles control your access to the Capella UI, while cluster access credentials control programmatic and application-level access to data.

Cluster access credentials are specific to a cluster and consist of a cluster access name, password, and a set of access levels or roles, depending on the chosen credential type.

Cluster Access Credential Types

The available access credential types are:

Basic access credentials: Read, write, or read/write access at the bucket, scope, and collection level.
Advanced access credentials: Custom combinations of fine-grained privileges and access roles.

When choosing between basic and advanced access credentials, consider the following:

	Basic Access Credentials	Advanced Access Credentials
Availability	All plans	Paid plans only
Access Control	Predefined permission sets: Read Write Read/Write	Fine-grained privileges and custom access roles with precise control over individual operations
Reusability	Permissions configured individually for each credential	Create reusable access roles that you can assign to multiple advanced credentials
Best For	Standard read/write operations Quick setup and deployment Straightforward security requirements	Least-privilege security models Providing specific operation access, such as query only Compliance and audit requirements Standardized access patterns across multiple credentials

Basic Access Credentials

Advanced Access Credentials

Availability

All plans

Paid plans only

Access Control

Predefined permission sets:

Read
Write
Read/Write

Fine-grained privileges and custom access roles with precise control over individual operations

Reusability

Permissions configured individually for each credential

Create reusable access roles that you can assign to multiple advanced credentials

Best For

Standard read/write operations
Quick setup and deployment
Straightforward security requirements

Least-privilege security models
Providing specific operation access, such as query only
Compliance and audit requirements
Standardized access patterns across multiple credentials

You cannot convert basic access credentials to advanced access credentials, or advanced access credentials to basic access credentials. If you need to change credential types, you must create new credentials with the desired type and migrate your applications to use them. A cluster may have both credential types active simultaneously.

Basic Access Credentials

When using basic access credentials, you can assign cluster access credentials on a per-bucket, per-scope, and per-collection basis. For example, you can grant access to all buckets and scopes in a cluster, assign different access levels to individual buckets, or grant access to just a single collection. This system allows you to mix and match access levels to different buckets, scopes, and collections in a cluster to match your application and security requirements.

The following table outlines the access levels available for basic access credentials and their corresponding privileges.

Access Description

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` (granted only when you assign Read access to all buckets) `query_execute_functions` `query_execute_external_functions` `query_use_sequences`
`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` `query_manage_sequences`
`Read/Write`	Grants the privileges of the following Couchbase roles: All the privileges of Read. All the privileges of Write.

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 (granted only when you assign Read access to all buckets)
query_execute_functions
query_execute_external_functions
query_use_sequences

Write

Grants the privileges of the following Couchbase roles:

Read/Write

Grants the privileges of the following Couchbase roles:

All the privileges of Read.
All the privileges of Write.

Advanced Access Credentials

Advanced access credentials use access roles. Access roles are reusable collections of preconfigured privileges applied at the container level, which you can assign to 1 or more advanced cluster credentials.

Advanced access credentials have no predefined access roles, instead you need to create custom access roles for your access requirements. Access roles simplify permission management when multiple users or applications require the same set of privileges. By creating access roles that match common access patterns in your organization, you can:

Maintain consistent security policies across multiple credentials.
Simplify credential management by updating role definitions rather than individual credentials.
Document intended access patterns for different user types or applications.

The following diagram illustrates the relationship between credentials, access roles, and privileges:

Privilege Levels and Data Containers

Each privilege applies at a specific data container level. For example, a global privilege applies across the entire cluster, while a collection-level privilege applies to a specific collection.

Privileges have the following levels:

Global: Applies across all buckets in the entire cluster.
Bucket: Applies to all or specified buckets.
Bucket/Scope: Applies to all or specified scopes within a bucket.
Bucket/Scope/Collection: Applies to all or specified collections within a bucket and scope.

When you assign a non-global privilege, you can choose to use the default and apply it to all data containers at its privilege level or to specific ones. This flexibility lets you implement least-privilege security models tailored to your application architecture.

Privileges for Advanced Access Credentials

The following table lists the available privileges for advanced access credentials, their mapping to Couchbase Server roles, and data container access levels.

Privilege Server Role Access Level

Privilege	Server Role	Access Level
Global
Global Function Execute	`query_execute_global_functions` `query_execute_global_external_functions`	Global
Query Catalog	`query_system_catalog`	Global
Global Function Manage	`query_manage_global_functions` `query_manage_global_external_functions`	Global
Analytics Read	`analytics_reader`	Global
Analytics Admin	`analytics_admin`	Global
Stats Read	`external_stats_reader`	Global
Query Manage Catalog	`query_manage_system_catalog`	Global
Query Curl Access	`query_external_access`	Global
Analytics
Analytics Manage	`analytics_manager`	Bucket
Analytics Select	`analytics_select`	Bucket/Scope/Collection
Data
Data Read	`data_reader` `data_dcp_reader`	Bucket/Scope/Collection
Data Manage	`data_writer`	Bucket/Scope/Collection
Data Monitor	`data_monitoring`	Bucket/Scope/Collection
Eventing
Eventing Manage	`eventing_manage_functions`	Bucket/Scope
Search
FTS Manage	`fts_admin`	Bucket
FTS Read	`fts_searcher`	Bucket/Scope/Collection
Query
Query Insert	`query_insert`	Bucket/Scope/Collection
Query Update	`query_update`	Bucket/Scope/Collection
Query Index	`query_manage_index`	Bucket/Scope/Collection
Query Read	`query_select`	Bucket/Scope/Collection
Query Manage	`query_manage_functions` `query_manage_external_functions`	Bucket/Scope
Query Delete	`query_delete`	Bucket/Scope/Collection
Query Execute	`query_execute_functions` `query_execute_external_functions`	Bucket/Scope
Query Use Sequences	`query_use_sequences`	Bucket/Scope
Query Manage Sequences	`query_manage_sequences`	Bucket/Scope

Global

Global Function Execute

Global

Query Catalog

query_system_catalog

Global

Global Function Manage

Global

Analytics Read

analytics_reader

Global

Analytics Admin