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 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", description="a cluster read only role")

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

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

  • 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 custom privilege groups to a role, please create a support ticket so that we can enable this feature for you.

  • For clusters running Milvus 2.5.x or later, individual privileges are no longer supported.

The following example demonstrates how to grant a custom privilege group named privilege_group_1 and a built-in privilege group ClusterReadOnly to the role role_a.

from pymilvus import MilvusClient

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='*',
)

The following are the parameters and corresponding explanations.

  • role_name: The name of the target role to which privilege group(s) need to be granted.

  • privilege: The privilege group to grant to the role. For the available options, see Privileges & Privilege Groups

  • Resource: The target resource of a privilege group, which can be a specific cluster, database, or collection.

    The following table explains how to specify the resource.

    Level

    Resource

    Grant Method

    Notes

    Collection

    A specific collection

     client.grant_privilege_v2(     role_name="roleA",      privilege="CollectionAdmin",     collection_name="col1",      db_name="db1" )

    Input the name of your target collection and the name of the database to which the target collection belongs.

    All collections under a specific database

     client.grant_privilege_v2(     role_name="roleA",      privilege="CollectionAdmin",     collection_name="*",      db_name="db1" )

    Input the name of your target database and a wildcard * as the collection name.

    Database

    A specific database

     client.grant_privilege_v2(     role_name="roleA",      privilege="DatabaseAdmin",      collection_name="*",      db_name="db1" )

    Input the name of your target database and a wildcard * as the collection name.

    All databases under the current instance

     client.grant_privilege_v2(     role_name="roleA",      privilege="DatabaseAdmin",      collection_name="*",      db_name="*" )

    Input * as the database name and * as the collection name.

    Instance

    The current instance

     client.grant_privilege_v2(     role_name="roleA",      privilege="ClusterAdmin",      collection_name="*",      db_name="*" )

    Input * as the database name and * as the collection 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",
     "descripton": "a cluster read only role",
     "privilege": "ClusterReadOnly"
}

Revoke a privilege group from a role​

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

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']