Organize CockroachDB Cloud Clusters Using Folders

This page explains how to organize and manage access to your organization's clusters with folders using the CockroachDB Cloud Console. You can also use the CockroachDB Cloud API, or the Terraform provider v1.1.0 or above. For more details about managing access to resources, refer to Managing Users, Roles, and Service Accounts in .

How folders work

Folders allow you to organize and manage access to your clusters according to your organization's requirements. For example, you can create top-level folders for each business unit in your organization, and within those folders, you can organize clusters by geographic location and then by their level of maturity, such as production, staging, and testing. For more details, refer to Folder Structure.

Each folder can contain a mix of folders and clusters. Roles assigned on a folder are inherited by its descendants.

Each folder that you create has an ID. To create a cluster in a folder or to move a cluster into a folder, you set its parent_id field to the folder's ID.

If no parent ID is specified for a cluster, it is created at the root level of the organization. Clusters and folders at the organization level have their parent_id set to root.

To move a folder or a cluster, you update its parent_id. If you move a folder that contains descendant resources, the descendant resources are not directly modified. A folder operation may fail in the following circumstances:

• A naming collision, such as an attempt to move a folder into a location that already contains a folder with the same name. Name collisions are limited to other folders. A folder and cluster at the same level of the hierarchy can share a name.
• A violation of the folder structure limitations.
• An attempt to move a folder into itself or into one of its descendant folders.

Folder naming

• Folder names must begin and end with a letter or number. The only allowed special characters are spaces, hyphens, apostrophes, and underscores.
• Folder names must be at least 3 characters long and cannot exceed 40 characters.

Folder structure

Folders give you the flexibility to organize and manage access to your clusters using the structure that makes the most sense for your organization. Keep the following structural limitations in mind:

• Folders can be nested a maximum of four levels deep, including the root organization level. A folder at the maximum depth can contain only clusters.

  In the following scenario, cluster Cluster B2 is allowed within Subfolder B2, but Subfolder B3 cannot be created, because it is nested too deeply.

  root
    -- Folder A
        -- Subfolder A
    -- Folder B
        -- Subfolder B
          -- Subfolder B2
            -- Cluster B2
            -- Subfolder B3
  

• An organization can have a maximum of 65 folders, regardless of how they are organized.

Operations that violate these limitations result in an error.

Folders and role assignment

A role granted on a folder is inherited on its descendant folders and clusters. All existing organizational roles, such as Cluster Administrator or Cluster Creator, can be granted at the folder scope.

A role granted directly on a cluster is unchanged if the cluster is moved into or out of a folder.

The following roles, when granted at the organization level, allow reading of the entire folder hierarchy:

• Org Administrator
• Cluster Administrator
• Cluster Operator
• Cluster Developer

The following roles allow creation of clusters at the level of the hierarchy where they are granted:

• Cluster Administrator
• Cluster Creator

The following additional roles explicitly allow management of folders and their contents:

• Folder Admins can create, rename, and move, or delete folders where they are granted the role, and they can also manage access to these folders. This role can be granted at the level of the organization or on a specific folder. If granted on a specific folder, the role is inherited by descendant folders.

  A user with the Org Administrator role can grant themselves, another user, or a service account the Folder Admin role.

  To create or manage clusters in a folder, a Folder Admin also needs the Cluster Administrator or Cluster Creator role on that folder directly or by inheritance. To delete a cluster, the Cluster Administrator role is required on the cluster directly or by inheritance.

• Folder Movers can rename or move descendant folders, and can move clusters within the folder hierarchy where they have the role. However, Folder Movers cannot create or delete folders or clusters, and cannot assign roles. Folder Movers can move clusters within the folder hierarchy even if they do not have a role that allows them to connect to the cluster, such as Cluster Creator or Cluster Operator.

  Note:

  A cluster cannot be renamed.

  A user with the Org Administrator or Folder Admin role can grant another user or a service account the Folder Mover role. Because the Folder Admin role is a superset of Folder Mover, there is no need for a Folder Admin to grant themselves the Folder Mover role.

The remainder of this page shows how to create folders, manage access to them, and use them to organize your clusters.

Initial setup

Your user account must have the following roles to manage access to folders:

• Folder Admin

Grant the FOLDER_ADMIN or FOLDER_MOVER role

Folders inherit roles granted higher in the hierarchy, and folders at the root level inherit roles granted at the organization scope. To create a folder, a team member must have the FOLDER_ADMIN role on its parent folder. To create a folder at the root level, a team member must have the FOLDER_ADMIN role at the level of the organization.

To grant the FOLDER_ADMIN role:

