S3
本文档用于介绍访问 AWS S3 时所需的参数。这些参数适用于：
- Catalog 属性。
- Table Valued Function 属性。
- Broker Load 属性。
- Export 属性。
- Outfile 属性。
配置 BE 端 HTTPS CA 证书
自 Doris 2.1 起，当 Doris BE 通过 HTTPS 访问 S3 时，可以在 be.conf 中显式配置 ca_cert_file_paths。
默认情况下，如果未配置 ca_cert_file_paths，Doris 会使用操作系统默认的 CA 证书。在大多数环境中，不需要手动设置该参数。建议在以下场景中显式配置：
- BE 节点未安装系统 CA 证书，或系统 CA 证书包版本过旧。
- BE 节点运行在精简容器或镜像中，未包含
ca-certificates包。 - BE 节点上的默认 CA 文件路径无效，或 Doris 进程没有该 CA 文件的读取权限。
- 环境中使用了自签名证书、私有 CA，或者会重签 TLS 流量的企业代理或网关。
- 访问 S3 时出现
Problem with the SSL CA cert或curl 77: Problem with the SSL CA cert (path? access rights?)等错误。
示例：
# be.conf
ca_cert_file_paths = /etc/ssl/certs/ca-certificates.crt
常见的系统 CA 文件路径包括：
- Debian / Ubuntu：
/etc/ssl/certs/ca-certificates.crt - CentOS / RockyLinux：
/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
需要在所有可能访问 S3 的 BE 节点上配置该参数，并确保 Doris 进程对证书文件有读取权限。修改 be.conf 后，需要重启对应的 BE 节点使配置生效。
参数总览
| 属性名称 | 曾用名 | 描述 | 默认值 | 是否必须 |
|---|---|---|---|---|
| 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：
- 按
s3.credentials_provider_type获取源凭证。 - 用源凭证调用 STS
AssumeRole。 - 使用返回的临时凭证访问 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 | 匿名访问（适用于公开桶） |
同时配置时的生效规则
- 同时配置
s3.access_key和s3.secret_key时，优先使用 AK/SK。 - 未配置 AK/SK 且配置了
s3.role_arn时，使用 IAM Role；此时s3.credentials_provider_type用于 STS 源凭证选择。 - 未配置 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>"
}
]
}
注意事项
-
占位符替换
<bucket>→ 你的 S3 Bucket 名称。<account-id>→ 你的 AWS 账号 ID（12 位数字）。
-
最小权限原则
- 如果只做查询，不要授予写权限。
