跳到主要内容
版本：Cloud 开发指南

Amazon S3

Zilliz Cloud 支持与 Amazon Simple Storage Service（Amazon S3） 集成。

该存储集成可用于：

📘说明

此功能仅限企业版项目使用。

MWh0wX3wehaH1dbkEXpc5GbFnoc

开始前​

  • 要将 Zilliz Cloud 与 Amazon S3 集成，您需要拥有组织管理员或项目管理员权限。如果您权限不足，请联系您的 Zilliz Cloud 组织管理员。

  • 您需要具有亚马逊云科技管理控制台的 Admin 权限。

步骤 1：集成基础设置​

1

登录 Zilliz Cloud 控制台。

2

进入目标项目，点击左侧导航栏的集成中心。

3

在 Amazon S3 区域，点击添加配置。

4

在弹出的对话框中，完成基础设置：

  • 配置名称：为此集成设置一个唯一名称（如：s3_integration_0820）。

  • 配置描述（可选）：为此集成添加描述（如：for export backup file）。

  • Bucket 权限：选择 Zilliz Cloud 对您的对象存储桶具有的访问级别。下表说明了这些选项。

    权限

    说明

    只读

    Zilliz Cloud 只能从存储桶中读取文件。用于为 External collections 提供支持的 External volumes。

    读写

    Zilliz Cloud 既可以从 bucket 中读取数据，也可以向 bucket 中写入数据。用于导出备份文件、转发审计日志或转发访问日志。

5

点击下一步。在创建 Amazon S3 存储桶步骤中，完成以下操作：

  1. 在 Zilliz Cloud 集群地域选项中，选择 Zilliz Cloud 集群或 Volum 所在的云地域。之后创建的存储桶所在的云地域需与 Zilliz Cloud 集群或 Volume所在的云地域相同。

  2. 打开 Amazon S3 控制台，继续执行步骤 2。

步骤 2：创建存储桶​

1

登录到 Amazon S3 控制台。

2

在页面顶部选择与你的 Zilliz Cloud 集群所在区域一致的 Amazon 云地域。

📘说明

  • 创建存储桶的云地域必须与 Zilliz Cloud 集群所在地域一致。Zilliz Cloud 支持的区域可参考云服务提供商和地域。

  • 如果集群运行在不同区域，需要分别为每个区域创建集成。

3

在左侧导航栏中，选择存储桶。

4

在通用存储桶页面，选择创建存储桶。此时将打开创建存储桶页面。

5

在常规配置中，设置存储桶名称（例如：bucket-for-integration），并记住该名称，后续步骤会用到。有关存储桶命名规则的完整列表，请参阅通用存储桶命名规则。

6

其余设置可保持默认，然后点击创建存储桶。

有关更多信息，请参考创建通用存储桶。

存储桶创建完成后，返回 Zilliz Cloud 控制台，完成以下操作：

1

在创建 Amazon S3 存储桶步骤的存储桶名称字段中，输入刚才所创建的存储桶名称（本指南中为 bucket-for-integration）。然后点击下一步。

2

在创建 IAM 策略步骤中，复制 JSON 策略。步骤 3 需要提供该内容。

3

完成后打开 IAM 控制台，进入步骤 3。

步骤 3：创建 IAM 策略​

为了让 Zilliz Cloud 访问 Amazon S3，需要创建一个 IAM 策略，包含必要的操作和资源权限，以便在 Zilliz Cloud 和 Amazon S3 存储桶之间转发审计日志或导出备份文件。

1

在 IAM 控制台，选择 策略 > 创建策略。

2

在策略编辑器中选择 JSON 选项。

3

将步骤 2 中 Zilliz Cloud 提供的 JSON 策略文档粘贴到编辑器中，然后点击下一步。

示例 JSON 策略（实际策略以 Zilliz Cloud 控制台显示为准）：

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

当您为上述对象存储桶启用了服务端加密，您还需要为 kms:GenerateDataKey 操作添加相应的策略。在此情况下，请使用如下 JSON 策略文件。

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

  • <bucket> 需要替换为你的存储桶实际名称。

  • <region>, <account_id>, and <key_id> 需要替换为对应的值。详情请参考 AWS 文档中的密钥标识符一节的相关内容。

4

在查看和创建页面，输入策略名称（例如：zilliz-policy-for-integration）和可选描述，并检查权限是否正确。

5

点击创建策略，完成后进入步骤 4。

步骤 4：创建 IAM 角色​

