AWS S3 との連携

Zilliz Cloud では、Amazon Simple Storage Service（Amazon S3）と連携して、バックアップファイルや監査ログを指定した S3 バケットにエクスポートできます。

BUEcwkZiChJrTlbziBMc3V49nFe

事前準備

Zilliz Cloud と AWS S3 を連携させるには、プロジェクトに対する Organization Owner または Project Admin の権限を持っていること。必要な権限がない場合は、Zilliz Cloud の Organization Owner にお問い合わせください。
AWS マネジメントコンソールへの管理者アクセス権を持っていること。

ステップ 1: Zilliz Cloud コンソールで連携を開始する

Zilliz Cloud コンソールにログインします。

プロジェクトページで、左側のナビゲーションパネルから Integrations に移動します。

Amazon S3 セクションで、+ Integration をクリックします。

表示されたダイアログボックスで、Basic Settings を構成します。

Integration Name: この連携の一意の名前（例: integration_0819）。
Integration Description （任意）: この連携の説明（例: for export backupfile）。

Bucket Permission: Zilliz Cloud が S3 バケットに対して持つアクセスレベルを選択します。以下の表で各オプションについて説明します。

権限	説明
Read only	Zilliz Cloud はバケット内のファイルを読み取ることのみできます。外部コレクションを支える外部ボリュームに使用します。
Read write	Zilliz Cloud はバケットに対する読み取りと書き込みの両方を行うことができます。バックアップのエクスポート、監査ログの転送、アクセスログの転送に使用します。

Next をクリックします。Create Amazon S3 Bucket ステップにリダイレクトされます。

Zilliz Cloud クラスター の Region フィールドで、Zilliz Cloud クラスターまたは外部ボリュームが存在するクラウドリージョンを選択します。後で作成するバケットは、Zilliz Cloud クラスターまたはボリュームと同じリージョンにある必要があります。
S3 コンソールを開き、ステップ 2 に進みます。

ステップ 2: AWS コンソールで S3 バケットを作成する

Amazon S3 コンソールの右上隅で、Zilliz Cloud クラスターまたは外部ボリュームのリージョンと一致する AWS リージョンを選択します。

Notes

バケットを作成する AWS リージョンは、Zilliz Cloud クラスターまたは外部ボリュームが存在するリージョンと一致させる必要があります。Zilliz Cloud がサポートするリージョンについては、クラウドプロバイダーとリージョンを参照してください。
異なるリージョンで実行されているクラスターの場合は、バックアップファイルまたは監査ログを正しくエクスポートできるように、リージョンごとに個別の連携を作成してください。

左側のナビゲーションパネルで General purpose buckets を選択し、続いて Create bucket をクリックします。

バケットの設定を構成します。

Bucket type で General purpose を選択します。
Bucket name に、バケットの名前を入力します（例: zilliz-bucket-for-integration-0819）。このバケット名は後のステップで必要になるため、必ず覚えておいてください。
その他の設定はデフォルトのままにして、Create bucket をクリックします。

詳細については、バケットの作成を参照してください。

バケットが作成されたら、Zilliz Cloud コンソールに戻り、次の操作を行います。

Bucket Name フィールドに、先ほど作成したバケットの名前を入力します（この例では `zilliz-bucket-for-integration-0819`）。次に、Next をクリックします。

Create IAM Policy ステップで、JSON ポリシーをコピーします。これはステップ 3 で必要になります。

完了したら、IAM コンソールを開き、ステップ 3 に進みます。

ステップ 3: AWS コンソールで IAM ポリシーを作成する

Zilliz Cloud に AWS S3 へのアクセス権を付与するには、IAM ポリシーを作成します。このポリシーには、Zilliz Cloud と S3 バケット間でのバックアップファイルの転送を円滑にするための、特定のアクションとリソースを含める必要があります。

ここでは簡便のため、JSON エディターを使用してポリシーを作成します。

IAM コンソールで、Policies > Create policy を選択します。

Policy editor セクションで、JSON オプションを選択します。

Zilliz Cloud から提供された JSON ポリシードキュメントをコピーして、ポリシーエディターに貼り付けます。次に、Next をクリックします。

