Add guide for migrating RBAC with custom roles

docs/cloud/guides/security/01_cloud_access_management/03b_migrating-rbac-custom-roles.md

@@ -0,0 +1,68 @@
+---
+sidebar_label: 'Migrating RBAC with custom roles'
+slug: /cloud/guides/security/migrating-rbac-custom-roles
+title: 'Migrating RBAC with custom roles'
+description: "An administrator's guide to migrating to the new role-based access control system in ClickHouse Cloud using the migration wizard"
+doc_type: 'guide'
+keywords: ['rbac', 'custom roles', 'migration', 'access control', 'permissions', 'security']
+---
+
+This guide is intended for users with the Admin role in ClickHouse Cloud.
+
+In June 2026, ClickHouse Cloud moved to a new role-based access control (RBAC) system. If your organization has members or API keys with service-scoped permissions that can't be migrated automatically, you'll use a migration wizard to map those permissions to new roles. This guide explains how the new system works and how to complete the migration.
+
+:::warning Complete the migration as soon as you can
+Organizations that haven't finished the migration by the deadline shown in the wizard and in your email notifications will be migrated automatically (see [What happens if you don't migrate](#automated-migration)).
+:::
+
+## What's changing {#whats-changing}
+
+The new RBAC system introduces custom role definitions and more granular access control. Instead of a fixed set of service-scoped permissions, you define roles that reveal every permission they grant, so it's clear exactly what access each role provides.
+
+A role can combine organization, service, and database permissions. You can apply those permissions to all of your services and databases, or to a subset. For the full list of permissions and the standard roles that ship with ClickHouse Cloud, see [Console roles and permissions](/cloud/security/console-roles). For instructions on creating and editing roles after you migrate, see [Manage custom roles](/cloud/guides/security/manage-custom-roles).
+
+Most permissions map to the new model automatically. Service-scoped permissions that can't be mapped directly are what the migration wizard asks you to handle.
+
+## Complete the migration wizard {#migration-wizard}
+
+The wizard prompts you to create new roles that reflect the permissions your members and API keys hold today, then assign those roles to the right members and keys. Your progress is saved automatically, so you don't need to finish in a single session.
+
+<VerticalStepper headerLevel="h3">
+
+### Open the migration wizard {#open-wizard}
+
+From the **Users and roles** page, follow the migration prompt to open the wizard. You can also reach it from the migration banner shown in the console.
+
+### Create roles for unmapped permissions {#create-roles}
+
+The wizard lists members and API keys whose service-scoped permissions couldn't be migrated automatically. Create new roles that match the access these members and keys need. See [Manage custom roles](/cloud/guides/security/manage-custom-roles) for details on how permissions are scoped.
+
+### Assign roles to every member and API key {#assign-roles}
+
+Assign at least one new role to each member, each pending invitation, and each API key. Any member, invitation, or key left with a blank **New role** column will block submission.
+
+### Keep at least one Administrator {#keep-admin}
+
+Assign an Admin role to at least one existing member. The wizard won't let you submit without one, because your organization would otherwise lose administrative access after the migration.
+
+### Submit the migration {#submit}
+
+Once every member, invitation, and API key has a role, submit the migration. You'll be redirected to the **Roles** tab on success.
+
+</VerticalStepper>
+
+If you try to submit before these conditions are met, the wizard shows a message identifying what's missing — members without roles, API keys without roles, or a missing Administrator — so you can jump straight to the affected entries.
+
+## What happens if you don't migrate {#automated-migration}
+
+Complete the migration yourself whenever possible so your roles reflect your intended access model. If your organization doesn't finish the migration in time, ClickHouse runs an automated migration in the following weeks.
+
+The automated migration creates one custom role per user and one custom role per API key, each mirroring that user's or key's existing permissions. This preserves everyone's current access level, so no member or key loses access. You can review and consolidate these roles afterward on the **Roles** tab.
+
+## After you migrate {#after-migration}
+
+Review your OpenAPI and Terraform configurations to keep them compatible with the new roles system. Automation that references the old roles may need to be updated.
+
+The Query Endpoints role transitions to the Basic service API reader role. Update any integrations that depend on the previous role name.
+
+For guidance on managing roles going forward, see [Manage custom roles](/cloud/guides/security/manage-custom-roles) and [Cloud access management](/cloud/security/cloud_access_management).

docs/cloud/guides/security/01_cloud_access_management/index.md

@@ -15,6 +15,7 @@ This section contains detailed guides for managing access in ClickHouse Cloud
 | [Manage my account](/cloud/security/manage-my-account) | Describes how to manage your own user account, including passwords, MFA and account recovery |
 | [Manage cloud users](/cloud/security/manage-cloud-users) | An administrator's guide to managing user access in the ClickHouse Cloud console |
 | [Manage custom roles](/cloud/guides/security/manage-custom-roles) | An administrator's guide to creating and managing custom roles |
+| [Migrating RBAC with custom roles](/cloud/guides/security/migrating-rbac-custom-roles) | An administrator's guide to migrating to the new role-based access control system |
 | [Manage SQL console role assignments](/cloud/guides/sql-console/manage-sql-console-role-assignments) | An administrator's guide to managing SQL console users |
 | [Manage database users](/cloud/security/manage-database-users) | An administrator's guide to managing database users |
 | [SAML SSO setup](/cloud/security/saml-setup) | An administrator's guide to configuring and troubleshooting SAML integrations |