This is an automated email from the ASF dual-hosted git repository.
kirs pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 1058f5c866d Add s3.credentials_provider_type docs (#3427)
1058f5c866d is described below
commit 1058f5c866d52810dc3733aaf08e32b51c4180c0
Author: Calvin Kirs <[email protected]>
AuthorDate: Fri Mar 6 12:06:38 2026 +0800
Add s3.credentials_provider_type docs (#3427)
## Versions
- [ ] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
docs/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../current/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-2.1/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-3.x/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-4.x/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-2.1/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-3.x/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
.../version-4.x/lakehouse/storages/s3.md | 136 ++++++++++++++++-----
8 files changed, 856 insertions(+), 232 deletions(-)
diff --git a/docs/lakehouse/storages/s3.md b/docs/lakehouse/storages/s3.md
index 97f55b50936..8705e7709b5 100644
--- a/docs/lakehouse/storages/s3.md
+++ b/docs/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@ This document describes the parameters required for
accessing AWS S3. These para
## Parameter Overview
-| Property Name | Legacy Name | Description
| Default | Required |
-|------------------------------|-------------|--------------------------------------------------|---------|----------|
-| s3.endpoint | | S3 service access endpoint,
e.g., s3.us-east-1.amazonaws.com | None | No |
-| s3.access_key | | AWS Access Key for
authentication | None | No |
-| s3.secret_key | | AWS Secret Key for
authentication | None | No |
-| s3.region | | S3 region, e.g., us-east-1.
Strongly recommended | None | Yes |
-| s3.use_path_style | | Whether to use path-style
access | FALSE | No |
-| s3.connection.maximum | | Maximum number of connections
for high concurrency scenarios | 50 | No |
-| s3.connection.request.timeout| | Request timeout (milliseconds),
controls connection acquisition timeout | 3000 | No |
-| s3.connection.timeout | | Connection establishment
timeout (milliseconds) | 1000 | No |
-| s3.role_arn | | Role ARN specified when using
Assume Role mode | None | No |
-| s3.external_id | | External ID used with
s3.role_arn | None | No |
+| Property Name | Legacy Name | Description
| Default |
Required |
+|------------------------------|-------------------------------|-----------------------------------------------------------------------------|---------|----------|
+| s3.endpoint | | S3 service
access endpoint, e.g., `s3.us-east-1.amazonaws.com` | None | No
|
+| s3.access_key | | AWS Access
Key for authentication | None | No
|
+| s3.secret_key | | AWS Secret
Key for authentication | None | No
|
+| s3.region | | S3 region,
e.g., `us-east-1`. Strongly recommended | None | Yes
|
+| s3.use_path_style | | Whether to
use path-style access | FALSE | No
|
+| s3.connection.maximum | | Maximum
number of connections for high concurrency scenarios | 50 |
No |
+| s3.connection.request.timeout| | Request
timeout (milliseconds), controls connection acquisition timeout | 3000 |
No |
+| s3.connection.timeout | | Connection
establishment timeout (milliseconds) | 1000 | No
|
+| s3.role_arn | | Role ARN
specified when using Assume Role mode | None |
No |
+| s3.external_id | | External ID
used with `s3.role_arn` | None | No
|
+| s3.credentials_provider_type | | Credentials
provider type for AWS authentication (used without AK/SK; used as STS source
credentials in IAM Role mode) | DEFAULT | No |
+
+> Version note: `s3.credentials_provider_type` is supported since **3.1.4**
and **4.0.3**.
## Authentication Configuration
-Doris supports the following two methods to access S3:
+Doris supports the following three methods to access S3:
-1. Direct Access Key and Secret Key
+### 1. Direct Access Key and Secret Key (AK/SK)
- ```properties
- "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"
- ```
+```properties
+"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) mode
+
+Suitable for cross-account and temporary authorization access. Doris
automatically obtains temporary credentials through role authorization.
+
+```properties
+"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"
+```
+
+#### Configure `s3.credentials_provider_type` in IAM Role mode
+
+When `s3.role_arn` is configured, `s3.credentials_provider_type` controls
which source credentials provider is used for STS `AssumeRole`:
+
+1. Get source credentials from `s3.credentials_provider_type`.
+2. Call STS `AssumeRole` with source credentials.
+3. Access S3 with the returned temporary credentials.
+
+#### IAM Role + `s3.credentials_provider_type` examples
+
+**Example 1: EC2 Instance Profile as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 2: Web Identity (for example IRSA) as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 3: Container metadata as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 4: Default provider chain as STS source credentials**
+
+```properties
+"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. Specify credential source with `s3.credentials_provider_type`
+
+This is suitable for scenarios without explicit AK/SK, such as EC2 Instance
Profile, container metadata, or Web Identity.
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### Supported values for `s3.credentials_provider_type`
-2. Assume Role Mode
+| Value | Description |
+|-------------------|-------------|
+| DEFAULT | Use default provider chain |
+| ENV | Read credentials from environment variables |
+| SYSTEM_PROPERTIES | Read credentials from system properties |
+| WEB_IDENTITY | Use Web Identity Token credentials |
+| CONTAINER | Use container metadata credentials |
+| INSTANCE_PROFILE | Use EC2 Instance Profile credentials |
+| ANONYMOUS | Anonymous access (for public buckets) |
- Suitable for cross-account and temporary authorization access. Automatically
obtains temporary credentials through role authorization.
+### Effective rules when configured together
- ```properties
- "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"
- ```
+1. If `s3.access_key` and `s3.secret_key` are both configured, AK/SK is used
first.
+2. If AK/SK is not configured and `s3.role_arn` is configured, IAM Role is
used. In this case, `s3.credentials_provider_type` is used to select STS source
credentials.
+3. If neither AK/SK nor `s3.role_arn` is configured,
`s3.credentials_provider_type` directly determines the credentials provider
used by the S3 client.
-> If both Access Key and Role ARN are configured, Access Key mode takes
precedence.
+> Note: `s3.access_key` and `s3.secret_key` must be configured together.
For instructions on AWS authentication and authorization configuration, please
refer to the document
[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/s3.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/s3.md
index 6b215787995..f7968258697 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/s3.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@
## 参数总览
-| 属性名称 | 曾用名 | 描述 |
默认值 | 是否必须 |
-|------------------------------|--------|-------------------------------------------|--------|----------|
-| 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.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：
+Doris 支持以下三种方式访问 S3：
-1. 直接使用 Access Key 和 Secret Key
+### 1. 直接使用 Access Key 和 Secret Key（AK/SK）
- ```properties
- "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"
- ```
+```properties
+"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）模式
+
+适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 等。
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### `s3.credentials_provider_type` 可选值
-2. Assume Role 模式
+| 值 | 说明 |
+|-------------------|------|
+| DEFAULT | 使用默认 provider chain |
+| ENV | 从环境变量读取凭证 |
+| SYSTEM_PROPERTIES | 从系统属性读取凭证 |
+| WEB_IDENTITY | 使用 Web Identity Token 凭证 |
+| CONTAINER | 使用容器元数据凭证 |
+| INSTANCE_PROFILE | 使用 EC2 Instance Profile 凭证 |
+| ANONYMOUS | 匿名访问（适用于公开桶） |
- 适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+### 同时配置时的生效规则
- ```properties
- "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"
- ```
+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。
-> 如果同时设置了 Access Key 和 Role ARN，则优先使用 Access Key 模式。
+> 注意：`s3.access_key` 和 `s3.secret_key` 必须成对出现，仅配置其中一个会报错。
AWS
认证鉴权配置说明请参阅文档[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/lakehouse/storages/s3.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/lakehouse/storages/s3.md
index a0d275f715d..ae560721fb1 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/lakehouse/storages/s3.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@
## 参数总览
-| 属性名称 | 曾用名 | 描述 |
默认值 | 是否必须 |
-|------------------------------|--------|-------------------------------------------|--------|----------|
-| 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.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：
+Doris 支持以下三种方式访问 S3：
-1. 直接使用 Access Key 和 Secret Key
+### 1. 直接使用 Access Key 和 Secret Key（AK/SK）
- ```properties
- "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"
- ```
+```properties
+"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）模式
+
+适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 等。
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### `s3.credentials_provider_type` 可选值
-2. Assume Role 模式
+| 值 | 说明 |
+|-------------------|------|
+| DEFAULT | 使用默认 provider chain |
+| ENV | 从环境变量读取凭证 |
+| SYSTEM_PROPERTIES | 从系统属性读取凭证 |
+| WEB_IDENTITY | 使用 Web Identity Token 凭证 |
+| CONTAINER | 使用容器元数据凭证 |
+| INSTANCE_PROFILE | 使用 EC2 Instance Profile 凭证 |
+| ANONYMOUS | 匿名访问（适用于公开桶） |
- 适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+### 同时配置时的生效规则
- ```properties
- "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"
- ```
+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。
-> 如果同时设置了 Access Key 和 Role ARN，则优先使用 Access Key 模式。
+> 注意：`s3.access_key` 和 `s3.secret_key` 必须成对出现，仅配置其中一个会报错。
## 访问 S3 Directory Bucket
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/s3.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/s3.md
index 6b215787995..f7968258697 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/s3.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@
## 参数总览
-| 属性名称 | 曾用名 | 描述 |
默认值 | 是否必须 |
-|------------------------------|--------|-------------------------------------------|--------|----------|
-| 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.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：
+Doris 支持以下三种方式访问 S3：
-1. 直接使用 Access Key 和 Secret Key
+### 1. 直接使用 Access Key 和 Secret Key（AK/SK）
- ```properties
- "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"
- ```
+```properties
+"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）模式
+
+适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 等。
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### `s3.credentials_provider_type` 可选值
-2. Assume Role 模式
+| 值 | 说明 |
+|-------------------|------|
+| DEFAULT | 使用默认 provider chain |
+| ENV | 从环境变量读取凭证 |
+| SYSTEM_PROPERTIES | 从系统属性读取凭证 |
+| WEB_IDENTITY | 使用 Web Identity Token 凭证 |
+| CONTAINER | 使用容器元数据凭证 |
+| INSTANCE_PROFILE | 使用 EC2 Instance Profile 凭证 |
+| ANONYMOUS | 匿名访问（适用于公开桶） |
- 适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+### 同时配置时的生效规则
- ```properties
- "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"
- ```
+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。
-> 如果同时设置了 Access Key 和 Role ARN，则优先使用 Access Key 模式。
+> 注意：`s3.access_key` 和 `s3.secret_key` 必须成对出现，仅配置其中一个会报错。
AWS
认证鉴权配置说明请参阅文档[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/s3.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/s3.md
index 6b215787995..f7968258697 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/s3.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@
## 参数总览
-| 属性名称 | 曾用名 | 描述 |
默认值 | 是否必须 |
-|------------------------------|--------|-------------------------------------------|--------|----------|
-| 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.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：
+Doris 支持以下三种方式访问 S3：
-1. 直接使用 Access Key 和 Secret Key
+### 1. 直接使用 Access Key 和 Secret Key（AK/SK）
- ```properties
- "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"
- ```
+```properties
+"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）模式
+
+适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 源凭证**
+
+```properties
+"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 等。
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### `s3.credentials_provider_type` 可选值
-2. Assume Role 模式
+| 值 | 说明 |
+|-------------------|------|
+| DEFAULT | 使用默认 provider chain |
+| ENV | 从环境变量读取凭证 |
+| SYSTEM_PROPERTIES | 从系统属性读取凭证 |
+| WEB_IDENTITY | 使用 Web Identity Token 凭证 |
+| CONTAINER | 使用容器元数据凭证 |
+| INSTANCE_PROFILE | 使用 EC2 Instance Profile 凭证 |
+| ANONYMOUS | 匿名访问（适用于公开桶） |
- 适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。
+### 同时配置时的生效规则
- ```properties
- "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"
- ```
+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。
-> 如果同时设置了 Access Key 和 Role ARN，则优先使用 Access Key 模式。
+> 注意：`s3.access_key` 和 `s3.secret_key` 必须成对出现，仅配置其中一个会报错。
AWS
认证鉴权配置说明请参阅文档[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
diff --git a/versioned_docs/version-2.1/lakehouse/storages/s3.md
b/versioned_docs/version-2.1/lakehouse/storages/s3.md
index 1f2ba5d54e5..f4557a36d00 100644
--- a/versioned_docs/version-2.1/lakehouse/storages/s3.md
+++ b/versioned_docs/version-2.1/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@ This document describes the parameters required for
accessing AWS S3. These para
## Parameter Overview
-| Property Name | Legacy Name | Description
| Default | Required |
-|------------------------------|-------------|--------------------------------------------------|---------|----------|
-| s3.endpoint | | S3 service access endpoint,
e.g., s3.us-east-1.amazonaws.com | None | No |
-| s3.access_key | | AWS Access Key for
authentication | None | No |
-| s3.secret_key | | AWS Secret Key for
authentication | None | No |
-| s3.region | | S3 region, e.g., us-east-1.
Strongly recommended | None | Yes |
-| s3.use_path_style | | Whether to use path-style
access | FALSE | No |
-| s3.connection.maximum | | Maximum number of connections
for high concurrency scenarios | 50 | No |
-| s3.connection.request.timeout| | Request timeout (milliseconds),
controls connection acquisition timeout | 3000 | No |
-| s3.connection.timeout | | Connection establishment
timeout (milliseconds) | 1000 | No |
-| s3.role_arn | | Role ARN specified when using
Assume Role mode | None | No |
-| s3.external_id | | External ID used with
s3.role_arn | None | No |
+| Property Name | Legacy Name | Description
| Default |
Required |
+|------------------------------|-------------------------------|-----------------------------------------------------------------------------|---------|----------|
+| s3.endpoint | | S3 service
access endpoint, e.g., `s3.us-east-1.amazonaws.com` | None | No
|
+| s3.access_key | | AWS Access
Key for authentication | None | No
|
+| s3.secret_key | | AWS Secret
Key for authentication | None | No
|
+| s3.region | | S3 region,
e.g., `us-east-1`. Strongly recommended | None | Yes
|
+| s3.use_path_style | | Whether to
use path-style access | FALSE | No
|
+| s3.connection.maximum | | Maximum
number of connections for high concurrency scenarios | 50 |
No |
+| s3.connection.request.timeout| | Request
timeout (milliseconds), controls connection acquisition timeout | 3000 |
No |
+| s3.connection.timeout | | Connection
establishment timeout (milliseconds) | 1000 | No
|
+| s3.role_arn | | Role ARN
specified when using Assume Role mode | None |
No |
+| s3.external_id | | External ID
used with `s3.role_arn` | None | No
|
+| s3.credentials_provider_type | | Credentials
provider type for AWS authentication (used without AK/SK; used as STS source
credentials in IAM Role mode) | DEFAULT | No |
+
+> Version note: `s3.credentials_provider_type` is supported since **3.1.4**
and **4.0.3**.
## Authentication Configuration
-Doris supports the following two methods to access S3:
+Doris supports the following three methods to access S3:
-1. Direct Access Key and Secret Key
+### 1. Direct Access Key and Secret Key (AK/SK)
- ```properties
- "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"
- ```
+```properties
+"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) mode
+
+Suitable for cross-account and temporary authorization access. Doris
automatically obtains temporary credentials through role authorization.
+
+```properties
+"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"
+```
+
+#### Configure `s3.credentials_provider_type` in IAM Role mode
+
+When `s3.role_arn` is configured, `s3.credentials_provider_type` controls
which source credentials provider is used for STS `AssumeRole`:
+
+1. Get source credentials from `s3.credentials_provider_type`.
+2. Call STS `AssumeRole` with source credentials.
+3. Access S3 with the returned temporary credentials.
+
+#### IAM Role + `s3.credentials_provider_type` examples
+
+**Example 1: EC2 Instance Profile as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 2: Web Identity (for example IRSA) as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 3: Container metadata as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 4: Default provider chain as STS source credentials**
+
+```properties
+"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. Specify credential source with `s3.credentials_provider_type`
+
+This is suitable for scenarios without explicit AK/SK, such as EC2 Instance
Profile, container metadata, or Web Identity.
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### Supported values for `s3.credentials_provider_type`
-2. Assume Role Mode
+| Value | Description |
+|-------------------|-------------|
+| DEFAULT | Use default provider chain |
+| ENV | Read credentials from environment variables |
+| SYSTEM_PROPERTIES | Read credentials from system properties |
+| WEB_IDENTITY | Use Web Identity Token credentials |
+| CONTAINER | Use container metadata credentials |
+| INSTANCE_PROFILE | Use EC2 Instance Profile credentials |
+| ANONYMOUS | Anonymous access (for public buckets) |
- Suitable for cross-account and temporary authorization access. Automatically
obtains temporary credentials through role authorization.
+### Effective rules when configured together
- ```properties
- "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"
- ```
+1. If `s3.access_key` and `s3.secret_key` are both configured, AK/SK is used
first.
+2. If AK/SK is not configured and `s3.role_arn` is configured, IAM Role is
used. In this case, `s3.credentials_provider_type` is used to select STS source
credentials.
+3. If neither AK/SK nor `s3.role_arn` is configured,
`s3.credentials_provider_type` directly determines the credentials provider
used by the S3 client.
-> If both Access Key and Role ARN are configured, Access Key mode takes
precedence.
+> Note: `s3.access_key` and `s3.secret_key` must be configured together.
## Accessing S3 Directory Bucket
diff --git a/versioned_docs/version-3.x/lakehouse/storages/s3.md
b/versioned_docs/version-3.x/lakehouse/storages/s3.md
index 97f55b50936..8705e7709b5 100644
--- a/versioned_docs/version-3.x/lakehouse/storages/s3.md
+++ b/versioned_docs/version-3.x/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@ This document describes the parameters required for
accessing AWS S3. These para
## Parameter Overview
-| Property Name | Legacy Name | Description
| Default | Required |
-|------------------------------|-------------|--------------------------------------------------|---------|----------|
-| s3.endpoint | | S3 service access endpoint,
e.g., s3.us-east-1.amazonaws.com | None | No |
-| s3.access_key | | AWS Access Key for
authentication | None | No |
-| s3.secret_key | | AWS Secret Key for
authentication | None | No |
-| s3.region | | S3 region, e.g., us-east-1.
Strongly recommended | None | Yes |
-| s3.use_path_style | | Whether to use path-style
access | FALSE | No |
-| s3.connection.maximum | | Maximum number of connections
for high concurrency scenarios | 50 | No |
-| s3.connection.request.timeout| | Request timeout (milliseconds),
controls connection acquisition timeout | 3000 | No |
-| s3.connection.timeout | | Connection establishment
timeout (milliseconds) | 1000 | No |
-| s3.role_arn | | Role ARN specified when using
Assume Role mode | None | No |
-| s3.external_id | | External ID used with
s3.role_arn | None | No |
+| Property Name | Legacy Name | Description
| Default |
Required |
+|------------------------------|-------------------------------|-----------------------------------------------------------------------------|---------|----------|
+| s3.endpoint | | S3 service
access endpoint, e.g., `s3.us-east-1.amazonaws.com` | None | No
|
+| s3.access_key | | AWS Access
Key for authentication | None | No
|
+| s3.secret_key | | AWS Secret
Key for authentication | None | No
|
+| s3.region | | S3 region,
e.g., `us-east-1`. Strongly recommended | None | Yes
|
+| s3.use_path_style | | Whether to
use path-style access | FALSE | No
|
+| s3.connection.maximum | | Maximum
number of connections for high concurrency scenarios | 50 |
No |
+| s3.connection.request.timeout| | Request
timeout (milliseconds), controls connection acquisition timeout | 3000 |
No |
+| s3.connection.timeout | | Connection
establishment timeout (milliseconds) | 1000 | No
|
+| s3.role_arn | | Role ARN
specified when using Assume Role mode | None |
No |
+| s3.external_id | | External ID
used with `s3.role_arn` | None | No
|
+| s3.credentials_provider_type | | Credentials
provider type for AWS authentication (used without AK/SK; used as STS source
credentials in IAM Role mode) | DEFAULT | No |
+
+> Version note: `s3.credentials_provider_type` is supported since **3.1.4**
and **4.0.3**.
## Authentication Configuration
-Doris supports the following two methods to access S3:
+Doris supports the following three methods to access S3:
-1. Direct Access Key and Secret Key
+### 1. Direct Access Key and Secret Key (AK/SK)
- ```properties
- "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"
- ```
+```properties
+"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) mode
+
+Suitable for cross-account and temporary authorization access. Doris
automatically obtains temporary credentials through role authorization.
+
+```properties
+"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"
+```
+
+#### Configure `s3.credentials_provider_type` in IAM Role mode
+
+When `s3.role_arn` is configured, `s3.credentials_provider_type` controls
which source credentials provider is used for STS `AssumeRole`:
+
+1. Get source credentials from `s3.credentials_provider_type`.
+2. Call STS `AssumeRole` with source credentials.
+3. Access S3 with the returned temporary credentials.
+
+#### IAM Role + `s3.credentials_provider_type` examples
+
+**Example 1: EC2 Instance Profile as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 2: Web Identity (for example IRSA) as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 3: Container metadata as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 4: Default provider chain as STS source credentials**
+
+```properties
+"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. Specify credential source with `s3.credentials_provider_type`
+
+This is suitable for scenarios without explicit AK/SK, such as EC2 Instance
Profile, container metadata, or Web Identity.
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### Supported values for `s3.credentials_provider_type`
-2. Assume Role Mode
+| Value | Description |
+|-------------------|-------------|
+| DEFAULT | Use default provider chain |
+| ENV | Read credentials from environment variables |
+| SYSTEM_PROPERTIES | Read credentials from system properties |
+| WEB_IDENTITY | Use Web Identity Token credentials |
+| CONTAINER | Use container metadata credentials |
+| INSTANCE_PROFILE | Use EC2 Instance Profile credentials |
+| ANONYMOUS | Anonymous access (for public buckets) |
- Suitable for cross-account and temporary authorization access. Automatically
obtains temporary credentials through role authorization.
+### Effective rules when configured together
- ```properties
- "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"
- ```
+1. If `s3.access_key` and `s3.secret_key` are both configured, AK/SK is used
first.
+2. If AK/SK is not configured and `s3.role_arn` is configured, IAM Role is
used. In this case, `s3.credentials_provider_type` is used to select STS source
credentials.
+3. If neither AK/SK nor `s3.role_arn` is configured,
`s3.credentials_provider_type` directly determines the credentials provider
used by the S3 client.
-> If both Access Key and Role ARN are configured, Access Key mode takes
precedence.
+> Note: `s3.access_key` and `s3.secret_key` must be configured together.
For instructions on AWS authentication and authorization configuration, please
refer to the document
[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
diff --git a/versioned_docs/version-4.x/lakehouse/storages/s3.md
b/versioned_docs/version-4.x/lakehouse/storages/s3.md
index da7196f4a3f..2abf4b51c03 100644
--- a/versioned_docs/version-4.x/lakehouse/storages/s3.md
+++ b/versioned_docs/version-4.x/lakehouse/storages/s3.md
@@ -19,44 +19,122 @@ This document describes the parameters required for
accessing AWS S3. These para
## Parameter Overview
-| Property Name | Legacy Name | Description
| Default | Required |
-|------------------------------|-------------|--------------------------------------------------|---------|----------|
-| s3.endpoint | | S3 service access endpoint,
e.g., s3.us-east-1.amazonaws.com | None | No |
-| s3.access_key | | AWS Access Key for
authentication | None | No |
-| s3.secret_key | | AWS Secret Key for
authentication | None | No |
-| s3.region | | S3 region, e.g., us-east-1.
Strongly recommended | None | Yes |
-| s3.use_path_style | | Whether to use path-style
access | FALSE | No |
-| s3.connection.maximum | | Maximum number of connections
for high concurrency scenarios | 50 | No |
-| s3.connection.request.timeout| | Request timeout (milliseconds),
controls connection acquisition timeout | 3000 | No |
-| s3.connection.timeout | | Connection establishment
timeout (milliseconds) | 1000 | No |
-| s3.role_arn | | Role ARN specified when using
Assume Role mode | None | No |
-| s3.external_id | | External ID used with
s3.role_arn | None | No |
+| Property Name | Legacy Name | Description
| Default |
Required |
+|------------------------------|-------------------------------|-----------------------------------------------------------------------------|---------|----------|
+| s3.endpoint | | S3 service
access endpoint, e.g., `s3.us-east-1.amazonaws.com` | None | No
|
+| s3.access_key | | AWS Access
Key for authentication | None | No
|
+| s3.secret_key | | AWS Secret
Key for authentication | None | No
|
+| s3.region | | S3 region,
e.g., `us-east-1`. Strongly recommended | None | Yes
|
+| s3.use_path_style | | Whether to
use path-style access | FALSE | No
|
+| s3.connection.maximum | | Maximum
number of connections for high concurrency scenarios | 50 |
No |
+| s3.connection.request.timeout| | Request
timeout (milliseconds), controls connection acquisition timeout | 3000 |
No |
+| s3.connection.timeout | | Connection
establishment timeout (milliseconds) | 1000 | No
|
+| s3.role_arn | | Role ARN
specified when using Assume Role mode | None |
No |
+| s3.external_id | | External ID
used with `s3.role_arn` | None | No
|
+| s3.credentials_provider_type | | Credentials
provider type for AWS authentication (used without AK/SK; used as STS source
credentials in IAM Role mode) | DEFAULT | No |
+
+> Version note: `s3.credentials_provider_type` is supported since **3.1.4**
and **4.0.3**.
## Authentication Configuration
-Doris supports the following two methods to access S3:
+Doris supports the following three methods to access S3:
-1. Direct Access Key and Secret Key
+### 1. Direct Access Key and Secret Key (AK/SK)
- ```properties
- "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"
- ```
+```properties
+"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) mode
+
+Suitable for cross-account and temporary authorization access. Doris
automatically obtains temporary credentials through role authorization.
+
+```properties
+"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"
+```
+
+#### Configure `s3.credentials_provider_type` in IAM Role mode
+
+When `s3.role_arn` is configured, `s3.credentials_provider_type` controls
which source credentials provider is used for STS `AssumeRole`:
+
+1. Get source credentials from `s3.credentials_provider_type`.
+2. Call STS `AssumeRole` with source credentials.
+3. Access S3 with the returned temporary credentials.
+
+#### IAM Role + `s3.credentials_provider_type` examples
+
+**Example 1: EC2 Instance Profile as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 2: Web Identity (for example IRSA) as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 3: Container metadata as STS source credentials**
+
+```properties
+"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"
+```
+
+**Example 4: Default provider chain as STS source credentials**
+
+```properties
+"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. Specify credential source with `s3.credentials_provider_type`
+
+This is suitable for scenarios without explicit AK/SK, such as EC2 Instance
Profile, container metadata, or Web Identity.
+
+```properties
+"s3.credentials_provider_type"="INSTANCE_PROFILE",
+"s3.endpoint"="s3.us-east-1.amazonaws.com",
+"s3.region"="us-east-1"
+```
+
+### Supported values for `s3.credentials_provider_type`
-2. Assume Role Mode
+| Value | Description |
+|-------------------|-------------|
+| DEFAULT | Use default provider chain |
+| ENV | Read credentials from environment variables |
+| SYSTEM_PROPERTIES | Read credentials from system properties |
+| WEB_IDENTITY | Use Web Identity Token credentials |
+| CONTAINER | Use container metadata credentials |
+| INSTANCE_PROFILE | Use EC2 Instance Profile credentials |
+| ANONYMOUS | Anonymous access (for public buckets) |
- Suitable for cross-account and temporary authorization access. Automatically
obtains temporary credentials through role authorization.
+### Effective rules when configured together
- ```properties
- "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"
- ```
+1. If `s3.access_key` and `s3.secret_key` are both configured, AK/SK is used
first.
+2. If AK/SK is not configured and `s3.role_arn` is configured, IAM Role is
used. In this case, `s3.credentials_provider_type` is used to select STS source
credentials.
+3. If neither AK/SK nor `s3.role_arn` is configured,
`s3.credentials_provider_type` directly determines the credentials provider
used by the S3 client.
-> If both Access Key and Role ARN are configured, Access Key mode takes
precedence.
+> Note: `s3.access_key` and `s3.secret_key` must be configured together.
For instructions on AWS authentication and authorization configuration, please
refer to the document
[aws-authentication-and-authorization](../../admin-manual/auth/integrations/aws-authentication-and-authorization.md)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
