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 Management Console への管理者アクセス権を持っていること。

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

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

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

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

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

Integration Name: この統合の一意の名前です（例: integration_0819）。
Integration Description (任意): この統合の説明です（例: for export backupfile）。

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

権限	説明
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 をクリックします。

詳細については、Creating a 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 ドキュメントの Key identifiers を参照してください。

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 をコピーします。これは、後ほど Zilliz Cloud コンソールのステップ 5 で必要になります。

ステップ 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:aws:iam::123456789012:role/zilliz-bucket-role のようなロール ARN を控えておいてください。ロールの作成方法の詳細については、前述の AWS コンソールでの IAM ポリシーの作成および IAM ロールの作成を参照してください。

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

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

bash
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 を参照してください。

ストレージ統合を作成します。

このリクエストは、説明を除き、検証リクエストとほとんどのパラメータが共通しています。

bash
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 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 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 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 をコピーします。これは、後ほど Zilliz Cloud コンソールの ステップ 5 で必要になります。

ステップ 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 をクリックします。

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

完了したら、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 をコピーします。これは、後ほど Zilliz Cloud コンソールのステップ 5 で必要になります。

ステップ 5: 統合を検証して追加する

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

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

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

統合を管理する

統合 ID を取得する

統合の詳細を表示する

ストレージ統合を削除する

トラブルシューティング

バケットのリージョンが一致しない

バケットが見つからない

バケットの場所へのアクセスが拒否される

ロールの引き受けに失敗する

権限の反映の遅延