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.
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
- Java
- NodeJS
- cURL
from pymilvus import MilvusClient
client.create_role(role_name="role_a")
import io.milvus.v2.service.rbac.request.CreateRoleReq;
CreateRoleReq createRoleReq = CreateRoleReq.builder()
.roleName("role_a")
.build();
client.createRole(createRoleReq);
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")
await milvusClient.createRole({
roleName: 'role_a',
});
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
- Java
- NodeJS
- cURL
from pymilvus import MilvusClient
client.list_roles()
List<String> roles = client.listRoles();
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")
await milvusClient.listRoles(
includeUserInfo: True
);
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​
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
.
- Python
- Go
- Java
- NodeJS
- cURL
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='*',
)
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", "*", "ClusterReadOnly", entity.WithOperatePrivilegeDatabase("*"))
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("ClusterReadOnly")
.collectionName("*")
.dbName("*")
.build());
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 --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": "ClusterReadOnly",
"collectionName": "*",
"dbName":"*"
}'
Describe a role​
The following example demonstrates how to view the privileges granted to the role role_a
using the describe_role
method.
- Python
- Go
- Java
- NodeJS
- cURL
from pymilvus import MilvusClient
client.describe_role(role_name="role_a")
import "github.com/milvus-io/milvus-sdk-go/v2/client"
client.ListRoles(context.Background())
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();
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")
await milvusClient.describeRole({roleName: 'role_a'});
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 built-in privilege group COLL_ADMIN
that have been granted to the role role_a
.
- Python
- Go
- Java
- cURL
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='*',
)
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("*"))
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 --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
.
The built-in role admin
cannot be dropped.
- Python
- Java
- NodeJS
- cURL
from pymilvus import MilvusClient
client.drop_role(role_name="role_a")
import io.milvus.v2.service.rbac.request.DropRoleReq
DropRoleReq dropRoleReq = DropRoleReq.builder()
.roleName("role_a")
.build();
client.dropRole(dropRoleReq);
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")
milvusClient.dropRole({
roleName: 'role_a',
})
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
- Java
- NodeJS
- cURL
from pymilvus import MilvusClient
client.list_roles()
List<String> resp = client.listRoles();
const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")
milvusClient.listRoles(
includeUserInfo: True
)
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']