Skip to main content
Version: User Guides (Cloud)

Manage Cluster Roles (SDK)

A cluster role defines the privileges that a user has within the cluster. More specifically, the cluster role controls a cluster user's privileges on the cluster, database, and collection level.

This guide walks you through how to create a role, grant built-in privilege groups to a role, revoke privilege groups from a role, and finally drop a role. For details about built-in privilege groups, refer to Privileges.

📘Notes

This feature is exclusively available to Dedicated clusters.

Create a role​

The following example demonstrates how to create a role named role_a.

The role name must follow the following rule:

  • Must start with a letter and can only include uppercase or lowercase letters, numbers, and underscores.
from pymilvus import MilvusClient

client.create_role(role_name="role_a")
import io.milvus.v2.service.rbac.request.CreateRoleReq;

List roles​

After creating several roles, you can list and view all existing roles.

from pymilvus import MilvusClient

client.list_roles()

Below is an example output. role_a is the new role that is just created.

['role_a']

Grant a privilege or a privilege group to a role​

In Zilliz Cloud, you can grant the followings to a role:

  • Privileges: Zilliz Cloud provides various types of privileges. For details, refer to All privileges.

  • Built-in privilege groups: Zilliz Cloud offers 9 built-in privilege groups. For details about the specific privileges included in each built-in privilege group, refer to Built-in privilege groups.

  • Custom privilege groups: If the built-in privileges do not meet your needs, you can combine different privileges to create your own custom privilege groups. For details, refer to Custom privilege groups.

📘Notes

If you need to grant specific privileges and custom privilege groups to a role, please create a support ticket first so that we can enable this feature for you.

The following example demonstrates how to grant the privilege PrivilegeSearch on collection_01 under the default database as well as a custom privilege group named privilege_group_1 to the role role_a.

from pymilvus import MilvusClient

client.grant_privilege_v2(
    role_name="role_a",
    privilege="Search",
    collection_name='collection_01',
    db_name='default',
)
    
client.grant_privilege_v2(
    role_name="role_a",
    privilege="privilege_group_1",
    collection_name='collection_01',
    db_name='default',
)

client.grant_privilege_v2(
    role_name="role_a",
    privilege="ClusterReadOnly",
    collection_name='*',
    db_name='*',
)

Describe a role​

The following example demonstrates how to view the privileges granted to the role role_a using the describe_role method.

from pymilvus import MilvusClient

client.describe_role(role_name="role_a")

Below is an example output.

{
     "role": "role_a",
     "privileges": [
         "COLL_ADMIN"
     ]
}

Revoke a privilege or a privilege group from a role​

The following example demonstrates how to revoke the privilege PrivilegeSearch on collection_01 under the default database as well as the privilege group privilege_group_1 that have been granted to the role role_a.

client.revoke_privilege_v2(
    role_name="role_a",
    privilege="Search",
    collection_name='collection_01',
    db_name='default',
)
    
client.revoke_privilege_v2(
    role_name="role_a",
    privilege="privilege_group_1",
    collection_name='collection_01',
    db_name='default',
)

client.revoke_privilege_v2(
    role_name="role_a",
    privilege="ClusterReadOnly",
    collection_name='*',
    db_name='*',
)

Drop a role​

The following example demonstrates how to drop the role role_a.

📘Notes

The built-in role admin cannot be dropped.

from pymilvus import MilvusClient

client.drop_role(role_name="role_a")

Once the role is dropped, you can list all existing roles to check if the drop operation is successful.

from pymilvus import MilvusClient

client.list_roles()

Below is an example output. There is no role_a in the list. The drop operation is successful.

['admin']