创建 IAM 角色前，在 Zilliz Cloud 控制台完成以下操作：

1

在 Zilliz Cloud 控制台，点击下一步，进入创建 IAM 角色步骤。

2

在选择可信实体区域中，复制 JSON 格式的信任策略，然后打开 IAM 控制台。

之后，继续在 IAM 控制台完成以下操作：

1

在 IAM 控制台，选择角色 > 创建角色。

2

在可信实体类型中，选择自定义信任策略类型。

3

在自定义信任策略部分，粘贴 Zilliz Cloud 提供的 JSON 信任策略，然后点击下一步。

示例 JSON 信任策略（实际以控制台为准）：

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

306787409409 和 my-external-id 需要替换为控制台实际显示的亚马逊云科技账号 ID 和 External ID。

4

在添加权限步骤中，搜索并选择步骤 3 中创建的策略，然后点击下一步。

5

在命名、查看和创建步骤中，输入角色名称并检查配置，最后点击创建角色。

6

创建完成后，点击右上角的查看角色。

7

在角色详情页面，复制该角色的 ARN，该 ARN 将在步骤 5 中使用。

步骤 5：校验并添加集成​

1

在 Zilliz Cloud 控制台的创建 IAM 角色步骤中，将从 IAM 控制台复制的 ARN 粘贴至 角色 ARN 字段。

2

点击校验集成。

3

校验通过后，点击添加。

之后您便可以转发审计日志或导出备份文件到您的 Amazon S3 存储桶。有关更多信息，请参考审计日志或导出备份文件。

调用接口创建存储集成​

除了在 Zilliz Cloud 控制台上进行操作之外，您还可以调用接口创建存储集成。

1

创建 OSS 存储空间。

更多详情，可参考上面的创建存储桶小节或 CreateBucket。

2

生成鉴权材料。

export BASE_URL="https://api.cloud.zilliz.com.cn"
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-cn-northwest-1",
    "bucketName": "my-bucket"
}'

根据上述请求，Zilliz Cloud 会生成您在阿里云控制台上创建权限策略及 RAM 角色时所需的凭据。返回的响应如下：

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

关于请求及响应中各字段的说明，可以参考生成 Storage Integration 授权材料。

3

使用返回的 readonly、readwrite、iamPolicy、trustPolicy 及 zillizAccount 创建 IAM 角色，并为其添加必要的权限，使其可以操作您的存储桶。

请记录下已创建的 IAM 角色 ARN，其格式类似 arn:aws:iam::123456789012:role/zilliz-bucket-role。关于如何创建 IAM 角色，可以参考创建 IAM 策略及创建 IAM 角色两小节的内容。

4

验证使用上述凭据创建的 IAM 角色是否可以正常访问您的存储桶。

在请求中，您需要将 externalCred.roleArn 设置为上一步获得的 IAM 角色 ARN，并将 externalCred.externalId 设置为生成的授权材料中的 externalId。

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-cn-northwest-1",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "arn:aws:iam::123456789012:role/zilliz-bucket-role",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

验证成功的响应如下：

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

关于请求及响应中各字段的说明，可以参考校验 Storage Integration。

5

创建存储集成。

此请求在验证请求的基础上增加了 description 参数。

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-cn-northwest-1",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "arn:aws:iam::123456789012:role/zilliz-bucket-role",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

上述请求的响应格式如下：

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

关于请求及响应中各字段的说明，可以参考创建 Storage Integration。

管理集成​

集成添加完成后，您可以查看其详细信息或根据需要删除该集成。

IohLb8sC2oQHLUxn4GzcDLF4nth

获取集成 ID​

如果您需要使用 RESTful API 接口导出文件到您集成到 Zilliz Cloud 的对象存储桶中，您可以单击查看详情查看该对象存储桶的集成详情并复制该桶的集成 ID。

除此之外，您还可以执行如下命令获取集成 ID。

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"

上述请求的响应如下：

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

关于请求及响应中各字段的说明，可以参考列出 Storage Integration。

查看集成详情​

您还可以执行如下命令查看指定集成的详情。

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"

上述请求的响应如下：

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

关于请求及响应中各字段的说明，可以参考查看 Storage Integration。

删除集成​

除了可以在 Zilliz Cloud 控制台上单击删除按钮之外，您还可以执行如下命令来删除指定集成。

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"

上述请求的响应如下：

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

关于请求及响应中各字段的说明，可以参考删除 Storage Integration。