1. On the Access Management page, locate the team member's details whose role you want to change.
2. In the row for the target member, click the three-dots Action button and select Edit Roles.
3. Set Scope to Organization or to a folder in the hierarchy. The role is granted on all of the folder's descendants.
4. Set Role to Folder Admin or Folder Mover.
5. Click Confirm.

Create a folder

Your service account must have the following roles on the organization, the folder, or by inheritance:

• Folder Admin

1. Go to the Clusters page. The folders and clusters at the root of the organization are shown.
2. If you have permission to create folders at the root of the organization, the Create folder option is displayed. Click it to create a folder.
3. In Folder name, provide a name for the folder.
4. In Folder location, choose the folder's location. Only locations where you have permission to create folders are shown.
   • To create the folder at the level of the organization, select the organization name.
   • To create the folder within another folder, select the parent folder.
5. Click Create.

Manage access to a folder

1. To manage access to a folder, go to Organization > Access Management.
2. In the row for the target member, click the three-dots Action button and select Edit Roles.
3. Set Scope to the folder you just created. The role is granted on all of the folder's descendants.

4. Set Role to Folder Admin or Folder Mover.

   To access a folder's clusters, a user or service account must also have the Cluster Administrator, Cluster Creator, or Cluster Operator role on the folder. The role may be granted by inheritance or directly on a cluster.

5. Click Confirm.

List folder contents

Your service account must have one of the following roles to read a folder's contents:

• Org Administrator.
• Folder Admin or Folder Mover.
• Cluster Administrator, Cluster Developer, Cluster Creator, or Cluster Operator.

1. To list the clusters and folders at the level of the organization, go to Clusters.
2. To list the clusters and folders in a folder, click the folder name.
3. To view details about a cluster, click the cluster name.

Create a cluster in a folder

Your service account must have the following roles on the organization or the folder:

• Cluster Administrator or Cluster Creator

1. Go to the Clusters page. The folders and clusters at the root of the organization are shown.
2. Browse to the folder where you want to create the cluster.
3. Click Create, then click Create cluster.
   Note:

   If you do not have permission to create folders at this location, you will see only Create cluster.
4. Configure the cluster as desired, then click Create Cluster.
5. To grant others roles directly on the newly-created cluster:
   1. Go to Organization > Access Management.
   2. In the row for the target member, click the three-dots Action button and select Edit Roles.
   3. Set Scope to the folder you just created.
   4. Set Role to the role you want to grant.
   5. Click Confirm.

Move a cluster into or out of a folder

Your service account must have permission to move clusters at both the source and destination locations. This permission is provided by the following roles:

• Folder Admin or Folder Mover

Folder Movers can move clusters within the folder hierarchy even if they do not have a role that allows them to connect to the cluster, such as Cluster Creator or Cluster Operator.

To move a cluster from the organization level into a folder, or to move it from one folder to another:

1. Go to the Clusters page. The folders and clusters at the root of the organization are shown.
2. Browse to the folder that contains the cluster, then click the cluster name to open its details.
3. Click Actions > Move Cluster.
4. In the dialog, select the destination to move the cluster to, then click Next.
5. Click Move.

To move a cluster to a new folder from the Clusters page:

1. Browse to the location of the destination folder.
2. Click the the three-dots Action button, then select Move.

Move a folder into another folder

Your service account must have permission to move folders at both the source and destination locations. This permission is provided by the following roles:

• Folder Admin or Folder Mover

To move a folder and its contents into another folder:

1. Go to the Clusters page. The folders and clusters at the root of the organization are shown.
2. Browse to the location of the folder that you want to move.
3. Next to the folder you want to move, click the three-dots Action button and select Move folder.
4. In the dialog, set Destination to the new location for the folder, then click Next.
5. Click Move.

Delete a folder

Your service account must have the following roles on the organization, the folder, or by inheritance:

• Folder Admin

To delete a folder:

1. Move or delete all descendant folders and clusters.
2. Go to the Clusters page. The folders and clusters at the root of the organization are shown.
3. Browse to the location of the folder that you want to delete.
4. Next to the folder you want to delete, click the three-dots Action button and select Delete folder.
5. Type the name of the folder to confirm, then click Delete.

Limitations

• Folders can be nested a maximum of four levels deep, including the organization level.
• An organization can have a maximum of 65 folders, regardless of how they are organized.
• You can manage folders using the CockroachDB Cloud Console, the CockroachDB Cloud API, or the Terraform provider v1.1.0 or above. It is not yet possible to view the folder structure, move resources, or assign the FOLDER_ADMIN or FOLDER_MOVER roles by using the ccloud command.

See also

• CockroachDB Cloud Access Management (Authorization) Overview
• Manage Users, Roles, and Service Accounts