以下はサンプルの JSON ポリシードキュメントです。連携に合わせた正確なポリシーについては、Zilliz Cloud コンソールの Create IAM Policy ステップを参照してください。

json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket>",
                "arn:aws:s3:::<bucket>/*"
            ]
        }
    ]
}

ただし、AWS KMS を使用してバケットのサーバー側暗号化を有効にしている場合は、kms:GenerateDataKey アクションを許可する別の IAM ポリシーを追加する必要があります。この場合は、以下の JSON ポリシーを使用します。

json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket>",
                "arn:aws:s3:::<bucket>/*"
            ]
        },
        {
            "Sid": "AllowKMSGenerateDataKey",
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:<region>:<account_id>:key/<key_id>"
        }
    ]
}

Notes

<bucket> は、実際の S3 バケットの名前に置き換える必要があります。
<region>、<account_id>、<key_id> は、それぞれ実際の値に置き換える必要があります。詳細については、AWS ドキュメントのキー識別子を参照してください。

Review and create ページで、作成するポリシーの Policy Name（例: `zilliz-policy-for-integration-0819`）と Description（任意）を入力し、Permissions defined in this policy を確認します。ポリシー名は後のステップで必要になるため、必ず覚えておいてください。

Create policy を選択して新しいポリシーを保存します。完了したら、ステップ 4 に進みます。

ステップ 4: IAM ロールを作成する

AWS コンソールで IAM ロールを作成する前に、Zilliz Cloud コンソールで次の操作を行います。

Zilliz Cloud コンソールで Next をクリックし、Create IAM Role ステップに進みます。

Select trusted entity で JSON の内容をコピーし、IAM コンソールに移動します。

完了したら、次の手順で IAM ロールを作成します。

IAM コンソールで、Roles > Create role を選択します。

Custom trust policy ロールタイプを選択します。

Custom trust policy セクションで、ロールのカスタム信頼ポリシーをコピーして貼り付けます。次に、Next をクリックします。

以下はサンプルの JSON 信頼ポリシーです。連携に合わせた正確な信頼ポリシーについては、Zilliz Cloud コンソールの Create IAM Role ステップを参照してください。

json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Principal": {
                "AWS": "965570967084"
            },
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "my-external-id"
                }
            }
        }
    ]
}

Notes

965570967084 と my-external-id は、Zilliz Cloud コンソールの Create IAM Role ステップに表示される実際の AWS アカウント ID と外部 ID に置き換える必要があります。

Add permissions ステップの Permissions policies で、ステップ 3 で作成したポリシーを検索して選択し、権限を追加します。次に、Next をクリックします。

Name, review, and create ステップで、ロール名（例: `zilliz-integration-role-0819`）を入力し、設定を確認します。次に、Create role をクリックします。

作成したロールの詳細ページに移動し、そのロールに対応する ARN をコピーします。これはステップ 5 で Zilliz Cloud コンソールにおいて必要になります。

ステップ 5: 連携を検証して追加する

Zilliz Cloud コンソールの Create IAM Role ステップで、前のステップで IAM コンソールからコピーした ARN を貼り付けます。

次に、Validate Integration をクリックして、S3 バケットと IAM ロールの設定を確認します。

ステータスが Successful に変わると、連携が機能します。次に、Add をクリックします。

Notes

IAM の変更が反映されるまでに時間がかかる場合があります。構成直後に検証が失敗した場合は、待ってから再試行してください。

これで、この連携を使用してバックアップファイルをエクスポートしたり、監査ログを Amazon S3 バケットに転送したりできるようになりました。詳細については、バックアップファイルのエクスポートまたは監査ログを参照してください。

ストレージ連携をプログラムで作成する

Zilliz Cloud コンソールでの操作の代わりに、ストレージ連携をプログラムから作成することもできます。

S3 バケットを作成します。

詳細については、上記の AWS コンソールで S3 バケットを作成するまたは CreateBucket API ドキュメントを参照してください。

認証情報を生成します。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations/authorizationMaterials" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "regionId": "aws-us-west-2",
    "bucketName": "my-bucket"
}'

