Clean up the Cloud Console roles topic #19758

jhlodin · 2025-06-11T21:20:46Z

Create a table describing roles and privileges at a high level, based on internal guidance
Reword the language used on the cloud console auth page to be more consistent
Correct usage of "Org Administrator" and "Cluster Administrator" to reflect the role names in the console, which are "Organization Admin" and "Cluster Admin" respectively
Disambiguate between Cloud Console roles and SQL User roles:
- Cloud Console roles are "assigned" and give "permissions". Arbitrary terms, discussed with @mikeCRL
- SQL User roles are "granted" and give "privileges". Specific terms associated with GRANT and related SQL statements

github-actions · 2025-06-11T21:21:08Z

Files changed:

src/current/_includes/cockroachcloud/backups/cloud-api-get-put.md:

src/current/_includes/cockroachcloud/cluster-operator-prereq.md:

src/current/cockroachcloud/network-authorization.md

src/current/_includes/cockroachcloud/cockroachcloud-ask-admin.md:

src/current/cockroachcloud/managing-access.md
src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md
src/current/_includes/cockroachcloud/create-a-sql-user.md:

Warning: include not used in any cockroachcloud file or include

Warning: include not used in any cockroachcloud file or include

src/current/_includes/cockroachcloud/first-org-user-roles.md:

src/current/cockroachcloud/authorization.md

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md:

src/current/_includes/cockroachcloud/org-roles/folder-admin.md:

src/current/_includes/cockroachcloud/org-roles/folder-mover.md:

src/current/advisories/c20230118.md
src/current/cockroachcloud/alerts-page.md
src/current/cockroachcloud/authorization.md
src/current/cockroachcloud/aws-privatelink.md
src/current/cockroachcloud/ccloud-faq.md
src/current/cockroachcloud/change-plan-between-basic-and-standard.md
src/current/cockroachcloud/client-certs-advanced.md
src/current/cockroachcloud/cloud-api.md
src/current/cockroachcloud/cloud-org-audit-logs.md
src/current/cockroachcloud/cloud-org-sso.md
src/current/cockroachcloud/configure-cloud-org-sso.md
src/current/cockroachcloud/configure-scim-provisioning.md
src/current/cockroachcloud/connect-to-a-basic-cluster.md
src/current/cockroachcloud/connect-to-an-advanced-cluster.md
src/current/cockroachcloud/connect-to-your-cluster.md
src/current/cockroachcloud/create-a-basic-cluster.md
src/current/cockroachcloud/create-an-account.md
src/current/cockroachcloud/create-an-advanced-cluster.md
src/current/cockroachcloud/create-your-cluster.md
src/current/cockroachcloud/databases-page.md
src/current/cockroachcloud/egress-perimeter-controls.md
src/current/cockroachcloud/export-logs-advanced.md
src/current/cockroachcloud/export-logs.md
src/current/cockroachcloud/export-metrics-advanced.md
src/current/cockroachcloud/folders.md
src/current/cockroachcloud/free-trial.md
src/current/cockroachcloud/labels.md
src/current/cockroachcloud/managed-backups-advanced.md
src/current/cockroachcloud/managing-access.md
src/current/cockroachcloud/migrations-page.md
src/current/cockroachcloud/organization-audit-logs-in-cloud-console.md
src/current/cockroachcloud/plan-your-cluster-basic.md
src/current/cockroachcloud/production-checklist.md
src/current/cockroachcloud/quickstart.md
src/current/cockroachcloud/sql-shell.md
src/current/cockroachcloud/upgrade-policy.md
src/current/releases/cloud.md
src/current/v23.1/security-reference/authorization.md
src/current/v23.2/security-reference/authorization.md
src/current/v24.1/security-reference/authorization.md
src/current/v24.2/security-reference/authorization.md
src/current/v24.3/security-reference/authorization.md
src/current/v25.1/security-reference/authorization.md
src/current/v25.2/security-reference/authorization.md
src/current/v25.3/security-reference/authorization.md

netlify · 2025-06-11T21:21:10Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`53b29cd`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/6852cea82a59670008488ada

netlify · 2025-06-11T21:21:11Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`53b29cd`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6852cea8c73dd600086d3fd3

netlify · 2025-06-11T21:30:05Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`53b29cd`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6852cea8d2306c0008ae91de
😎 Deploy Preview	https://deploy-preview-19758--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

