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: Zilliz Cloud が S3 バケットに対して持つアクセスレベルを選択します。以下の表で各オプションを説明します。

Permission	Description
Read only	Zilliz Cloud はバケット内のファイルを読み取ることのみ可能です。外部 collection を支える external volumes に使用します。
Read write	Zilliz Cloud はバケットの読み取りと書き込みの両方が可能です。backup export、audit log forwarding、または access log forwarding に使用します。

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

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

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

Amazon S3 コンソールの右上隅で、Zilliz Cloud の cluster または external volume のリージョンと一致する AWS リージョンを選択します。

📘注意

バケットを作成する AWS リージョンは、Zilliz Cloud の cluster または external volume が存在するリージョンと一致している必要があります。Zilliz Cloud がサポートするリージョンについては、Cloud Providers & Regions を参照してください。
異なるリージョンで実行される cluster については、バックアップファイルや監査ログを適切にエクスポートできるよう、各リージョンごとに別々の統合を作成してください。

左側のナビゲーションペインで 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>"
        }
    ]
}

📘注意

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

📘注意

965570967084 と my-external-id は、Zilliz Cloud コンソールの Create IAM Role ステップに表示される実際の AWS アカウント ID と external 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 をクリックします。

これで、この統合を使用してバックアップファイルをエクスポートしたり、監査ログを Amazon S3 バケットに転送したりできます。詳細については、Export Backup Files または Audit Logging を参照してください。

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

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

integration ID を取得する

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

または、次のコマンドを実行して integration 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 の cluster のリージョンと一致しない場合に発生します。

plaintext

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

解決策:

S3 バケットが配置されている AWS リージョンが、Zilliz Cloud の cluster のリージョンと一致していることを確認してください。
必要に応じて、正しいリージョンに新しいバケットを作成するか、バケットのリージョンに合わせて cluster のリージョンを調整してください。

バケットが見つからない

説明: このエラーは、指定した 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、external 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 と external ID が、IAM 信頼ポリシー内の対応する値と一致していることを確認してください。
IAM ロール内の信頼ポリシーが、Zilliz Cloud にそのロールの引き受けを許可していることを確認してください。

始める前に​

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

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

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

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

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

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

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

Amazon S3 コンソールの右上隅で、Zilliz Cloud の cluster または external volume のリージョンと一致する 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 ロールを作成します。

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

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

統合を管理する​

integration ID を取得する​

統合の詳細を表示する​

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

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

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

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

バケットロケーションへのアクセス拒否​

ロール引き受けの失敗​

始める前に

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

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

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

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

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

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

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

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

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

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

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

統合を管理する

integration ID を取得する

統合の詳細を表示する

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

トラブルシューティング

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

バケットが見つからない

バケットロケーションへのアクセス拒否

ロール引き受けの失敗