上記のリクエストは、AWS コンソールで権限、ポリシー、ロールを作成するために必要な認証情報を生成します。

応答の例は以下の通りです。

bash
{
  "code": 0,
  "data": {
    "readonly": "{...}",
    "readwrite": "{...}",
    "iamPolicy": "{...}",
    "trustPolicy": "{...}",
    "zillizAccount": "306787409409",
    "externalId": "zilliz-external-AbCdEf12345678"
  }
}

パラメーターの説明の詳細については、Generate Storage Integration Authorization Materials を参照してください。

返された `readonly`、`readwrite`、`iamPolicy`、`trustPolicy`、`zillizAccount` を使用して、バケットを操作するための十分な権限を持つ IAM ロールを作成します。

ロール ARN を書き留めてください。これは arn:aws:iam::123456789012:role/zilliz-bucket-role のような形式です。ロールの作成方法の詳細については、上記の AWS コンソールで IAM ポリシーを作成するおよび IAM ロールを作成するを参照してください。

取得した認証情報を検証します。

リクエストで、externalCred.roleArn に前のステップで書き留めたロール ARN を設定し、externalCred.externalId に取得した認証情報に表示された値を設定します。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations/validate" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "regionId": "aws-us-west-2",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "arn:aws:iam::123456789012:role/zilliz-bucket-role",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

検証が成功した場合の応答は以下の通りです。

bash
{
    "code": 0,
    "data": {
        "success": true,
        "message": ""
    }
}

パラメーターの説明の詳細については、Validate Storage Integration を参照してください。

ストレージ連携を作成します。

このリクエストは、description 以外は検証リクエストとほとんどのパラメーターが共通です。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "name": "analytics-s3",
    "description": "S3 bucket for external tables",
    "regionId": "aws-us-west-2",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "arn:aws:iam::123456789012:role/zilliz-bucket-role",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

応答は以下の通りです。

bash
{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-s3"
    }
}

パラメーターの説明の詳細については、Create Storage Integration を参照してください。

連携を管理する

連携を追加すると、必要に応じてその詳細を表示したり、連携を削除したりできます。

YODhb5leToWLsjxGRrpcyuZNnPb

連携 ID を取得する

RESTful API を使用して、Zilliz Cloud と連携した AWS S3 バケットのいずれかにバックアップファイルをエクスポートする必要がある場合は、View Details をクリックして連携の詳細を表示し、その連携 ID をコピーします。

または、次のコマンドを実行して連携 ID を取得することもできます。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request GET \
--url "${BASE_URL}/v2/storageIntegrations?projectId=proj-xxxxxxxxxxxxxxxxxxxxxx" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

応答は以下の通りです。

bash
{
    "code": 0,
    "data": {
        "storageIntegrations": [
            {
                "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
                "name": "analytics-s3",
                "status": "ACTIVE",
                "message": "",
                "regionId": "aws-us-west-2",
                "bucketName": "my-bucket"
            }
        ],
        "count": 1,
        "currentPage": 1,
        "pageSize": 10
    }
}

パラメーターの説明の詳細については、List Storage Integrations を参照してください。

連携の詳細を表示する

次のコマンドを使用して連携の詳細を表示できます。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

export integrationId="integ-xxxxxxxxxxxxxxxxxxx"

curl --request GET \
--url "${BASE_URL}/v2/storageIntegrations/${integrationId}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

応答は以下の通りです。

bash
{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-s3",
        "description": "S3 bucket for external tables",
        "status": "ACTIVE",
        "message": "",
        "regionId": "aws-us-west-2",
        "bucketName": "my-bucket",
        "externalCred": {
            "roleArn": "arn:aws:iam::123456789012:role/zilliz-bucket-role",
            "externalId": "zilliz-external-AbCdEf12345678"
        },
        "createTime": "2024-07-30T16:49:50Z"
    }
}

パラメーターの説明の詳細については、Describe Storage Integration を参照してください。

ストレージ連携を削除する

Zilliz Cloud コンソールで Remove をクリックする代わりの方法として、次のコマンドを使用して不要なストレージ連携を削除できます。

bash
export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

export integrationId="integ-xxxxxxxxxxxxxxxxxxx"

