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.

Python

from pymilvus import MilvusClient

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

Java

CreateRoleReq createRoleReq = CreateRoleReq.builder()
        .roleName("role_a")
        .build();
       

NodeJS

client.createRole(createRoleReq);
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

await milvusClient.createRole({
   roleName: 'role_a',
});

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a"
}'

List roles

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

Python

from pymilvus import MilvusClient

client.list_roles()

Java

List<String> roles = client.listRoles();

NodeJS

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

await milvusClient.listRoles(
    includeUserInfo: True
);

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{}'

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 role_a read-only access to all collections in the default database and admin access to collection_01.

Python

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="DatabaseReadOnly"
    collection_name='*'
    db_name='default',
)

Go

import "github.com/milvus-io/milvus-sdk-go/v2/client"

client.GrantV2(context.Background(), "role_a", "collection_01", "COLL_ADMIN", entity.WithOperatePrivilegeDatabase("default"))

client.GrantV2(context.Background(), "role_a", "*", "DatabaseReadOnly", entity.WithOperatePrivilegeDatabase("default"))

Java

import io.milvus.v2.service.rbac.request.GrantPrivilegeReqV2

client.grantPrivilegeV2(GrantPrivilegeReqV2.builder()
        .roleName("role_a")
        .privilege("COLL_ADMIN")
        .collectionName("collection_01")
        .dbName("default")
        .build());

client.grantPrivilegeV2(GrantPrivilegeReqV2.builder()
        .roleName("role_a")
        .privilege("DatabaseReadOnly")
        .collectionName("*")
        .dbName("default")
        .build());

NodeJS

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

const address = "YOUR_CLUSTER_ENDPOINT";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});

await milvusClient.grantPrivilege({
   roleName: 'role_a',
   object: 'Collection', 
   objectName: 'collection_01',
   privilegeName: 'COLL_ADMIN'
 });

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/grant_privilege_v2" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a",
    "privilege": "COLL_ADMIN",
    "collectionName": "collection_01",
    "dbName":"default"
}'

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/grant_privilege_v2" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a",
    "privilege": "DatabaseReadOnly",
    "collectionName": "*",
    "dbName":"default"
}'

Describe a role

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

Python

from pymilvus import MilvusClient

client.describe_role(role_name="role_a")

Go

import "github.com/milvus-io/milvus-sdk-go/v2/client"

client.ListRoles(context.Background())

Java

import io.milvus.v2.service.rbac.response.DescribeRoleResp;
import io.milvus.v2.service.rbac.request.DescribeRoleReq

DescribeRoleReq describeRoleReq = DescribeRoleReq.builder()
        .roleName("role_a")
        .build();
DescribeRoleResp resp = client.describeRole(describeRoleReq);
List<DescribeRoleResp.GrantInfo> infos = resp.getGrantInfos();

NodeJS

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

await milvusClient.describeRole({roleName: 'role_a'});

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/describe" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "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 read-only access to all collections in the default database and admin access to collection_01 from role_a.

Python

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

Go

import "github.com/milvus-io/milvus-sdk-go/v2/client"

client.RevokeV2(context.Background(), "role_a", "collection_01", "COLL_ADMIN", entity.WithOperatePrivilegeDatabase("default"))

client.RevokeV2(context.Background(), "role_a", "*", "ClusterReadOnly", entity.WithOperatePrivilegeDatabase("*"))

Java

import io.milvus.v2.service.rbac.request.RevokePrivilegeReqV2

client.revokePrivilegeV2(RevokePrivilegeReqV2.builder()
        .roleName("role_a")
        .privilege("COLL_ADMIN")
        .collectionName("collection_01")
        .dbName("default")
        .build());

client.revokePrivilegeV2(RevokePrivilegeReqV2.builder()
        .roleName("role_a")
        .privilege("ClusterReadOnly")
        .collectionName("*")
        .dbName("*")
        .build());

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/revoke_privilege_v2" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a",
    "privilege": "COLL_ADMIN",
    "collectionName": "collection_01",
    "dbName":"default"
}'

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/revoke_privilege_v2" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a",
    "privilege": "ClusterReadOnly",
    "collectionName": "*",
    "dbName":"*"
}'

Drop a role

The following example demonstrates how to drop the role role_a.

📘Notes

The built-in role admin cannot be dropped.

Python

from pymilvus import MilvusClient

client.drop_role(role_name="role_a")

Java

import io.milvus.v2.service.rbac.request.DropRoleReq

DropRoleReq dropRoleReq = DropRoleReq.builder()
        .roleName("role_a")
        .build();
client.dropRole(dropRoleReq);

NodeJS

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

milvusClient.dropRole({
   roleName: 'role_a',
 })

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/drop" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "roleName": "role_a"
}'

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

Python

from pymilvus import MilvusClient

client.list_roles()

Java

List<String> resp = client.listRoles();

NodeJS

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")

milvusClient.listRoles(
    includeUserInfo: True
)

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{}'

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

['admin']