jhlodin · 2025-06-12T20:02:39Z

Screenshot showing how the table renders. Note that it currently requires horizontal scrolling on browser windows smaller than fullscreen 1920x1080 which may not be acceptable.

jaiayu · 2025-06-17T02:29:30Z

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md

+| `Folder` | Applies to clusters within a specific folder. Only available as a selectable scope if folders have been created within the organization by a user with the `Folder Admin` role | `Cluster Creator`, `Cluster Admin`, `Folder Admin`, `Folder Mover` |
+| `Cluster` | Applies to a specific cluster | `Cluster Admin`, `Cluster Operator`, `Cluster Developer` |
+
+{% if page.name != 'authorization.md' %}For more information on these roles and the specific permissions given, see [Organization user roles]({% link cockroachcloud/authorization.md %}#organization-member).{% endif %}


@biplav-crl can you review these roles and permissions and ensure they are correct?

We need to add which roles can do cluster upgrade/downgrade. Additionally, add PCR whenever we add documentation for PCR. Mention about Terraform for Cluster Creator/Admin. Also bring in details for ccloud. I see network auth, but calling our create private clusters, egress perimeter control would be a good idea. Also, linking these operation to relevant documentation pages will add value.

I was unable to review the pages and have just reviewed the table. Apart from above feedback comments, rest LGTM.

We must ideally create a similar table for Cloud Console API's. Categories might be similar but listing our APIs instead of permission might be a good idea.

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md

mikeCRL

LGTM. I'd like us to look at iterating on the table styles but that can happen in a follow up. Perhaps an issue for Ed Infra?

src/current/_includes/cockroachcloud/cockroachcloud-ask-admin.md

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md

src/current/_includes/cockroachcloud/cluster-operator-prereq.md

src/current/cockroachcloud/managing-access.md

jaiayu · 2025-06-17T20:27:15Z

src/current/_includes/cockroachcloud/cockroachcloud-ask-admin.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_info}}
-Only [Org Administrators]({% link cockroachcloud/authorization.md %}#org-administrator) and [Cluster Administrators]({% link cockroachcloud/authorization.md %}#cluster-administrator) can create SQL users and issue credentials.
+Only [Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) and [Cluster Admins]({% link cockroachcloud/authorization.md %}#cluster-admin) can create SQL users using the {{site.data.products.cloud}} Console or API. These SQL users default to the `Admin` role. For granular provisioning of SQL user privileges, refer to documentation on [using the cluster's SQL interface]({% link cockroachcloud/managing-access.md %}?filters=client#create-a-sql-user).


@biplav-crl can you confirm if org admins can create SQL users? I don't think you can via console.

The Organization Admin cannot create the SQL users.

jaiayu · 2025-06-17T20:47:11Z

src/current/advisories/c20230118.md

@@ -31,13 +31,13 @@ All users assigned the Developer role in a CockroachDB Cloud organization will n

 See [Role Options](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/alter-user#{% if site.current_cloud_version == "v22.1" %}parameters{% else %}role-options{% endif %}) for more information on these roles.

-The users assigned the [org admin role](https://www.cockroachlabs.com/docs/cockroachcloud/authorization#org-administrator) in a CockroachDB Cloud organization will continue to access the relevant pages in Cloud Console using an underlying per-cluster [SQL admin user](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/security-reference/authorization#admin-role), as it is intended to be an all-access, highly privileged role.
+The users assigned the [Organization Admin role](https://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-admin) in a CockroachDB Cloud organization will continue to access the relevant pages in Cloud Console using an underlying per-cluster [SQL admin user](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/security-reference/authorization#admin-role), as it is intended to be an all-access, highly privileged role.


@biplav-crl to confirm if this is true

I would have to read the complete page to comment effectively on this. Based on what is here this does not look right. Can you please deploy these changes for me to review?

biplav-crl · 2025-06-18T07:40:36Z

I have reviewed the table and left my comments above. For any remaining changes, will have to look at a deployed version. Thx.

jhlodin · 2025-06-18T14:47:24Z

I have reviewed the table and left my comments above. For any remaining changes, will have to look at a deployed version. Thx.

@biplav-crl Deploy preview can be found here - https://deploy-preview-19758--cockroachdb-docs.netlify.app/docs/cockroachcloud/authorization

rmloveland

LGTM from the narrow POV of the terminology change to:

Cloud users are "assigned" "permissions"
SQL users are "granted" "privileges"

I think this is a huge improvement in clarity!

@jhlodin is there any chance you'd PR a new 'Controlled Vocabulary' section in our Style Guide and add this terminology there?

rmloveland · 2025-06-18T19:00:57Z

src/current/v23.2/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence here (and I think in the other versions of vXX.Y/security-reference/authorization.md

rmloveland · 2025-06-18T19:01:57Z

src/current/v24.1/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence i think (eyes crossing from close reading thru this PR so double check me on this 🩻 )

rmloveland · 2025-06-18T19:02:14Z

src/current/v24.2/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence

rmloveland · 2025-06-18T19:02:30Z

src/current/v24.3/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence

rmloveland · 2025-06-18T19:02:47Z

src/current/v25.1/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence

rmloveland · 2025-06-18T19:03:00Z

src/current/v25.2/security-reference/authorization.md

@@ -7,9 +7,9 @@ docs_area: reference.security

 Authorization, generally, is the control over **who** (users/roles) can perform **which actions** (e.g read, write, update, delete, grant, etc.) to **which resources or targets** (databases, functions, tables, clusters, schemas, rows, users, jobs, etc.).

-This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} users on CockroachDB {{ site.data.products.cloud }} organizations.
+This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This page describes authorization of SQL users on particular [CockroachDB database clusters]({% link {{ page.version.version }}/architecture/glossary.md %}#cluster). This is distinct from authorization of CockroachDB {{ site.data.products.cloud }} Console users on CockroachDB {{ site.data.products.cloud }} organizations.


doubled sentence

jhlodin · 2025-06-20T16:21:35Z

Convo with Ayushi:

Should probably move from Cloud Console roles to "Cloud roles", because some of those roles grant privileges not specific to the console. such as Billing roles using the Billing API.
Validated that the two types of roles are completely independent.

jhlodin marked this pull request as ready for review June 12, 2025 19:54

jhlodin requested review from mikeCRL, kannanlakshmi and jaiayu June 13, 2025 19:47

jhlodin changed the title ~~Add table describing cloud console roles~~ Clean up the Cloud Console roles topic Jun 16, 2025

jhlodin force-pushed the jl/doc-12238 branch 2 times, most recently from 7cb8e59 to e86347f Compare June 16, 2025 17:40

jaiayu reviewed Jun 17, 2025

View reviewed changes

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md Outdated Show resolved Hide resolved

jaiayu reviewed Jun 17, 2025

View reviewed changes

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md Outdated Show resolved Hide resolved

jaiayu reviewed Jun 17, 2025

View reviewed changes

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md Show resolved Hide resolved

mikeCRL approved these changes Jun 17, 2025

View reviewed changes

jaiayu reviewed Jun 17, 2025

View reviewed changes

rmloveland self-requested a review June 18, 2025 14:33

jhlodin added 9 commits June 18, 2025 10:34

Add table describing cloud console roles

d93a043

Edit cloud access management page for consistent language

9009cec

Correct wrong role names

283a283

Correct wording

b812c5f

Clean up passive verbiage

1f4ce2a

Remove usage of grant and privileges for Console roles, clarify wording

9bacbc9

Finish disassociating 'grant' and 'privilege' from console roles

85867fc

Ayushi feedback

efbaf0d

Mike feedback

53b29cd

jhlodin force-pushed the jl/doc-12238 branch from 31a3752 to 53b29cd Compare June 18, 2025 14:35

rmloveland approved these changes Jun 18, 2025

View reviewed changes

Clean up the Cloud Console roles topic #19758

Are you sure you want to change the base?

Clean up the Cloud Console roles topic #19758

Uh oh!

Conversation

jhlodin commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

jhlodin commented Jun 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikeCRL left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

biplav-crl commented Jun 18, 2025

Uh oh!

jhlodin commented Jun 18, 2025

Uh oh!

rmloveland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhlodin commented Jun 20, 2025

Uh oh!

Uh oh!

jhlodin commented Jun 11, 2025 •

edited

Loading

github-actions bot commented Jun 11, 2025 •

edited

Loading

netlify bot commented Jun 11, 2025 •

edited

Loading

netlify bot commented Jun 11, 2025 •

edited

Loading

netlify bot commented Jun 11, 2025 •

edited

Loading