# CockroachDB Cloud

## Overview

The Veza CockroachDB Cloud integration discovers identity and access information from your CockroachDB Cloud organization, including:

* Organization SCIM-provisioned users and groups
* Service accounts and their API keys
* Organization and folder-scoped role assignments
* Clusters are organized within the folder hierarchy
* Effective permissions across the organization and folder structure

This is a native agent integration that connects to the CockroachDB Cloud API to extract authorization metadata. Veza models the hierarchical organization structure, enabling you to analyze how permissions flow from the organization level through folders to individual clusters.

CockroachDB Cloud uses a hierarchical authorization model where roles assigned at the organization or folder level automatically inherit to child folders and clusters. Veza models this inheritance, showing you the complete effective permissions for each identity across your organization. See [Notes and Supported Entities](#notes-and-supported-entities) for details on what Veza discovers.

After reading this guide, you will understand how to:

* Configure a CockroachDB Cloud service account with API access for Veza
* Connect Veza to your CockroachDB Cloud organization to discover users, groups, service accounts, roles, folders, and clusters
* Understand how Veza models CockroachDB Cloud's hierarchical folder structure and role-based access control

***

## Prerequisites

Before configuring the integration, ensure you have:

* **Network connectivity** from Veza to the CockroachDB Cloud API (`cockroachlabs.cloud`) via:
  * A [deployed Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) in your network (recommended for production)
  * Direct connection using Veza's internal Insight Point (suitable for testing)
* **Organization Administrator access** to create service accounts in CockroachDB Cloud
* A **service account with the Organization Admin role** for API access
* An **API key** for the service account

{% hint style="warning" %}
Only service accounts can authenticate to the CockroachDB Cloud API. Regular user accounts cannot generate API keys for programmatic access.
{% endhint %}

***

## Configuring CockroachDB Cloud

### Creating the Service Account

The Veza integration requires a CockroachDB Cloud service account with an API key. This service account authenticates to the CockroachDB Cloud API to retrieve organization metadata.

1. Log in to the [CockroachDB Cloud Console](https://cockroachlabs.cloud/)
2. Navigate to **Access Management** > **Service Accounts**
3. Click **Create Service Account**
4. Provide a name for the service account (e.g., `veza-integration`)
5. Assign the **Organization Admin** role to the service account at the organization scope
6. Click **Create** and save the generated API key securely

{% hint style="warning" %}
The API key is displayed only once during creation. Store it securely, as you will need it to configure the Veza integration. If you lose the key, you will need to create a new one.
{% endhint %}

### Required Permissions

The integration requires the Organization Admin role to access organization-level metadata through the CockroachDB Cloud API.

| Permission Scope | Role Required      | Purpose                                                                |
| ---------------- | ------------------ | ---------------------------------------------------------------------- |
| Organization     | Organization Admin | Discover users, groups, roles, service accounts, folders, and clusters |

The Organization Admin role provides:

* Read access to organization SCIM users and SCIM groups
* Read access to service accounts and API keys
* Read access to role assignments at organization and folder scopes
* Read access to folders and cluster metadata
* Ability to list all resources within the organization hierarchy

You can test the API key to ensure it has the correct permissions:

```bash
# Test organization access
curl -H "Authorization: Bearer YOUR_SECRET_KEY" \
  https://cockroachlabs.cloud/api/v1/organizations

# Expected: JSON response with organization details
```

***

## Configuring CockroachDB Cloud on the Veza Platform

Add the integration in Veza. See [Configuring Integrations](/4yItIzMvkpAvMVFAamTf/integrations/configuration.md) for detailed steps on adding and configuring integrations.

### Configuration Options

| Field             | Required | Notes                                                                    |
| ----------------- | -------- | ------------------------------------------------------------------------ |
| **Insight Point** | Yes      | Choose whether to use the default data plane or a deployed Insight Point |
| **Name**          | Yes      | A friendly name to identify this integration instance                    |
| **API Key**       | Yes      | The service account API key created in the previous step                 |

After adding the integration, Veza will automatically discover your CockroachDB Cloud organization resources. The integration creates additional data sources for each cluster discovered in your organization.

***

## Notes and Supported Entities

Veza discovers and models the following entity types from CockroachDB Cloud:

* Organization
* User (SCIM-provisioned)
* Group (SCIM-provisioned)
* Service Account
* API Key
* Role
* Role Assignment
* Folder
* Cluster

CockroachDB Cloud implements a hierarchical authorization model where:

* **Organization** is the top-level container for all resources
* **Folders** provide hierarchical organization of clusters (folders can contain other folders)
* **Clusters** are the database instances that can be assigned to folders or directly to the organization
* **Roles** can be assigned at the organization, folder, or cluster scope, with permissions inheriting down the hierarchy

The metadata that Veza collects enables granular queries for search, rules, and workflows. To view discovered properties for an entity, search for it in the Authorization Graph and click **View Details**. You can also view all possible entity properties when filtering in Query Builder or Access Reviews.

### Organization

The top-level container for all CockroachDB Cloud resources within your account.

| Attribute    | Type      | Description                       |
| ------------ | --------- | --------------------------------- |
| `name`       | String    | Organization display name         |
| `created_at` | Timestamp | When the organization was created |

**Relationships:**

* Contains Users, Groups, Service Accounts, Roles, Folders, and Clusters

### User

SCIM-provisioned users within the CockroachDB Cloud organization.

| Attribute          | Type        | Description                                             |
| ------------------ | ----------- | ------------------------------------------------------- |
| `name`             | String      | User's full name                                        |
| `display_name`     | String      | Display name from SCIM provider                         |
| `user_name`        | String      | Username from SCIM provider                             |
| `emails`           | String List | Email addresses associated with the user                |
| `external_id`      | String      | Identifier from external identity provider              |
| `is_active`        | Boolean     | Whether the user account is active in CockroachDB Cloud |
| `created_at`       | Timestamp   | When the user was created                               |
| `last_modified_at` | Timestamp   | When the user was last updated                          |
| `identity_type`    | String      | System field (always `human` for users)                 |

**Notes:**

* Users are provisioned through SCIM integration with an external identity provider
* User accounts are initially assigned the Organization Member role, which provides no permissions by default
* Additional roles must be explicitly assigned at the organization, folder, or cluster scope

### Group

SCIM-provisioned groups that enable role assignment to multiple users.

| Attribute          | Type      | Description                                |
| ------------------ | --------- | ------------------------------------------ |
| `name`             | String    | Group display name                         |
| `external_id`      | String    | Identifier from external identity provider |
| `created_at`       | Timestamp | When the group was created                 |
| `last_modified_at` | Timestamp | When the group was last updated            |

**Notes:**

* Groups support nested membership (groups can contain other groups)
* Role assignments to groups automatically apply to all group members
* Groups are synchronized from external identity providers via SCIM

### Service Account

Non-human identities used for API access and automation.

| Attribute       | Type      | Description                                      |
| --------------- | --------- | ------------------------------------------------ |
| `name`          | String    | Service account name                             |
| `creator_name`  | String    | Name of the user who created the service account |
| `created_at`    | Timestamp | When the service account was created             |
| `identity_type` | String    | Type of identity (non-human)                     |

**Notes:**

* Service accounts authenticate to the Cloud API using API keys
* Role assignments on service accounts apply to all API operations performed using their API keys
* Service accounts cannot access the CockroachDB Cloud Console UI

### API Key

Credentials associated with service accounts for API authentication.

| Attribute       | Type      | Description                  |
| --------------- | --------- | ---------------------------- |
| `name`          | String    | API key name                 |
| `created_at`    | Timestamp | When the API key was created |
| `identity_type` | String    | Type of identity (non-human) |

**Notes:**

* API keys are bearer tokens used in the `Authorization` header for Cloud API requests
* Each API key is linked to exactly one service account

### Role

Predefined sets of permissions that can be assigned at different scopes.

| Attribute     | Type        | Description                                    |
| ------------- | ----------- | ---------------------------------------------- |
| `name`        | String      | Role name (e.g., `ORG_ADMIN`, `CLUSTER_ADMIN`) |
| `permissions` | String List | List of permissions granted by this role       |

CockroachDB Cloud provides the following organization roles:

| Role                      | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `ORG_MEMBER`              | Default role for all users; provides base organization membership |
| `ORG_ADMIN`               | Manage users, service accounts, and role assignments              |
| `BILLING_COORDINATOR`     | Manage billing and payment information                            |
| `CLUSTER_CREATOR`         | Create new clusters and manage own clusters                       |
| `CLUSTER_OPERATOR_WRITER` | Configure and manage cluster operations                           |
| `CLUSTER_ADMIN`           | Full administrative access to clusters                            |
| `CLUSTER_DEVELOPER`       | Read-only access to cluster details and DB Console                |
| `FOLDER_ADMIN`            | Create and manage folders and folder-scoped access                |
| `FOLDER_MOVER`            | Move clusters and folders within the hierarchy                    |

### Role Assignment

Represents the assignment of a role to a user, group, or service account at a specific scope (organization, folder, or cluster).

| Attribute       | Type        | Description                                                      |
| --------------- | ----------- | ---------------------------------------------------------------- |
| `name`          | String      | Name of the assigned role                                        |
| `resource_type` | String      | Scope of the assignment (`ORGANIZATION`, `FOLDER`, or `CLUSTER`) |
| `resource_id`   | String      | ID of the resource where the role is assigned                    |
| `permissions`   | String List | Effective permissions granted by this assignment                 |

**Notes:**

* Role assignments at the organization scope apply to all resources in the organization
* Role assignments at folder scope apply to the folder and all child folders and clusters
* Role assignments at cluster scope apply only to that specific cluster
* Veza models permission inheritance through the hierarchy automatically

### Folder

Organizational containers for grouping clusters and other folders.

| Attribute | Type   | Description                                                        |
| --------- | ------ | ------------------------------------------------------------------ |
| `name`    | String | Folder name                                                        |
| `path`    | String | Full hierarchical path to the folder (e.g., `/production/us-east`) |

**Notes:**

* Folders can contain other folders and clusters, creating a multi-level hierarchy
* Role assignments on folders are inherited by all child folders and clusters
* Folders are used to organize clusters by business unit, environment, region, or other criteria

### Cluster

Metadata about CockroachDB database clusters discovered in the organization.

| Attribute          | Type      | Description                                                      |
| ------------------ | --------- | ---------------------------------------------------------------- |
| `name`             | String    | Cluster name                                                     |
| `cluster_id`       | String    | Unique identifier for the cluster                                |
| `state`            | String    | Current state of the cluster (e.g., `CREATED`, `CREATING`)       |
| `operation_status` | String    | Current operation status                                         |
| `cloud_provider`   | String    | Cloud provider hosting the cluster (e.g., `AWS`, `GCP`, `AZURE`) |
| `cost_center`      | String    | Cost center label for billing                                    |
| `creator_id`       | String    | ID of the user who created the cluster                           |
| `created_at`       | Timestamp | When the cluster was created                                     |
| `updated_at`       | Timestamp | When the cluster was last updated                                |

**Notes:**

* Cluster entities represent the CockroachDB Cloud management metadata
* Cluster metadata includes cloud provider and operational details for cost tracking and compliance

### Permissions and Effective Access

CockroachDB Cloud uses a role-based access control (RBAC) model with hierarchical permission inheritance. Veza maps native CockroachDB Cloud permissions to Effective Permissions, showing the complete access granted through:

* Direct role assignments at organization, folder, or cluster scope
* Group membership (roles assigned to groups apply to all members)
* Service account role assignments
* Hierarchical inheritance (organization roles inherit to folders and clusters; folder roles inherit to child folders and clusters)

#### Permission Mappings by Role

**Organization-Scoped Roles:**

Roles that can be assigned at the organization scope:

| Role                      | Key Permissions                                                | Veza Effective Permissions                                                                            |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `ORG_ADMIN`               | Assign and revoke roles, manage users and service accounts     | Data Create, Data Write, Data Delete, Metadata Create, Metadata Write, Non Data                       |
| `BILLING_COORDINATOR`     | Manage billing                                                 | Non Data                                                                                              |
| `CLUSTER_CREATOR`         | Create clusters, edit/delete own clusters                      | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Metadata Delete |
| `CLUSTER_ADMIN`           | Full cluster administration, manage SQL users, configure SSO   | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data        |
| `CLUSTER_OPERATOR_WRITER` | Configure cluster settings, scale nodes, and manage networking | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data        |
| `CLUSTER_DEVELOPER`       | View cluster details, access DB Console                        | Metadata Read, Non Data                                                                               |
| `FOLDER_ADMIN`            | Create/delete/manage folders, apply roles at folder scope      | Data Create, Data Write, Data Delete, Metadata Create, Metadata Write, Non Data                       |
| `FOLDER_MOVER`            | Move clusters between folders                                  | Metadata Write                                                                                        |

**Folder-Scoped Roles:**

Roles that can be assigned at the folder scope (apply to folder and all child folders/clusters):

| Role                      | Key Permissions                                                | Veza Effective Permissions                                                                            |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `CLUSTER_ADMIN`           | Full cluster administration, manage SQL users, configure SSO   | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data        |
| `CLUSTER_CREATOR`         | Create clusters, edit/delete own clusters                      | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Metadata Delete |
| `CLUSTER_OPERATOR_WRITER` | Configure cluster settings, scale nodes, and manage networking | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data        |
| `CLUSTER_DEVELOPER`       | View cluster details, access DB Console                        | Metadata Read, Non Data                                                                               |
| `FOLDER_ADMIN`            | Create/delete/manage folders, apply roles at folder scope      | Data Create, Data Write, Data Delete, Metadata Create, Metadata Write, Non Data                       |
| `FOLDER_MOVER`            | Move clusters between folders                                  | Metadata Write                                                                                        |

**Cluster-Scoped Roles:**

Roles that can be assigned at the cluster scope (apply only to specific cluster):

| Role                      | Key Permissions                                                | Veza Effective Permissions                                                                     |
| ------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `CLUSTER_ADMIN`           | Full cluster administration, manage SQL users, configure SSO   | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data |
| `CLUSTER_OPERATOR_WRITER` | Configure cluster settings, scale nodes, and manage networking | Data Create, Data Write, Data Delete, Metadata Read, Metadata Write, Metadata Create, Non Data |
| `CLUSTER_DEVELOPER`       | View cluster details, access DB Console                        | Metadata Read, Non Data                                                                        |

**Organization Member Role:**

| Role         | Scope        | Description                                            | Veza Effective Permissions |
| ------------ | ------------ | ------------------------------------------------------ | -------------------------- |
| `ORG_MEMBER` | Organization | Base membership permission; no additional capabilities | Uncategorized              |

#### Permission Inheritance

Veza analyzes the following factors when determining effective permissions:

1. **Organization-Level Role Assignments**: Roles assigned at the organization scope apply to the organization and are inherited by all folders and clusters
2. **Folder-Level Role Assignments**: Roles assigned on a folder apply to that folder and are inherited by all child folders and clusters within the folder hierarchy
3. **Cluster-Level Role Assignments**: Roles assigned directly on a cluster apply only to that specific cluster
4. **Group Membership Inheritance**: Users inherit all role assignments from groups they belong to, including nested group memberships

***

## Additional Resources

* [Official CockroachDB Cloud API Documentation](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api)
* [CockroachDB Cloud Authorization Overview](https://www.cockroachlabs.com/docs/cockroachcloud/authorization)
* [Managing Access in CockroachDB Cloud](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access)
* [Organize Clusters Using Folders](https://www.cockroachlabs.com/docs/cockroachcloud/folders)
* [Configuring Integrations](/4yItIzMvkpAvMVFAamTf/integrations/configuration.md)
* [Access Reviews Scenarios](/4yItIzMvkpAvMVFAamTf/features/access-reviews/scenarios.md)
* [Query Builder Reference](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/cockroachdb-cloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.