Grant Privilege or Privilege Group to Roles

Once a role is created, you can grant privileges to the role. This guide introduces how to grant privileges or privilege groups to a role.

Grant a privilege or a privilege group to a role

Milvus 2.5 introduces a new version of API which streamlines the grant operation. You no longer need to look up the object type when granting a privilege to a role. The following are the parameters and corresponding explanations.

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

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

The following table explains how to specify the resource in the client.grantV2() method.

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

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

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

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

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

• Privilege: The specific privilege or privilege group that you need to grant to a role. Currently, Milvus provides 56 types of privileges that you can grant. The table below lists the privileges in Milvus.

  The type column in the table below are user to facilitate your quick lookup for privileges and is used for classification purposes only. When granting privileges, you do not need to understand the types. You just need to input the corresponding privileges.

  Type	Privilege	Description	Relevant API description on the client side
  Database Privileges	ListDatabases	View all databases in the current instance	ListDatabases
  	DescribeDatabase	View the details of a database	DescribeDatabase
  	CreateDatabase	Create a database	CreateDatabase
  	DropDatabase	Drop a database	DropDatabase
  	AlterDatabase	Modify the properties of a database	AlterDatabase
  Collection Privileges	GetFlushState	Check the status of the collection flush operation	GetFlushState
  	GetLoadState	Check the load status of a collection	GetLoadState
  	GetLoadingProgress	Check the loading progress of a collection	GetLoadingProgress
  	ShowCollections	View all collections with collection privileges	ShowCollections
  	ListAliases	View all aliases of a collection	ListAliases
  	DescribeCollection	View the details of a collection	DescribeCollection
  	DescribeAlias	View the details of an alias	DescribeAlias
  	GetStatistics	Obtain the statistics of a collection (eg. The number of entities in a collection)	GetCollectionStatistics
  	CreateCollection	Create a collection	CreateCollection
  	DropCollection	Drop a collection	DropCollection
  	Load	Load a collection	LoadCollection/GetLoadingProgress/GetLoadState
  	Release	Release a collection	ReleaseCollection
  	Flush	Persist all entities in a collection to a sealed segment. Any entity inserted after the flush operation will be stored in a new segment.	Flush/GetFlushState
  	Compaction	Manually trigger compaction	Compact
  	RenameCollection	Rename a collection	RenameCollection
  	CreateAlias	Create an alias for a collection	CreateAlias
  	DropAlias	Drop the alias of a collection	DropAlias
  	FlushAll	Flush all collections in a database	FlushAll
  Partition Privileges	HasPartition	Check whether a partition exists	HasPartition
  	ShowPartitions	View all partitions in a collection	ShowPartitions
  	CreatePartition	Create a partition	CreatePartition
  	DropPartition	Drop a partition	DropPartition
  Index Privileges	IndexDetail	View the details of an index	DescribeIndex/GetIndexState/GetIndexBuildProgress
  	CreateIndex	Create an index	CreateIndex
  	DropIndex	Drop an index	DropIndex
  Resource Management Privileges	LoadBalance	Achieve load balance	LoadBalance
  	CreateResourceGroup	Create a resource group	CreateResourceGroup
  	DropResourceGroup	Drop a resource group	DropResourceGroup
  	UpdateResourceGroups	Update a resource group	UpdateResourceGroups
  	DescribeResourceGroup	View the details of a resource group	DescribeResourceGroup
  	ListResourceGroups	View all resource groups of the current instance	ListResourceGroups
  	TransferNode	Transfer nodes between resource groups	TransferNode
  	TransferReplica	Transfer replicas between resource groups	TransferReplica
  	BackupRBAC	Create a backup for all RBAC related operations in the current instance	BackupRBAC
  	RestoreRBAC	Restore a backup of all RBAC related operations in the current instance	RestoreRBAC
  Entity Privileges	Query	Conduct a query	Query
  	Search	Conduct a search	Search
  	Insert	Insert entities	Insert
  	Delete	Delete entities	Delete
  	Upsert	Upsert entities	Upsert
  	Import	Bulk insert or import entities	BulkInsert/Import
  RBAC Privileges	CreateOwnership	Create a user or a role	CreateUser/CreateRole
  	UpdateUser	Update the password of a user	UpdateCredential
  	DropOwnership	Drop a user password or a role	DeleteCredential/DropRole
  	SelectOwnership	View all users that are granted a specific role	SelectRole/SelectGrant
  	ManageOwnership	Manage a user or a role or grant a role to a user	OperateUserRole/OperatePrivilege/OperatePrivilegeV2
  	SelectUser	View all roles granted to a user	SelectUser
  	CreatePrivilegeGroup	Create a privilege group	CreatePrivilegeGroup
  	DropPrivilegeGroup	Drop a privilege group	DropPrivilegeGroup
  	ListPrivilegeGroups	View all privilege groups in the current instance	ListPrivilegeGroups
  	OperatePrivilegeGroup	Add privileges to or remove privileges from a privilege group	OperatePrivilegeGroup

The following example demonstrates how to grant the privilege PrivilegeSearch on collection_01 under the default database as well as a privilege group named privilege_group_1 to the role role_a.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

client.grant_privilege_v2(
    role_name="role_a",
    privilege="Search",
    collection_name='collection_01',
    db_name='default',
)
    
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("Search")
        .collectionName("collection_01")
        .dbName("default")
        .build());

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: "localhost:19530",
    APIKey:  "root:Milvus",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

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

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 = "http://localhost:19530";
const token = "root:Milvus";
const client = new MilvusClient({address, token});

await client.grantPrivilegeV2({
    role: "role_a",
    privilege: "Search"
    collection_name: 'collection_01'
    db_name: 'default',
});
    
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": "Search",
    "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": "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":"*"
}'

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")

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();

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

role, err := client.DescribeRole(ctx, milvusclient.NewDescribeRoleOption("role_a"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

await client.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": [
         {
             "collection_name": "collection_01",
             "db_name": "default",
             "role_name": "role_a",
             "privilege": "Search",
             "grantor_name": "root"
         },
         "privilege_group_1"
     ]
}

Revoke a privilege or a privilege group from a role

The following example demonstrates how to revoke the privilege PrivilegeSearch on collection_01 under the default database as well as the privilege group privilege_group_1 that have been granted to the role role_a.

client.revoke_privilege_v2(
    role_name="role_a",
    privilege="Search",
    collection_name='collection_01',
    db_name='default',
)
    
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("Search")
        .collectionName("collection_01")
        .dbName("default")
        .build());

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", "Search", "collection_01").
        WithDbName("default"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

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',
    privilege: 'Search',
    collection_name: 'collection_01',
    db_name: 'default'
});

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