curl --request DELETE \
--url "${BASE_URL}/v2/storageIntegrations/${integrationId}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

応答は以下の通りです。

bash
{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-s3"
    }
}

パラメーターの説明の詳細については、Delete Storage Integration を参照してください。

トラブルシューティング

連携のプロセスで問題が発生した場合に備えて、よくあるエラーメッセージとその解決策を以下に示します。

バケットリージョンの不一致

説明: 次のエラー例は、S3 バケットのリージョンが Zilliz Cloud クラスターのリージョンと一致しない場合に発生します。

plaintext

"bucket region not match, want[us-west-1] got[us-west-2]"

解決策:

S3 バケットが配置されている AWS リージョンが、Zilliz Cloud クラスターのリージョンと一致していることを確認します。
必要に応じて、正しいリージョンに新しいバケットを作成するか、バケットのリージョンに合わせてクラスターのリージョンを変更します。

バケットが見つからない

説明: このエラーは、指定した S3 バケットが存在しないか、バケット名が正しくない場合に発生します。

plaintext

check bucket failed: get bucket location: operation error S3: GetBucketLocation, https response error StatusCode: 404, RequestID: ..., HostID: ..., api error NoSuchBucket: The specified bucket does not exis

解決策:

Zilliz Cloud コンソールと AWS S3 コンソールの両方で、バケット名を再確認します。
バケットが存在すること、および Zilliz Cloud の構成で名前が正しく入力されていることを確認します。

バケットのロケーションに対するアクセス拒否

説明: このエラーは、IAM ロールに S3 バケットのロケーションにアクセスするために必要な権限がない場合に発生します。

plaintext

check bucket failed: get bucket location: operation error S3: GetBucketLocation, https response error StatusCode: 403 ...

解決策:

Zilliz Cloud が使用しているロールにアタッチされている IAM ポリシーを確認します。
ポリシーに s3:GetBucketLocation 権限が、s3:GetObject、s3:PutObject、s3:ListBucket などの他の必要な権限とともに含まれていることを確認します。

ロールの引き受けエラー

説明: このエラーは、ロール ARN、外部 ID、または信頼ポリシーが正しくないために IAM ロールの引き受けに問題がある場合に発生します。

sql
try assume role from[zilliz-role] to [arn:aws:iam::041623484421:role/testoss121703] with externalId[zilliz-external-1umVCIK7q96kzDE] failed

解決策:

Zilliz Cloud コンソールのロール ARN と外部 ID が、IAM 信頼ポリシーの対応する値と一致していることを確認します。
IAM ロールの信頼ポリシーが Zilliz Cloud にそのロールの引き受けを許可していることを確認します。

権限の反映の遅延

IAM ロールまたはポリシーを作成または更新した直後に AccessDenied エラーが発生した場合は、待ってから再試行してください。AWS IAM の変更は結果整合性があり、反映までの最大時間は保証されていません。

事前準備​

ステップ 1: Zilliz Cloud コンソールで連携を開始する​

Zilliz Cloud コンソール にログインします。

プロジェクトページで、左側のナビゲーションパネルから Integrations に移動します。

Amazon S3 セクションで、+ Integration をクリックします。

表示されたダイアログボックスで、Basic Settings を構成します。

Next をクリックします。Create Amazon S3 Bucket ステップにリダイレクトされます。

ステップ 2: AWS コンソールで S3 バケットを作成する​

Amazon S3 コンソール の右上隅で、Zilliz Cloud クラスターまたは外部ボリュームのリージョンと一致する AWS リージョンを選択します。

左側のナビゲーションパネルで General purpose buckets を選択し、続いて Create bucket をクリックします。

バケットの設定を構成します。

Bucket Name フィールドに、先ほど作成したバケットの名前を入力します（この例では zilliz-bucket-for-integration-0819）。次に、Next をクリックします。

Create IAM Policy ステップで、JSON ポリシーをコピーします。これはステップ 3 で必要になります。

完了したら、IAM コンソール を開き、ステップ 3 に進みます。

ステップ 3: AWS コンソールで IAM ポリシーを作成する​

IAM コンソール で、Policies > Create policy を選択します。

