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, and to summarize billing by folder. 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 is assigned a unique ID when it is created, and each folder and cluster has an optional parent ID field, which determines its position in the organization's hierarchy.

• Clusters or folders within a folder have their parent ID set to that folder's ID.
• A cluster or folder created at the root level of the organization has no parent ID. When using the CockroachDB Cloud API, you can either omit the parent ID for a folder or cluster, or set it to root, to create it at or move it to the root level.
• Moving a folder is a lightweight operation that does not modify the folder itself or its descendant folders or clusters; only the folder's parent ID field is updated. Similarly, when moving a cluster into or out of a folder, only the cluster's parent ID field is updated. If you move a folder that contains descendant resources, the descendant resources are not directly modified.

A folder operation may fail if it violates folder naming or folder structure restrictions or if you 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     <-- Too deep, violates folder structure
  

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

Operations that violate these restrictions 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:

• A Folder Admin 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 at the level of the organization, the role grants the ability to view all users and service accounts in the organization. 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.

• A Folder Mover can rename or move descendant folders, and can move clusters within the folder hierarchy where they have the role. However, a Folder Mover cannot create or delete folders or clusters, and cannot assign roles. A Folder Mover 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 Administrator 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 possible to use the ccloud command to view the folder structure, move a cluster or folder into or out of a folder, or assign the FOLDER_ADMIN or FOLDER_MOVER roles.

See also

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