クラスターロールの管理（SDK）

クラスターロールは、クラスター内でユーザーが持つ権限を定義します。より具体的には、クラスターロールはクラスター、データベース、コレクションの各レベルでクラスターユーザーの権限を制御します。

このガイドでは、ロールを作成し、組み込み権限グループをロールに付与し、ロールから権限グループを取り消し、最後にロールを削除する方法について説明します。組み込み権限グループの詳細については、権限 を参照してください。

Notes

この機能は Dedicated クラスターでのみ利用できます。

ロールを作成する

次の例では、role_a という名前のロールを作成する方法を示します。

ロール名は英字で始まる必要があり、大文字または小文字の英字、数字、およびアンダースコアのみを使用できます。

Python

python

from pymilvus import MilvusClient

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

Java

java

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

Go

go

import (
    "context"
    "fmt"

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

ctx := context.Background()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

err = client.CreateRole(ctx, milvusclient.NewCreateRoleOption("role_a").WithDescription("a cluster read only role"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

Rust

rust

use milvus::v2::prelude::*;

client
    .create_role(
        CreateRoleRequest::builder()
            .role_name("role_a")
            .description("a cluster read only role")
            .build()?,
    )
    .await?;

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

auto status = client->CreateRole(milvus::CreateRoleRequest()
                                     .WithRoleName("role_a")
                                     .WithDescription("a cluster read only role"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

await client.createRole({
  roleName: 'role_a',
  description: 'a cluster read only role',
});

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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

python

from pymilvus import MilvusClient

client.list_roles()

Java

java

import java.util.List;

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

Go

go

import (
    "context"
    "fmt"

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

ctx := context.Background()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

roles, err := client.ListRoles(ctx, milvusclient.NewListRoleOption())
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(roles)

Rust

rust

use milvus::v2::prelude::*;

let roles = client
    .list_roles(ListRolesRequest::builder().build()?)
    .await?;
println!("{:?}", roles.role_names());

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

milvus::ListRolesResponse resp;
auto status = client->ListRoles(milvus::ListRolesRequest(), resp);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

const roles = await client.listRoles();
console.log(roles);

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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

以下は出力例です。role_a は、作成したばかりの新しいロールです。

bash

['role_a']

ロールに権限グループを付与する

Zilliz Cloud では、ロールに次のものを付与できます。

• 組み込み権限グループ: Zilliz Cloud は 9つの組み込み権限グループを提供します。各組み込み権限グループに含まれる具体的な権限の詳細については、組み込み権限グループ を参照してください。

• カスタム権限グループ: 組み込み権限がニーズを満たさない場合は、さまざまな権限を組み合わせて独自のカスタム権限グループを作成できます。詳細については、カスタム権限グループ を参照してください。

Notes

• ロールにカスタム権限グループを付与する必要がある場合は、この機能を有効化できるよう、サポートチケットを作成 してください。

• Milvus 2.5.x 以降を実行しているクラスターでは、個別の権限はサポートされなくなりました。

次の例では、role_a というロールに、privilege_group_1 という名前のカスタム権限グループと、組み込み権限グループ ClusterReadOnly を付与する方法を示します。

Python

python

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

Java

java

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

Go

go

import (
    "context"
    "fmt"

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

ctx := context.Background()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
    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
}

Rust

rust

use milvus::v2::prelude::*;

client
    .grant_privilege(
        GrantPrivilegeRequest::builder()
            .role_name("role_a")
            .privilege("privilege_group_1")
            .database_name("default")
            .collection_name("collection_01")
            .build()?,
    )
    .await?;

client
    .grant_privilege(
        GrantPrivilegeRequest::builder()
            .role_name("role_a")
            .privilege("ClusterReadOnly")
            .database_name("*")
            .collection_name("*")
            .build()?,
    )
    .await?;

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

milvus::GrantPrivilegeV2Request grant_req;
grant_req.WithRoleName("role_a")
         .WithPrivilege("privilege_group_1")
         .WithDatabaseName("default")
         .WithCollectionName("collection_01");
auto status = client->GrantPrivilegeV2(grant_req);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

const client = new MilvusClient({
  address: 'YOUR_CLUSTER_ENDPOINT',
  token: 'YOUR_CLUSTER_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

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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: 権限グループの対象リソースです。特定のクラスター、データベース、またはコレクションを指定できます。

  次の表では、リソースを指定する方法について説明します。

  レベル	リソース	付与方法	注意
  コレクション	特定のコレクション	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="*" )	データベース名として *、コレクション名として * を入力します。

ロールの詳細を表示する

次の例では、describe_role メソッドを使用して、role_a ロールに付与されている権限を表示する方法を示します。

Python

python

from pymilvus import MilvusClient

client.describe_role(role_name="role_a")

Java

java

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

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

Go

go

import (
    "context"
    "fmt"

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

ctx := context.Background()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

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

Rust

rust

use milvus::v2::prelude::*;

let role = client
    .describe_role(
        DescribeRoleRequest::builder()
            .role_name("role_a")
            .build()?,
    )
    .await?;
println!("{:?}", role.description().get_role_name());

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

milvus::DescribeRoleResponse resp;
auto status = client->DescribeRole(milvus::DescribeRoleRequest().WithRoleName("role_a"), resp);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

const role = await client.describeRole({ roleName: 'role_a' });
console.log(role);

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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

以下は出力例です。

python

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

ロールから権限グループを取り消す

次の例では、role_a ロールに付与されているカスタム権限グループ privilege_group_1 と組み込み権限グループ ClusterReadOnly を取り消す方法を示します。

Python

python

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

Java

java

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

Go

go

import (
    "fmt"

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

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
}

Rust

rust

use milvus::v2::prelude::*;

client
    .revoke_privilege(
        RevokePrivilegeRequest::builder()
            .role_name("role_a")
            .privilege("privilege_group_1")
            .database_name("default")
            .collection_name("collection_01")
            .build()?,
    )
    .await?;

client
    .revoke_privilege(
        RevokePrivilegeRequest::builder()
            .role_name("role_a")
            .privilege("ClusterReadOnly")
            .database_name("*")
            .collection_name("*")
            .build()?,
    )
    .await?;

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

milvus::RevokePrivilegeV2Request revoke_req;
revoke_req.WithRoleName("role_a")
           .WithPrivilege("privilege_group_1")
           .WithDatabaseName("default")
           .WithCollectionName("collection_01");
auto status = client->RevokePrivilegeV2(revoke_req);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

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

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

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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": "privilege_group_1",
    "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 ロールを削除する方法を示します。

Notes

組み込みロール admin は削除できません。

Python

python

from pymilvus import MilvusClient

client.drop_role(role_name="role_a")

Java

java

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

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

Go

go

import (
    "fmt"

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

err = client.DropRole(ctx, milvusclient.NewDropRoleOption("role_a"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

Rust

rust

use milvus::v2::prelude::*;

client
    .drop_role(
        DropRoleRequest::builder()
            .role_name("role_a")
            .build()?,
    )
    .await?;

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

auto status = client->DropRole(milvus::DropRoleRequest().WithRoleName("role_a"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

await client.dropRole({ roleName: 'role_a' });

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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

ロールを削除した後、既存のすべてのロールを一覧表示して、削除操作が成功したかどうかを確認できます。

Python

python

from pymilvus import MilvusClient

client.list_roles()

Java

java

import java.util.List;

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

Go

go

import (
    "context"
    "fmt"

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

ctx := context.Background()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "YOUR_CLUSTER_ENDPOINT",
    APIKey:  "YOUR_CLUSTER_TOKEN",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

roles, err := client.ListRoles(ctx, milvusclient.NewListRoleOption())
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
fmt.Println(roles)

Rust

rust

use milvus::v2::prelude::*;

let roles = client
    .list_roles(ListRolesRequest::builder().build()?)
    .await?;
println!("{:?}", roles.role_names());

C++

c++

#include <iostream>
#include "milvus/MilvusClientV2.h"

milvus::ListRolesResponse resp;
auto status = client->ListRoles(milvus::ListRolesRequest(), resp);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

NodeJS

javascript

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

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

const roles = await client.listRoles();
console.log(roles);

cURL

bash

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

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

以下は出力例です。一覧に role_a はありません。削除操作は成功しました。

bash

['admin']