> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 사용자 지정 역할을 사용한 RBAC 마이그레이션

> 마이그레이션 마법사를 사용하여 ClickHouse Cloud의 새로운 역할 기반 접근 제어 시스템으로 전환하는 관리자를 위한 가이드

이 가이드는 ClickHouse Cloud에서 관리자 역할을 보유한 사용자를 위한 것입니다.

2026년 6월, ClickHouse Cloud는 새로운 역할 기반 접근 제어(RBAC) 시스템으로 전환했습니다. 조직에 자동으로 마이그레이션할 수 없는 서비스 범위 권한을 가진 멤버 또는 API Key가 있는 경우, 마이그레이션 마법사를 사용해 해당 권한을 새 역할에 매핑합니다. 이 가이드에서는 새 시스템의 작동 방식과 마이그레이션을 완료하는 방법을 설명합니다.

<Warning>
  **가능한 한 빨리 마이그레이션을 완료하십시오**

  마법사와 이메일 알림에 표시된 마감일까지 마이그레이션을 완료하지 않은 조직은 자동으로 마이그레이션됩니다([마이그레이션하지 않으면 어떻게 되나요](#automated-migration) 참조).
</Warning>

<div id="whats-changing">
  ## 변경 사항
</div>

새로운 RBAC 시스템에서는 사용자 지정 역할을 정의하고 더욱 세분화된 접근 제어를 적용할 수 있습니다. 고정된 서비스 범위 권한 집합 대신, 각 역할에 부여된 모든 권한을 확인할 수 있도록 역할을 정의하므로 역할별로 제공되는 액세스 권한을 정확히 파악할 수 있습니다.

역할에는 조직, 서비스, 데이터베이스 권한을 결합할 수 있습니다. 이러한 권한은 모든 서비스와 데이터베이스에 적용하거나 일부에만 적용할 수 있습니다. 전체 권한 목록과 ClickHouse Cloud에 기본 제공되는 표준 역할은 [Console roles and permissions](/docs/ko/products/cloud/reference/security/console-roles)를 참조하십시오. 마이그레이션 후 역할을 생성하고 편집하는 방법은 [사용자 지정 역할 관리](/docs/ko/products/cloud/guides/security/cloud-access-management/manage-custom-roles)를 참조하십시오.

대부분의 권한은 새 모델에 자동으로 매핑됩니다. 직접 매핑할 수 없는 서비스 범위 권한은 마이그레이션 마법사에서 처리를 요청하는 항목입니다.

<div id="migration-wizard">
  ## 마이그레이션 마법사 완료
</div>

마법사는 현재 멤버와 API Key에 부여된 권한을 반영하는 새 역할을 생성하고, 해당 역할을 적절한 멤버와 Key에 할당하도록 안내합니다. 진행 상황은 자동으로 저장되므로 한 세션에서 모두 완료하지 않아도 됩니다.

<Steps>
  <Step title="마이그레이션 마법사 열기" id="open-wizard">
    **Users and roles** 페이지에서 마이그레이션 안내를 따라 마법사를 엽니다. Console에 표시되는 마이그레이션 배너에서도 마법사에 액세스할 수 있습니다.
  </Step>

  <Step title="매핑되지 않은 권한에 대한 역할 생성" id="create-roles">
    마법사에는 서비스 범위 권한을 자동으로 마이그레이션할 수 없었던 멤버와 API Key가 표시됩니다. 이러한 멤버와 Key에 필요한 액세스 권한에 맞는 새 역할을 생성합니다. 권한 범위에 관한 자세한 내용은 [사용자 지정 역할 관리](/docs/ko/products/cloud/guides/security/cloud-access-management/manage-custom-roles)를 참조하십시오.
  </Step>

  <Step title="모든 멤버와 API Key에 역할 할당" id="assign-roles">
    각 멤버, 보류 중인 각 초대, 각 API Key에 최소 1개의 새 역할을 할당합니다. **New role** 컬럼이 비어 있는 멤버, 초대 또는 Key가 하나라도 있으면 제출할 수 없습니다.
  </Step>

  <Step title="최소 한 명의 관리자 유지" id="keep-admin">
    기존 멤버 중 최소 한 명에게 관리자 역할을 할당합니다. 그렇지 않으면 마이그레이션 후 조직의 관리 액세스 권한이 사라지므로, 관리자가 없으면 마법사에서 제출할 수 없습니다.
  </Step>

  <Step title="마이그레이션 제출" id="submit">
    모든 멤버, 초대 및 API Key에 역할이 할당되면 마이그레이션을 제출합니다. 성공하면 **Roles** 탭으로 리디렉션됩니다.
  </Step>
</Steps>

이러한 조건이 충족되기 전에 제출하려고 하면 마법사에서 누락된 항목(역할이 없는 멤버, 역할이 없는 API Key 또는 관리자 부재)을 알려주는 메시지를 표시하므로 해당 항목으로 바로 이동할 수 있습니다.

<div id="automated-migration">
  ## 마이그레이션을 완료하지 않으면 어떻게 되나요
</div>

역할이 의도한 액세스 모델을 반영하도록 가능한 한 직접 마이그레이션을 완료하십시오. 조직에서 제때 마이그레이션을 완료하지 않으면 ClickHouse가 이후 몇 주 내에 자동 마이그레이션을 실행합니다.

자동 마이그레이션은 사용자별로 하나의 사용자 지정 역할을, API Key별로 하나의 사용자 지정 역할을 생성하며, 각 역할에는 해당 사용자 또는 키의 기존 권한이 반영됩니다. 따라서 현재 액세스 수준이 유지되므로 어떤 멤버나 키도 액세스 권한을 잃지 않습니다. 이후 **Roles** 탭에서 이러한 역할을 검토하고 통합할 수 있습니다.

<div id="after-migration">
  ## 마이그레이션 후
</div>

새 역할 시스템과의 호환성을 유지하려면 OpenAPI 및 Terraform 구성을 검토하십시오. 이전 역할을 참조하는 자동화는 업데이트가 필요할 수 있습니다.

Query Endpoints 역할은 Basic service API reader 역할로 전환됩니다. 이전 역할 이름을 사용하는 통합을 업데이트하십시오.

향후 역할 관리에 대한 지침은 [사용자 지정 역할 관리](/docs/ko/products/cloud/guides/security/cloud-access-management/manage-custom-roles) 및 [Cloud 접근 관리](/docs/ko/products/cloud/guides/security/cloud-access-management)를 참조하십시오.