This is an automated email from the ASF dual-hosted git repository.
dataroaring 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 98189a2a7fb [doc](iam role) Add iam role internals artical (#2833)
98189a2a7fb is described below
commit 98189a2a7fbbb9369414266dd377517d27692f21
Author: Lei Zhang <[email protected]>
AuthorDate: Fri Sep 12 14:22:11 2025 +0800
[doc](iam role) Add iam role internals artical (#2833)
## Versions
- [x] dev
- [x] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../admin-manual/auth/integrations/aws-iam-role.md | 81 +++++++++++++++++++++
.../admin-manual/auth/integrations/aws-iam-role.md | 81 +++++++++++++++++++++
.../admin-manual/auth/integrations/aws-iam-role.md | 81 +++++++++++++++++++++
sidebars.json | 3 +-
static/images/integrations/aws_iam_role_flow.png | Bin 0 -> 175688 bytes
.../images/integrations/aws_iam_role_flow_en.png | Bin 0 -> 213528 bytes
static/images/integrations/doris_iam_role.png | Bin 0 -> 60567 bytes
.../images/integrations/iam_role_access_bucket.png | Bin 0 -> 36732 bytes
.../admin-manual/auth/integrations/aws-iam-role.md | 81 +++++++++++++++++++++
versioned_sidebars/version-3.0-sidebars.json | 3 +-
10 files changed, 328 insertions(+), 2 deletions(-)
diff --git a/docs/admin-manual/auth/integrations/aws-iam-role.md
b/docs/admin-manual/auth/integrations/aws-iam-role.md
new file mode 100644
index 00000000000..557d3ed1bc8
--- /dev/null
+++ b/docs/admin-manual/auth/integrations/aws-iam-role.md
@@ -0,0 +1,81 @@
+---
+{
+ "title": "How Apache Doris IAM Assume Role work",
+ "language": "en"
+}
+---
+
+# How Apache Doris IAM Assume Role work
+
+## 1. Issues with Traditional AK/SK Access to AWS Resources
+
+### Key Management Dilemma:
+- **Long-Term Exposure Risk**：Static AK/SK must be hard-coded in configuration
files. Once the key is spread due to code leaks, mis-submissions, or malicious
theft, an attacker can permanently gain full permissions equivalent to the key
owner, leading to ongoing data leaks, resource tampering, and financial losses;
+- **Audit Blind Spot**：When multiple users/services share the same key set,
cloud operation logs only record the key identity and cannot be associated with
specific users, making it impossible to trace the true responsible individuals
or business modules;
+- **High Operational and Maintenance Cost**：Key rotation is a disaster; manual
rotation of business module keys is required, which is prone to errors and
triggering service interruptions;
+- **Uncontrolled Permission Management**：Account-level, coarse-grained
authorization fails to meet the requirements for least privilege management at
the service/instance level.
+
+## 2. Introduction to the AWS IAM Assume Role Mechanism
+
+### What is AWS IAM Assume Role?
+AWS Assume Role is a secure identity transfer mechanism that allows a trusted
entity (such as an IAM user, EC2 instance, or external account) to temporarily
obtain the permissions of a target role through STS (Security Token Service).
The process is as follows:
+
+
+
+### Advantages of using AWS IAM Assume Role for access:
+- Dynamic token mechanism (valid for 15 minutes to 12 hours) instead of
permanent keys
+- Cross-account security isolation through External IDs, auditable by AWS
backend services
+- Role-based principle of least privilege
+
+### AWS IAM Assume Role authentication process for accessing an S3 bucket:
+
+
+
+#### Phase 1: Source User Authentication
+1. **Permission Policy Check**
+ - When a source user initiates an AssumeRole request, the source account's
IAM policy engine first verifies: Is the user authorized to call the
sts:AssumeRole action?
+ - Check basis: IAM Trust Relationships Policies bound to the target role
(specifying which accounts/users are allowed to assume the role)
+
+2. **Trust Relationship Verification**
+ - Initiate a request to the target account through the STS service:
+ - Is the source user whitelisted in the target role's trust policy?
+ - Check basis: IAM Trust Relationships Policies bound to the target role
(specifying which accounts/users are allowed to assume the role)
+
+#### Phase 2: Activating target role permissions
+3. **Temporary Credential Generation**
+ If the trust relationship verification passes, STS generates three-factor
temporary credentials
+ ```json
+ {
+ "AccessKeyId": "***",
+ "SecretAccessKey": "***",
+ "SessionToken": "***" // Valid for 15 minutes to 12 hours
+ }
+ ```
+
+4. **Target Role Permission Verification**
+ - Before the target role uses the temporary credentials to access S3, the
target account's IAM policy engine verifies: Is the role authorized to perform
the requested S3 operation? (e.g., s3:GetObject, s3:PutObject, etc.)
+ - Check basis: IAM Permissions Policies attached to the target role
(defining what the role can do)
+
+#### Phase 3: Executing Resource Operations
+5. **Accessing the Bucket**
+ Only after all verifications are passed can the target role perform S3 API
operations
+
+## 3、How Doris Uses the AWS IAM Assume Role Authentication Mechanism
+1. Doris uses the AWS IAM Assume Role feature by binding the AWS EC2 instances
deployed by the FE and BE processes to the source account. The main process is
shown in the following figure:
+
+
+
+2. After configuration is complete, the Doris FE/BE processes automatically
obtain the EC2 instance profile and perform the Assume Role operation to access
the bucket. During capacity expansion, the BE node will automatically detect
whether the new EC2 instance is successfully bound to the IAM role to prevent
mismatches;
+
+3. Doris's S3 Load, TVF, Export, Resource, Repository, Storage Vault, and
other functions support the AWS Assume Role method in versions 3.0.6 and above.
Connectivity checks will be performed when executing SQL-related functions:
+ ```sql
+ CREATE REPOSITORY `s3_repo`
+ WITH S3 ON LOCATION "s3://bucket/path/"
+ PROPERTIES (
+ "s3.role_arn" = "arn:aws:iam::1234567890:role/doris-s3-role",
+ "s3.external_id" = "doris-external-id",
+ "timeout" = "3600"
+ );
+ ```
+Where "s3.role_arn" corresponds to the IAM ID in AWS IAM Account2 In the ARN
value for role2, "s3.external_id" corresponds to the externalId value
configured in the Trust Relationships Policies (optional). For more detailed
SQL statements, see:
+[AWS authentication and
authorization](../../../admin-manual/auth/integrations/aws-authentication-and-authorization.md#assumed-role-authentication).
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/integrations/aws-iam-role.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/integrations/aws-iam-role.md
new file mode 100644
index 00000000000..cd65e1fab7e
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/integrations/aws-iam-role.md
@@ -0,0 +1,81 @@
+---
+{
+ "title": "Apache Doris IAM Assume Role工作原理",
+ "language": "zh-CN"
+}
+---
+
+# Apache Doris IAM Assume Role工作原理
+
+## 一、传统AK/SK方式访问AWS资源存在的问题
+
+### 密钥管理困境：
+-
**长期暴露风险**：静态AK/SK需硬编码于配置文件中，一旦因代码泄露、误提交或恶意窃取导致密钥扩散，攻击者可永久获得等同于密钥所有者的完整权限，引发持续性的数据泄露、资源篡改及资金损失风险；
+- **审计盲区**：多用户/多服务共享同一组密钥时，云操作日志仅记录密钥身份而无法关联具体使用者，无法追溯真实责任人或业务模块；
+- **运维成本高**：密钥轮换灾难，需手动轮换业务模块密钥，容易出错触发服务中断；
+- **权限管理失控**：账户级粗放授权无法满足服务/实例级的最小权限管控需求。
+
+## 二、AWS IAM ASSUME ROLE机制介绍
+
+### AWS IAM Assume Role 是什么？
+AWS Assume Role
是一种安全身份切换机制，允许一个可信实体（如IAM用户、EC2实例或外部账号）通过STS（安全令牌服务）临时获取目标角色的权限，其运作流程如下:
+
+
+
+### 使用AWS IAM Assume Role方式访问的优点:
+- 动态令牌机制(15分钟~12小时有效期)替代永久密钥
+- 通过 External ID 实现跨账号安全隔离，并且可通过AWS后台服务进行审计
+- 基于角色的最小权限原则(Principle of Least Privilege)
+
+### AWS IAM Assume Role访问S3 Bucket的鉴权过程：
+
+
+
+#### 阶段1: 源用户身份验证
+1. **权限策略检查**
+ - 源用户发起AssumeRole请求时，源账户的IAM策略引擎首先验证：该用户是否被授权调用sts:AssumeRole操作？
+ - 检查依据：附着在源用户身份上的IAM Permissions Policies
+
+2. **信任关系校验**
+ - 通过STS服务向目标账户发起请求：
+ - 源用户是否在目标角色的信任策略白名单中？
+ - 检查依据：目标角色绑定的IAM Trust Relationships Policies（明确允许哪些账号/用户担任该角色）
+
+#### 阶段2: 目标角色权限激活
+3. **临时凭证生成**
+ 若信任关系验证通过，STS生成三要素临时凭证
+ ```json
+ {
+ "AccessKeyId": "***",
+ "SecretAccessKey": "***",
+ "SessionToken": "***" // 有效期15min-12h
+ }
+ ```
+
+4. **目标角色权限验证**
+ -
目标角色使用临时凭证访问S3前，目标账户的IAM策略引擎校验：该角色是否被授权执行请求的S3操作？（如s3:GetObject、s3:PutObject等）
+ - 检查依据：附着在目标角色上的IAM Permissions Policies（定义角色能做什么）
+
+#### 阶段3: 资源操作执行
+5. **访问存储桶**
+ 全部验证通过后，目标角色才可执行S3 API操作
+
+## 三、Doris如何应用AWS IAM Assume Role鉴权机制
+1. Doris通过将FE、BE进程所部署的AWS EC2 Instances绑定到Source Account来使用AWS IAM Assume
Role功能，主要流程如下图所示：
+
+
+
+2. 完成配置后Doris FE/BE进程会自动获取EC2 Instance的Profile执行Assume
Role操作访问Bucket。扩容时BE节点会自动检测新EC2 Instance是否成功绑定IAM Role，防止漏配;
+
+3. Doris的S3 Load、TVF、Export、Resource、Repository、Storage
Vault等功能在3.0.6+版本均支持AWS Assume Role方式，执行SQL相关功能时会进行连通性检测：
+ ```sql
+ CREATE REPOSITORY `s3_repo`
+ WITH S3 ON LOCATION "s3://bucket/path/"
+ PROPERTIES (
+ "s3.role_arn" = "arn:aws:iam::1234567890:role/doris-s3-role",
+ "s3.external_id" = "doris-external-id",
+ "timeout" = "3600"
+ );
+ ```
+其中"s3.role_arn" 对应填入AWS IAM Account2下的Iam role2的arn值,"s3.external_id"对应填入Trust
Relationships Policies中配置的externalId的值(可选配置), 更多功能SQL语句功能详细参考：
+[AWS
认证和鉴权](../../../admin-manual/auth/integrations/aws-authentication-and-authorization.md#assumed-role-authentication).
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
new file mode 100644
index 00000000000..cd65e1fab7e
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
@@ -0,0 +1,81 @@
+---
+{
+ "title": "Apache Doris IAM Assume Role工作原理",
+ "language": "zh-CN"
+}
+---
+
+# Apache Doris IAM Assume Role工作原理
+
+## 一、传统AK/SK方式访问AWS资源存在的问题
+
+### 密钥管理困境：
+-
**长期暴露风险**：静态AK/SK需硬编码于配置文件中，一旦因代码泄露、误提交或恶意窃取导致密钥扩散，攻击者可永久获得等同于密钥所有者的完整权限，引发持续性的数据泄露、资源篡改及资金损失风险；
+- **审计盲区**：多用户/多服务共享同一组密钥时，云操作日志仅记录密钥身份而无法关联具体使用者，无法追溯真实责任人或业务模块；
+- **运维成本高**：密钥轮换灾难，需手动轮换业务模块密钥，容易出错触发服务中断；
+- **权限管理失控**：账户级粗放授权无法满足服务/实例级的最小权限管控需求。
+
+## 二、AWS IAM ASSUME ROLE机制介绍
+
+### AWS IAM Assume Role 是什么？
+AWS Assume Role
是一种安全身份切换机制，允许一个可信实体（如IAM用户、EC2实例或外部账号）通过STS（安全令牌服务）临时获取目标角色的权限，其运作流程如下:
+
+
+
+### 使用AWS IAM Assume Role方式访问的优点:
+- 动态令牌机制(15分钟~12小时有效期)替代永久密钥
+- 通过 External ID 实现跨账号安全隔离，并且可通过AWS后台服务进行审计
+- 基于角色的最小权限原则(Principle of Least Privilege)
+
+### AWS IAM Assume Role访问S3 Bucket的鉴权过程：
+
+
+
+#### 阶段1: 源用户身份验证
+1. **权限策略检查**
+ - 源用户发起AssumeRole请求时，源账户的IAM策略引擎首先验证：该用户是否被授权调用sts:AssumeRole操作？
+ - 检查依据：附着在源用户身份上的IAM Permissions Policies
+
+2. **信任关系校验**
+ - 通过STS服务向目标账户发起请求：
+ - 源用户是否在目标角色的信任策略白名单中？
+ - 检查依据：目标角色绑定的IAM Trust Relationships Policies（明确允许哪些账号/用户担任该角色）
+
+#### 阶段2: 目标角色权限激活
+3. **临时凭证生成**
+ 若信任关系验证通过，STS生成三要素临时凭证
+ ```json
+ {
+ "AccessKeyId": "***",
+ "SecretAccessKey": "***",
+ "SessionToken": "***" // 有效期15min-12h
+ }
+ ```
+
+4. **目标角色权限验证**
+ -
目标角色使用临时凭证访问S3前，目标账户的IAM策略引擎校验：该角色是否被授权执行请求的S3操作？（如s3:GetObject、s3:PutObject等）
+ - 检查依据：附着在目标角色上的IAM Permissions Policies（定义角色能做什么）
+
+#### 阶段3: 资源操作执行
+5. **访问存储桶**
+ 全部验证通过后，目标角色才可执行S3 API操作
+
+## 三、Doris如何应用AWS IAM Assume Role鉴权机制
+1. Doris通过将FE、BE进程所部署的AWS EC2 Instances绑定到Source Account来使用AWS IAM Assume
Role功能，主要流程如下图所示：
+
+
+
+2. 完成配置后Doris FE/BE进程会自动获取EC2 Instance的Profile执行Assume
Role操作访问Bucket。扩容时BE节点会自动检测新EC2 Instance是否成功绑定IAM Role，防止漏配;
+
+3. Doris的S3 Load、TVF、Export、Resource、Repository、Storage
Vault等功能在3.0.6+版本均支持AWS Assume Role方式，执行SQL相关功能时会进行连通性检测：
+ ```sql
+ CREATE REPOSITORY `s3_repo`
+ WITH S3 ON LOCATION "s3://bucket/path/"
+ PROPERTIES (
+ "s3.role_arn" = "arn:aws:iam::1234567890:role/doris-s3-role",
+ "s3.external_id" = "doris-external-id",
+ "timeout" = "3600"
+ );
+ ```
+其中"s3.role_arn" 对应填入AWS IAM Account2下的Iam role2的arn值,"s3.external_id"对应填入Trust
Relationships Policies中配置的externalId的值(可选配置), 更多功能SQL语句功能详细参考：
+[AWS
认证和鉴权](../../../admin-manual/auth/integrations/aws-authentication-and-authorization.md#assumed-role-authentication).
\ No newline at end of file
diff --git a/sidebars.json b/sidebars.json
index 67c8add69f6..4700d67c7e5 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -584,7 +584,8 @@
"type": "category",
"label": "Integrations",
"items": [
-
"admin-manual/auth/integrations/aws-authentication-and-authorization"
+
"admin-manual/auth/integrations/aws-authentication-and-authorization",
+ "admin-manual/auth/integrations/aws-iam-role"
]
}
]
diff --git a/static/images/integrations/aws_iam_role_flow.png
b/static/images/integrations/aws_iam_role_flow.png
new file mode 100644
index 00000000000..a4fc816b6fb
Binary files /dev/null and b/static/images/integrations/aws_iam_role_flow.png
differ
diff --git a/static/images/integrations/aws_iam_role_flow_en.png
b/static/images/integrations/aws_iam_role_flow_en.png
new file mode 100644
index 00000000000..47529135a63
Binary files /dev/null and
b/static/images/integrations/aws_iam_role_flow_en.png differ
diff --git a/static/images/integrations/doris_iam_role.png
b/static/images/integrations/doris_iam_role.png
new file mode 100644
index 00000000000..f8a39601666
Binary files /dev/null and b/static/images/integrations/doris_iam_role.png
differ
diff --git a/static/images/integrations/iam_role_access_bucket.png
b/static/images/integrations/iam_role_access_bucket.png
new file mode 100644
index 00000000000..03f4b0b7c87
Binary files /dev/null and
b/static/images/integrations/iam_role_access_bucket.png differ
diff --git
a/versioned_docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
b/versioned_docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
new file mode 100644
index 00000000000..557d3ed1bc8
--- /dev/null
+++ b/versioned_docs/version-3.0/admin-manual/auth/integrations/aws-iam-role.md
@@ -0,0 +1,81 @@
+---
+{
+ "title": "How Apache Doris IAM Assume Role work",
+ "language": "en"
+}
+---
+
+# How Apache Doris IAM Assume Role work
+
+## 1. Issues with Traditional AK/SK Access to AWS Resources
+
+### Key Management Dilemma:
+- **Long-Term Exposure Risk**：Static AK/SK must be hard-coded in configuration
files. Once the key is spread due to code leaks, mis-submissions, or malicious
theft, an attacker can permanently gain full permissions equivalent to the key
owner, leading to ongoing data leaks, resource tampering, and financial losses;
+- **Audit Blind Spot**：When multiple users/services share the same key set,
cloud operation logs only record the key identity and cannot be associated with
specific users, making it impossible to trace the true responsible individuals
or business modules;
+- **High Operational and Maintenance Cost**：Key rotation is a disaster; manual
rotation of business module keys is required, which is prone to errors and
triggering service interruptions;
+- **Uncontrolled Permission Management**：Account-level, coarse-grained
authorization fails to meet the requirements for least privilege management at
the service/instance level.
+
+## 2. Introduction to the AWS IAM Assume Role Mechanism
+
+### What is AWS IAM Assume Role?
+AWS Assume Role is a secure identity transfer mechanism that allows a trusted
entity (such as an IAM user, EC2 instance, or external account) to temporarily
obtain the permissions of a target role through STS (Security Token Service).
The process is as follows:
+
+
+
+### Advantages of using AWS IAM Assume Role for access:
+- Dynamic token mechanism (valid for 15 minutes to 12 hours) instead of
permanent keys
+- Cross-account security isolation through External IDs, auditable by AWS
backend services
+- Role-based principle of least privilege
+
+### AWS IAM Assume Role authentication process for accessing an S3 bucket:
+
+
+
+#### Phase 1: Source User Authentication
+1. **Permission Policy Check**
+ - When a source user initiates an AssumeRole request, the source account's
IAM policy engine first verifies: Is the user authorized to call the
sts:AssumeRole action?
+ - Check basis: IAM Trust Relationships Policies bound to the target role
(specifying which accounts/users are allowed to assume the role)
+
+2. **Trust Relationship Verification**
+ - Initiate a request to the target account through the STS service:
+ - Is the source user whitelisted in the target role's trust policy?
+ - Check basis: IAM Trust Relationships Policies bound to the target role
(specifying which accounts/users are allowed to assume the role)
+
+#### Phase 2: Activating target role permissions
+3. **Temporary Credential Generation**
+ If the trust relationship verification passes, STS generates three-factor
temporary credentials
+ ```json
+ {
+ "AccessKeyId": "***",
+ "SecretAccessKey": "***",
+ "SessionToken": "***" // Valid for 15 minutes to 12 hours
+ }
+ ```
+
+4. **Target Role Permission Verification**
+ - Before the target role uses the temporary credentials to access S3, the
target account's IAM policy engine verifies: Is the role authorized to perform
the requested S3 operation? (e.g., s3:GetObject, s3:PutObject, etc.)
+ - Check basis: IAM Permissions Policies attached to the target role
(defining what the role can do)
+
+#### Phase 3: Executing Resource Operations
+5. **Accessing the Bucket**
+ Only after all verifications are passed can the target role perform S3 API
operations
+
+## 3、How Doris Uses the AWS IAM Assume Role Authentication Mechanism
+1. Doris uses the AWS IAM Assume Role feature by binding the AWS EC2 instances
deployed by the FE and BE processes to the source account. The main process is
shown in the following figure:
+
+
+
+2. After configuration is complete, the Doris FE/BE processes automatically
obtain the EC2 instance profile and perform the Assume Role operation to access
the bucket. During capacity expansion, the BE node will automatically detect
whether the new EC2 instance is successfully bound to the IAM role to prevent
mismatches;
+
+3. Doris's S3 Load, TVF, Export, Resource, Repository, Storage Vault, and
other functions support the AWS Assume Role method in versions 3.0.6 and above.
Connectivity checks will be performed when executing SQL-related functions:
+ ```sql
+ CREATE REPOSITORY `s3_repo`
+ WITH S3 ON LOCATION "s3://bucket/path/"
+ PROPERTIES (
+ "s3.role_arn" = "arn:aws:iam::1234567890:role/doris-s3-role",
+ "s3.external_id" = "doris-external-id",
+ "timeout" = "3600"
+ );
+ ```
+Where "s3.role_arn" corresponds to the IAM ID in AWS IAM Account2 In the ARN
value for role2, "s3.external_id" corresponds to the externalId value
configured in the Trust Relationships Policies (optional). For more detailed
SQL statements, see:
+[AWS authentication and
authorization](../../../admin-manual/auth/integrations/aws-authentication-and-authorization.md#assumed-role-authentication).
\ No newline at end of file
diff --git a/versioned_sidebars/version-3.0-sidebars.json
b/versioned_sidebars/version-3.0-sidebars.json
index af4e5ca14ab..9488faf6f7e 100644
--- a/versioned_sidebars/version-3.0-sidebars.json
+++ b/versioned_sidebars/version-3.0-sidebars.json
@@ -565,7 +565,8 @@
"type": "category",
"label": "Integrations",
"items": [
-
"admin-manual/auth/integrations/aws-authentication-and-authorization"
+
"admin-manual/auth/integrations/aws-authentication-and-authorization",
+ "admin-manual/auth/integrations/aws-iam-role"
]
}
]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
