Skip to main content
Version: User Guides (BYOC)

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 built-in privilege group to a role​

📘Notes

Currently, Zilliz Cloud only supports creating custom roles with built-in privilege groups. For details about built-in privilege groups, refer to Privileges.

If you need to create custom roles with user-defined privileges and privilege groups, please contact us.

The following example demonstrates how to grant the built-in privilege group COLL_ADMIN to the role role_a.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

client.grant_privilege_v2(
    role_name="role_a",
    privilege="COLL_ADMIN"
    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 built-in privilege group from a role​

The following example demonstrates how to revoke the built-in privilege group COLL_ADMIN that have been granted to the role role_a.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)
   
client.revoke_privilege_v2(
    role_name="role_a",
    privilege="COLL_ADMIN"
    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']