Policy editor セクションで、JSON オプションを選択します。

Zilliz Cloud から提供された JSON ポリシードキュメントをコピーして、ポリシーエディターに貼り付けます。次に、Next をクリックします。

Create policy を選択して新しいポリシーを保存します。完了したら、ステップ 4 に進みます。

ステップ 4: IAM ロールを作成する​

Zilliz Cloud コンソールで Next をクリックし、Create IAM Role ステップに進みます。

Select trusted entity で JSON の内容をコピーし、IAM コンソール に移動します。

IAM コンソール で、Roles > Create role を選択します。

Custom trust policy ロールタイプを選択します。

Custom trust policy セクションで、ロールのカスタム信頼ポリシーをコピーして貼り付けます。次に、Next をクリックします。

Add permissions ステップの Permissions policies で、ステップ 3 で作成したポリシーを検索して選択し、権限を追加します。次に、Next をクリックします。

Name, review, and create ステップで、ロール名（例: zilliz-integration-role-0819）を入力し、設定を確認します。次に、Create role をクリックします。

作成したロールの詳細ページに移動し、そのロールに対応する ARN をコピーします。これは ステップ 5 で Zilliz Cloud コンソールにおいて必要になります。

ステップ 5: 連携を検証して追加する​

Zilliz Cloud コンソール の Create IAM Role ステップで、前のステップで IAM コンソールからコピーした ARN を貼り付けます。

次に、Validate Integration をクリックして、S3 バケットと IAM ロールの設定を確認します。

ステータスが Successful に変わると、連携が機能します。次に、Add をクリックします。

ストレージ連携をプログラムで作成する​

S3 バケットを作成します。

認証情報を生成します。

返された readonly、readwrite、iamPolicy、trustPolicy、zillizAccount を使用して、バケットを操作するための十分な権限を持つ IAM ロールを作成します。

取得した認証情報を検証します。

ストレージ連携を作成します。

連携を管理する​

連携 ID を取得する​

連携の詳細を表示する​

ストレージ連携を削除する​

トラブルシューティング​

バケットリージョンの不一致​

バケットが見つからない​

バケットのロケーションに対するアクセス拒否​

ロールの引き受けエラー​

権限の反映の遅延​

事前準備

ステップ 1: Zilliz Cloud コンソールで連携を開始する

Zilliz Cloud コンソールにログインします。

ステップ 2: AWS コンソールで S3 バケットを作成する

Amazon S3 コンソールの右上隅で、Zilliz Cloud クラスターまたは外部ボリュームのリージョンと一致する AWS リージョンを選択します。

Bucket Name フィールドに、先ほど作成したバケットの名前を入力します（この例では `zilliz-bucket-for-integration-0819`）。次に、Next をクリックします。

完了したら、IAM コンソールを開き、ステップ 3 に進みます。

ステップ 3: AWS コンソールで IAM ポリシーを作成する

IAM コンソールで、Policies > Create policy を選択します。

ステップ 4: IAM ロールを作成する

Select trusted entity で JSON の内容をコピーし、IAM コンソールに移動します。

IAM コンソールで、Roles > Create role を選択します。

Name, review, and create ステップで、ロール名（例: `zilliz-integration-role-0819`）を入力し、設定を確認します。次に、Create role をクリックします。

作成したロールの詳細ページに移動し、そのロールに対応する ARN をコピーします。これはステップ 5 で Zilliz Cloud コンソールにおいて必要になります。

ステップ 5: 連携を検証して追加する

Zilliz Cloud コンソールの Create IAM Role ステップで、前のステップで IAM コンソールからコピーした ARN を貼り付けます。

ストレージ連携をプログラムで作成する

返された `readonly`、`readwrite`、`iamPolicy`、`trustPolicy`、`zillizAccount` を使用して、バケットを操作するための十分な権限を持つ IAM ロールを作成します。

連携を管理する

連携 ID を取得する

連携の詳細を表示する

ストレージ連携を削除する

トラブルシューティング

バケットリージョンの不一致

バケットが見つからない

バケットのロケーションに対するアクセス拒否

ロールの引き受けエラー

権限の反映の遅延