S3

本文档用于介绍访问 AWS S3 时所需的参数。这些参数适用于：

• Catalog 属性。
• Table Valued Function 属性。
• Broker Load 属性。
• Export 属性。
• Outfile 属性。

参数总览

属性名称	曾用名	描述	默认值	是否必须
s3.endpoint		S3 服务访问地址，如 s3.us-east-1.amazonaws.com	无	否
s3.access_key		AWS Access Key。用于身份验证	无	否
s3.secret_key		AWS Secret Key。用于身份验证	无	否
s3.region		S3 所在区域，例如：us-east-1。强烈建议配置	无	是
s3.use_path_style		是否使用 path-style（路径风格）访问	FALSE	否
s3.connection.maximum		最大连接数，适用于高并发场景	50	否
s3.connection.request.timeout		请求超时时间（毫秒），控制连接获取超时	3000	否
s3.connection.timeout		建立连接的超时时间（毫秒）	1000	否
s3.role_arn		使用 Assume Role 模式时指定的角色 ARN	无	否
s3.external_id		配合 s3.role_arn 使用的 external ID	无	否
s3.credentials_provider_type		指定 AWS 凭证提供器类型（无 AK/SK 时使用；在 IAM Role 场景用于 STS 源凭证）	DEFAULT	否

版本说明：s3.credentials_provider_type 自 3.1.4 和 4.0.3 起支持。

认证配置

Doris 支持以下三种方式访问 S3：

1. 直接使用 Access Key 和 Secret Key（AK/SK）

"s3.access_key"="your-access-key",
"s3.secret_key"="your-secret-key",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

2. IAM Role（Assume Role）模式

适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

在 IAM Role 模式中配置 s3.credentials_provider_type

当配置了 s3.role_arn 时，s3.credentials_provider_type 用于指定 STS AssumeRole 调用所使用的源凭证 provider：

1. 按 s3.credentials_provider_type 获取源凭证。
2. 用源凭证调用 STS AssumeRole。
3. 使用返回的临时凭证访问 S3。

IAM Role + s3.credentials_provider_type 配置示例

示例 1：EC2 Instance Profile 作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 2：Web Identity（如 IRSA）作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="WEB_IDENTITY",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 3：容器元数据作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="CONTAINER",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 4：使用默认 provider chain 作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="DEFAULT",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

3. 通过 s3.credentials_provider_type 指定凭证来源

适用于不显式填写 AK/SK 的场景，例如 EC2 Instance Profile、容器元数据、Web Identity 等。

"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

s3.credentials_provider_type 可选值

值	说明
DEFAULT	使用默认 provider chain
ENV	从环境变量读取凭证
SYSTEM_PROPERTIES	从系统属性读取凭证
WEB_IDENTITY	使用 Web Identity Token 凭证
CONTAINER	使用容器元数据凭证
INSTANCE_PROFILE	使用 EC2 Instance Profile 凭证
ANONYMOUS	匿名访问（适用于公开桶）

同时配置时的生效规则

1. 同时配置 s3.access_key 和 s3.secret_key 时，优先使用 AK/SK。
2. 未配置 AK/SK 且配置了 s3.role_arn 时，使用 IAM Role；此时 s3.credentials_provider_type 用于 STS 源凭证选择。
3. 未配置 AK/SK 且未配置 s3.role_arn 时，s3.credentials_provider_type 直接决定 S3 客户端使用的 provider。

注意：s3.access_key 和 s3.secret_key 必须成对出现，仅配置其中一个会报错。

AWS 认证鉴权配置说明请参阅文档aws-authentication-and-authorization

访问 S3 Directory Bucket

该功能自 3.1.0 起支持。

Amazon S3 Express One Zone（又名 Directory Bucket）提供更高性能，但 endpoint 格式不同。

• 普通 bucket：s3.us-east-1.amazonaws.com
• Directory Bucket：s3express-usw2-az1.us-west-2.amazonaws.com

更多可用区域参考：AWS 官方文档

示例：

"s3.access_key"="ak",
"s3.secret_key"="sk",
"s3.endpoint"="s3express-usw2-az1.us-west-2.amazonaws.com",
"s3.region"="us-west-2"

权限策略

根据使用场景不同，可以分为 只读 和 读写 两类策略。

1. 只读权限

只允许读取 S3 中的对象。适用于 LOAD、TVF、查询 EXTERNAL CATALOG 等场景。

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

2. 读写权限

在只读的基础上，允许删除、创建、修改对象。适用于 EXPORT、OUTFILE 以及 EXTERNAL CATALOG 回写等场景。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "s3:PutObject",
              "s3:GetObject",
              "s3:GetObjectVersion",
              "s3:DeleteObject",
              "s3:DeleteObjectVersion",
              "s3:AbortMultipartUpload",      
              "s3:ListMultipartUploadParts"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>/<your-prefix>/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:GetLifecycleConfiguration"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>"
        }    
    ]
}

注意事项

1. 占位符替换

   • <bucket> → 你的 S3 Bucket 名称。
   • <account-id> → 你的 AWS 账号 ID（12 位数字）。

2. 最小权限原则

   • 如果只做查询，不要授予写权限。