版本：Cloud 开发指南

管理集群角色（SDK）

集群角色定义了用户在集群内的权限。具体而言，集群角色控制集群用户在集群、Database 和 Collection 层级的权限。

本文将介绍如何创建角色、将内置权限组授予角色、撤销授予角色的权限组，以及删除角色。有关内置权限组的详细信息，请参考权限。

📘说明

此功能仅限 Dedicated 集群使用。

创建角色

以下示例展示了如何创建一个角色 role_a。

角色名称必须以字母开头且只可以包含大写或小写字母、数字和下划线。

Python
Java
NodeJS
cURL

from pymilvus import MilvusClient

client.create_role(role_name="role_a", description="a cluster read only role")

import io.milvus.v2.service.rbac.request.CreateRoleReq;
CreateRoleReq createRoleReq = CreateRoleReq.builder()
        .roleName("role_a")
        .description("a cluster read only role")
        .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",
    "description": "a cluster read only role"
}'

查看所有角色

在创建了多个角色后，您可以查看所有已创建的角色列表。

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 '{}'

示例结果如下，role_a 为新创建的角色。

['role_a']

为角色分配权限组

在 Zilliz Cloud 中，你可以为一个角色分配如下权限：

内置权限组：Zilliz Cloud 提供了九种内置权限组。关于每种内置权限组中包含哪些权限，可以参考内置权限组。
自定义权限组：如果内置权限组不能满足您的需要，您也可以通过将多个权限组合的方式创建自定义权限组。更多详情，可参考自定义权限组。

📘说明

如需为角色分配自定义权限组，请联系我们开通功能。
Milvus 2.5 及以上版本的集群不再支持为角色分配单个权限。

以下示例展示了如何为角色 role_a 分配在 default Database 中的名为 collection_01 的 Collection 中的 PrivilegeSearch 权限及名为 privilege_group_1 的自定义权限组。

Python
Java
Go
NodeJS
cURL

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

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

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

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

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "https://{cluster-id}.{region}.vectordb.zilliz.com.cn:19530",
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

err = client.GrantV2(ctx, milvusclient.NewGrantV2Option("role_a", "privilege_group_1", "default", "collection_01"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

err = client.GrantV2(ctx, milvusclient.NewGrantV2Option("role_a", "ClusterReadOnly", "*", "*"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

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

const address = "https://{cluster-id}.{region}.vectordb.zilliz.com.cn:19530";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});

await client.grantPrivilegeV2({
    role: "role_a",
    privilege: "privilege_group_1"
    collection_name: 'collection_01'
    db_name: 'default',
});

await client.grantPrivilegeV2({
    role: "role_a",
    privilege: "ClusterReadOnly"
    collection_name: '*'
    db_name: '*',
});

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": "privilege_group_1",
    "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":"*"
}'

以下是参数及其说明：

role_name：需要授予权限组的目标角色名称。
privilege：需要授予该角色的权限组。可选的参数值请参考权限与权限组

Resource：权限组对应的目标资源，可以是指定的集群、Database 或 Collection。

下表说明了如何指定资源。

层级	资源	Grant Method	Notes
Collection	指定 Collection	`client.grant_privilege_v2( role_name="roleA", privilege="CollectionAdmin", collection_name="col1", db_name="db1" )`	输入目标 Collection 的名称，以及该 Collection 所属 Database 的名称。
Collection	当前 Database 下所有 Collection	`client.grant_privilege_v2( role_name="roleA", privilege="CollectionAdmin", collection_name="*", db_name="db1" )`	输入目标 Database 的名称，并将 Collection 名称设置为通配符 `*`。
Database	指定 Database	`client.grant_privilege_v2( role_name="roleA", privilege="DatabaseAdmin", collection_name="*", db_name="db1" )`	输入目标 Database 的名称，并将 Collection 名称设置为通配符 `*`。
Database	当前集群下所有 Database	`client.grant_privilege_v2( role_name="roleA", privilege="DatabaseAdmin", collection_name="", db_name="" )`	将 Database 名称和 Collection 名称都设置为通配符 `*`。
集群	当前集群	`client.grant_privilege_v2( role_name="roleA", privilege="ClusterAdmin", collection_name="", db_name="" )`	将 Database 名称和 Collection 名称都设置为通配符 `*`。

查看角色权限

以下示例展示如何查看角色 role_a 的权限。

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"
}'

示例结果如下:

{
     "role": "role_a",
     "descripton": "a cluster read only role",
     "privilege": "ClusterReadOnly"
}

撤销为角色分配的权限组

以下示例展示了如何撤销已分配给角色 role_a 的 privilege_group_1 自定义权限组和内置权限组 ClusterReadOnly。

Python
Java
Go
NodeJS
cURL

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

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

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

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

err = client.RevokePrivilegeV2(ctx, milvusclient.NewRevokePrivilegeV2Option("role_a", "privilege_group_1", "collection_01").
    WithDbName("default"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

err = client.RevokePrivilegeV2(ctx, milvusclient.NewRevokePrivilegeV2Option("role_a", "ClusterReadOnly", "*").
    WithDbName("*"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

await client.revokePrivilegeV2({
    role: 'role_a',
    collection_name: 'collection_01',
    privilege: 'Search',
    db_name: 'default'
});

await client.revokePrivilegeV2({
    role: 'role_a',
    collection_name: '*',
    privilege: 'ClusterReadOnly',
    db_name: '*'
});

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": "Search",
    "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":"*"
}'

删除角色

以下示例展示了如何删除角色 role_a。

📘说明

内置的 admin 角色无法删除。

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"
}'

删除后，您可以通过查看所有角色操作检查是否删除成功。如果列表中未展示此前删除的角色则视为删除成功。

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 '{}'

示例结果如下，列表中无角色 role_a，删除操作成功。

['admin']

创建角色​

查看所有角色​

为角色分配权限组​

查看角色权限​

撤销为角色分配的权限组​

删除角色​