This is an automated email from the ASF dual-hosted git repository.
zhangshenghang pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new f5a679e71c [Docs][Connector-V2] Improve S3File HdfsFile FtpFile
CosFile and ObsFile connector docs (#11764)
f5a679e71c is described below
commit f5a679e71c603deabc9f99924c299cb381898177
Author: Daniel Carter <[email protected]>
AuthorDate: Tue Aug 11 20:42:35 2026 +0800
[Docs][Connector-V2] Improve S3File HdfsFile FtpFile CosFile and ObsFile
connector docs (#11764)
Co-authored-by: DanielCarter-stack
<[email protected]>
---
docs/en/connectors/sink/FtpFile.md | 22 ++++++++++++++++++++++
docs/en/connectors/sink/HdfsFile.md | 18 ++++++++++++++++++
docs/en/connectors/sink/S3File.md | 24 ++++++++++++++++++++++++
docs/en/connectors/source/CosFile.md | 6 +++---
docs/en/connectors/source/FtpFile.md | 25 +++++++++++++++++++++++++
docs/en/connectors/source/HdfsFile.md | 17 +++++++++++++++++
docs/en/connectors/source/ObsFile.md | 22 ++++++++++++++++++++++
docs/en/connectors/source/S3File.md | 23 +++++++++++++++++++++++
docs/zh/connectors/sink/FtpFile.md | 22 ++++++++++++++++++++++
docs/zh/connectors/sink/HdfsFile.md | 18 ++++++++++++++++++
docs/zh/connectors/sink/S3File.md | 24 ++++++++++++++++++++++++
docs/zh/connectors/source/CosFile.md | 6 +++---
docs/zh/connectors/source/FtpFile.md | 25 +++++++++++++++++++++++++
docs/zh/connectors/source/HdfsFile.md | 17 +++++++++++++++++
docs/zh/connectors/source/ObsFile.md | 22 ++++++++++++++++++++++
docs/zh/connectors/source/S3File.md | 23 +++++++++++++++++++++++
16 files changed, 308 insertions(+), 6 deletions(-)
diff --git a/docs/en/connectors/sink/FtpFile.md
b/docs/en/connectors/sink/FtpFile.md
index 75963ae937..3ff9da2fc8 100644
--- a/docs/en/connectors/sink/FtpFile.md
+++ b/docs/en/connectors/sink/FtpFile.md
@@ -400,6 +400,28 @@ FtpFile {
```
+### Writing via SFTP
+
+The `FtpFile` sink supports `sftp://` URIs alongside `ftp://`. Authentication
and host-key trust are configured the same way as for the source — SSH key or
password plus a `known_hosts` file (the connector does not auto-trust unknown
hosts).
+
+```hocon
+sink {
+ FtpFile {
+ fs.defaultFS = "sftp://sftp.example.example.com:22";
+ path = "/upload/landing/"
+ user = "seatunnel"
+ file_format_type = "parquet"
+ ftp_properties = {
+ "fs.sftp.user." = "seatunnel"
+ "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
+ "fs.sftp.host" = "sftp.example.example.com"
+ "fs.sftp.port" = "22"
+ "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
+ }
+ }
+}
+```
+
## Changelog
diff --git a/docs/en/connectors/sink/HdfsFile.md
b/docs/en/connectors/sink/HdfsFile.md
index c47d7d2f2a..3674741e8d 100644
--- a/docs/en/connectors/sink/HdfsFile.md
+++ b/docs/en/connectors/sink/HdfsFile.md
@@ -324,6 +324,24 @@ Configure mount table in `core-site.xml`:
</configuration>
```
+### Writing to an HA HDFS Cluster (Kerberos-enabled)
+
+When writing to an HA HDFS cluster that uses Kerberos, supply the Kerberos
principal/keytab in addition to the nameservice URI. The connector picks up the
same authentication the rest of your Hadoop tooling uses, so the principal's
HDFS permissions must allow writes to the target directory.
+
+```hocon
+sink {
+ HdfsFile {
+ fs.defaultFS = "hdfs://mycluster"
+ path = "/data/landing/events"
+ file_format_type = "parquet"
+ hdfs_site_path = "/etc/hadoop/conf/hdfs-site.xml"
+ kerberos_principal = "[email protected]"
+ krb5_path = "/etc/krb5.conf"
+ }
+}
+```
+
+The `kerberos_principal` and `krb5_path` values are forwarded to the Hadoop
FileSystem client; the connector does not perform a `kinit` itself, so the
keytab must already be discoverable on every worker node (typically via
`KRB5CCNAME` / a `kinit` cron) or supplied to the same JVM via standard Hadoop
authentication utilities. For cluster-level auth issues, check the worker logs
for `LoginException` / `KrbException` messages — those indicate a credential
problem, not a connector bug.
## Changelog
diff --git a/docs/en/connectors/sink/S3File.md
b/docs/en/connectors/sink/S3File.md
index 2a3de2607a..d71bdf69bb 100644
--- a/docs/en/connectors/sink/S3File.md
+++ b/docs/en/connectors/sink/S3File.md
@@ -560,6 +560,30 @@ S3File {
For production jobs, avoid hardcoding long-lived keys in job files. Prefer an
IAM-based provider such as `fs.s3a.aws.credentials.provider =
com.amazonaws.auth.InstanceProfileCredentialsProvider`, or inject `access_key`
and `secret_key` with SeaTunnel variable substitution.
+### Writing with STS AssumeRole (cross-account writes)
+
+For sinks that must write to a bucket owned by a different AWS account, assume
an IAM role and pass the temporary session credentials through
`hadoop_s3_properties`. The temporary credentials are issued by
`sts:AssumeRole` and used via `TemporaryAWSCredentialsProvider`.
+
+```hocon
+sink {
+ S3File {
+ path = "/cross-account/prefix"
+ bucket = "s3a://target-bucket"
+ fs.s3a.endpoint = "s3.cn-north-1.amazonaws.com.cn"
+ fs.s3a.aws.credentials.provider =
"org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider"
+ hadoop_s3_properties = {
+ "fs.s3a.access.key" = "<assumed-role-access-key>"
+ "fs.s3a.secret.key" = "<assumed-role-secret-key>"
+ "fs.s3a.session.token" = "<assumed-role-session-token>"
+ }
+ file_format_type = "parquet"
+ schema_evolution_enabled = true
+ }
+}
+```
+
+For AWS SSO/Profile-based roles, swap the provider class (for example
`com.amazonaws.auth.profile.ProfileCredentialsProvider` with `fs.s3a.profile`
and `fs.s3a.credentialsFile`) and pass the provider-specific keys under
`hadoop_s3_properties`. See the [Hadoop
AWS](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html)
documentation for the full set of supported `fs.s3a.*` keys.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/source/CosFile.md
b/docs/en/connectors/source/CosFile.md
index 685e9ccf84..857ad70902 100644
--- a/docs/en/connectors/source/CosFile.md
+++ b/docs/en/connectors/source/CosFile.md
@@ -229,15 +229,15 @@ The bucket address of COS file system, for example:
`cosn://seatunnel-test`
### secret_id [string]
-The secret id of Cos file system.
+The secret id of Cos file system. Issue this from the [Tencent Cloud CAM
console](https://console.cloud.tencent.com/cam/capi) (SecretId field). For
production jobs, prefer a CAM role with a scoped policy (e.g.
`QcloudCOSReadOnlyAccess`) and use role-based temporary keys via STS instead of
long-lived keys.
### secret_key [string]
-The secret key of Cos file system.
+The secret key of Cos file system. The SecretKey that pairs with `secret_id`.
See `secret_id` for the recommended STS-based replacement.
### region [string]
-The region of cos file system.
+The region of cos file system. Use a region that matches your bucket's actual
location (for example `ap-guangzhou`, `ap-shanghai`, `ap-chengdu`). Bucket
access from a different region still works but incurs cross-region transfer
cost and latency.
### read_columns [list]
diff --git a/docs/en/connectors/source/FtpFile.md
b/docs/en/connectors/source/FtpFile.md
index e84c2149be..c98c44119a 100644
--- a/docs/en/connectors/source/FtpFile.md
+++ b/docs/en/connectors/source/FtpFile.md
@@ -868,6 +868,31 @@ sink {
}
```
+### Reading via SFTP (SSH File Transfer)
+
+`FtpFile` reads from FTP and SFTP servers through the same Hadoop FileSystem
URI scheme; switch to `sftp://` to use SSH instead of plain FTP. SFTP requires
an SSH key (or a password) for authentication, and the host key must be trusted
by the running JVM (either via `~/.ssh/known_hosts` or a custom `known_hosts`
file passed through `ftp_properties`).
+
+```hocon
+source {
+ FtpFile {
+ fs.defaultFS = "sftp://sftp.example.example.com:22";
+ path = "/upload/landing/"
+ user = "seatunnel"
+ file_format_type = "csv"
+ delimiter = ","
+ ftp_properties = {
+ "fs.sftp.user." = "seatunnel"
+ "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
+ "fs.sftp.host" = "sftp.example.example.com"
+ "fs.sftp.port" = "22"
+ "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
+ }
+ }
+}
+```
+
+If the SFTP server uses a self-signed host key, add it to `known_hosts` ahead
of time — otherwise the first read throws a `SftpException` complaining about
host verification. The connector does not cache or refresh `known_hosts`
itself; updating the file and restarting the job is enough.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/source/HdfsFile.md
b/docs/en/connectors/source/HdfsFile.md
index 04ed4bc55e..3b2609ca81 100644
--- a/docs/en/connectors/source/HdfsFile.md
+++ b/docs/en/connectors/source/HdfsFile.md
@@ -678,6 +678,23 @@ sink {
```
+### Reading from an HA HDFS Cluster (Nameservice)
+
+When the HDFS namenode is deployed in HA mode (multiple namenodes behind a
single nameservice), point `fs.defaultFS` at the nameservice URI (not an
individual namenode) so the client can fail over automatically. The nameservice
ID must match the `dfs.nameservices` value in `hdfs-site.xml`.
+
+```hocon
+source {
+ HdfsFile {
+ fs.defaultFS = "hdfs://mycluster"
+ path = "/data/orders/dt=2026-08-11"
+ file_format_type = "parquet"
+ hdfs_site_path = "/etc/hadoop/conf/hdfs-site.xml"
+ }
+}
+```
+
+If the cluster is configured with ViewFS (federated HDFS), use a
`viewfs://<nameservice-path>` URI for `fs.defaultFS` instead — the connector
passes the URI straight to the Hadoop FileSystem client. The `hdfs_site_path`
option lets you load an external `hdfs-site.xml` (for example from
`/etc/hadoop/conf/`) so the cluster's HA / federation settings are picked up
without restating them in the job file.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/source/ObsFile.md
b/docs/en/connectors/source/ObsFile.md
index 1226fc55e8..60aba06bf0 100644
--- a/docs/en/connectors/source/ObsFile.md
+++ b/docs/en/connectors/source/ObsFile.md
@@ -399,6 +399,28 @@ schema {
```
+### Reading with Temporary Security Credentials (OBS STS)
+
+For production jobs that need scoped, short-lived access, generate temporary
AK/SK via [OBS
STS](https://support.huaweicloud.com/intl/en-us/api-obs/obs_04_0081.html) and
pass them through `hadoop_obs_properties`. The temporary credentials can carry
a fine-grained custom policy that limits access to a specific bucket prefix.
+
+```hocon
+source {
+ ObsFile {
+ path = "/staging/prefix"
+ bucket = "obs://target-bucket"
+ endpoint = "obs.ap-southeast-1.myhuaweicloud.com"
+ hadoop_obs_properties = {
+ "fs.obs.access.key" = "<temp-access-key>"
+ "fs.obs.secret.key" = "<temp-secret-key>"
+ "fs.obs.session.token" = "<temp-security-token>"
+ }
+ file_format_type = "parquet"
+ }
+}
+```
+
+The provider jar must be on the runtime classpath of every node
(`${SEATUNNEL_HOME}/lib`). Avoid long-lived AK/SK in job files; prefer
STS-issued temporary credentials or an ECS Agency when running inside Huawei
Cloud.
+
## Changelog
<ChangeLog />
diff --git a/docs/en/connectors/source/S3File.md
b/docs/en/connectors/source/S3File.md
index 36f96c2448..de51d8b9bd 100644
--- a/docs/en/connectors/source/S3File.md
+++ b/docs/en/connectors/source/S3File.md
@@ -565,6 +565,29 @@ sink {
}
```
+### Reading with STS AssumeRole (cross-account or federated access)
+
+For jobs that must read from a bucket owned by a different AWS account, or
that assume an IAM role via STS, pass the temporary session credentials through
`hadoop_s3_properties` together with a custom credentials provider. The
temporary credentials (issued by `sts:AssumeRole`) are supplied as raw Hadoop
S3A keys.
+
+```hocon
+source {
+ S3File {
+ path = "/cross-account/prefix"
+ bucket = "s3a://target-bucket"
+ fs.s3a.endpoint = "s3.cn-north-1.amazonaws.com.cn"
+ fs.s3a.aws.credentials.provider =
"org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider"
+ hadoop_s3_properties = {
+ "fs.s3a.access.key" = "<assumed-role-access-key>"
+ "fs.s3a.secret.key" = "<assumed-role-secret-key>"
+ "fs.s3a.session.token" = "<assumed-role-session-token>"
+ }
+ file_format_type = "parquet"
+ }
+}
+```
+
+The same pattern works for AWS SSO/Profile providers by swapping the provider
class (for example `com.amazonaws.auth.profile.ProfileCredentialsProvider` with
`fs.s3a.profile` and `fs.s3a.credentialsFile` keys) — pass those
provider-specific keys under `hadoop_s3_properties`. See the [Hadoop
AWS](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html)
documentation for the full set of supported `fs.s3a.*` keys.
+
## Changelog
<ChangeLog />
diff --git a/docs/zh/connectors/sink/FtpFile.md
b/docs/zh/connectors/sink/FtpFile.md
index 9764daf3d6..520d6ea804 100644
--- a/docs/zh/connectors/sink/FtpFile.md
+++ b/docs/zh/connectors/sink/FtpFile.md
@@ -408,6 +408,28 @@ FtpFile {
```
+### 通过 SFTP 写入
+
+`FtpFile` Sink 同时支持 `ftp://` 和 `sftp://` URI。认证方式与 source 一致：SSH 密钥或密码外加
`known_hosts` 文件——连接器不会自动信任未知 host。
+
+```hocon
+sink {
+ FtpFile {
+ fs.defaultFS = "sftp://sftp.example.example.com:22";
+ path = "/upload/landing/"
+ user = "seatunnel"
+ file_format_type = "parquet"
+ ftp_properties = {
+ "fs.sftp.user." = "seatunnel"
+ "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
+ "fs.sftp.host" = "sftp.example.example.com"
+ "fs.sftp.port" = "22"
+ "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
+ }
+ }
+}
+```
+
## 变更日志
diff --git a/docs/zh/connectors/sink/HdfsFile.md
b/docs/zh/connectors/sink/HdfsFile.md
index becfc8eae7..f3ace17cb6 100644
--- a/docs/zh/connectors/sink/HdfsFile.md
+++ b/docs/zh/connectors/sink/HdfsFile.md
@@ -320,6 +320,24 @@ HdfsFile {
</configuration>
```
+### 写入启用 Kerberos 的 HA HDFS 集群
+
+向启用 Kerberos 的 HA HDFS 集群写入时，除了 nameservice URI，还需要提供 Kerberos
principal/keytab。连接器复用 Hadoop 工具链的同一套身份认证，因此 principal 必须拥有目标目录的写权限。
+
+```hocon
+sink {
+ HdfsFile {
+ fs.defaultFS = "hdfs://mycluster"
+ path = "/data/landing/events"
+ file_format_type = "parquet"
+ hdfs_site_path = "/etc/hadoop/conf/hdfs-site.xml"
+ kerberos_principal = "[email protected]"
+ krb5_path = "/etc/krb5.conf"
+ }
+}
+```
+
+`kerberos_principal` 与 `krb5_path` 仅被转发给 Hadoop FileSystem 客户端，连接器自身不会执行
`kinit`；所以 keytab 必须已经能被每个 worker 节点发现（通常通过 `KRB5CCNAME` 或定时 `kinit`），或经由标准的
Hadoop 认证工具注入到同一 JVM 中。遇到集群级认证问题时，请先在 worker 日志里查看 `LoginException` /
`KrbException`——这些通常是凭据问题，而不是连接器本身的 bug。
## 变更日志
diff --git a/docs/zh/connectors/sink/S3File.md
b/docs/zh/connectors/sink/S3File.md
index 7536854aa1..6cf67e2091 100644
--- a/docs/zh/connectors/sink/S3File.md
+++ b/docs/zh/connectors/sink/S3File.md
@@ -548,6 +548,30 @@ S3File {
生产作业中不建议把长期有效的密钥直接写入任务文件。优先使用 IAM 类认证方式，例如 `fs.s3a.aws.credentials.provider =
com.amazonaws.auth.InstanceProfileCredentialsProvider`，或通过 SeaTunnel 变量替换注入
`access_key` 和 `secret_key`。
+### 使用 STS AssumeRole 写入（跨账号写入）
+
+向另一个 AWS 账号拥有的 bucket 写入时，先通过 `sts:AssumeRole` 拿到临时会话凭证，再通过
`hadoop_s3_properties` 与 `TemporaryAWSCredentialsProvider` 配合使用。
+
+```hocon
+sink {
+ S3File {
+ path = "/cross-account/prefix"
+ bucket = "s3a://target-bucket"
+ fs.s3a.endpoint = "s3.cn-north-1.amazonaws.com.cn"
+ fs.s3a.aws.credentials.provider =
"org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider"
+ hadoop_s3_properties = {
+ "fs.s3a.access.key" = "<assumed-role-access-key>"
+ "fs.s3a.secret.key" = "<assumed-role-secret-key>"
+ "fs.s3a.session.token" = "<assumed-role-session-token>"
+ }
+ file_format_type = "parquet"
+ schema_evolution_enabled = true
+ }
+}
+```
+
+对于 AWS SSO / Profile 角色，把 provider 类换成
`com.amazonaws.auth.profile.ProfileCredentialsProvider`，并把
`fs.s3a.profile`、`fs.s3a.credentialsFile` 等 provider 特定键放在
`hadoop_s3_properties` 里。完整的 `fs.s3a.*` 键集合参见 [Hadoop
AWS](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html)
文档。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/CosFile.md
b/docs/zh/connectors/source/CosFile.md
index 1c5e95afaa..68d5faf90c 100644
--- a/docs/zh/connectors/source/CosFile.md
+++ b/docs/zh/connectors/source/CosFile.md
@@ -229,15 +229,15 @@ Cos文件系统的bucket地址，例如: `cos://tyrantlucifer-image-bed`
### secret_id [string]
-Cos文件系统的秘密id。
+Cos 文件系统的 SecretId。在 [腾讯云 CAM 控制台](https://console.cloud.tencent.com/cam/capi)
创建。生产环境建议为作业分配一个绑定细粒度策略（如 `QcloudCOSReadOnlyAccess`）的 CAM 角色，并通过 STS
颁发临时密钥，避免长期密钥出现在作业配置里。
### secret_key [string]
-Cos文件系统的密钥。
+Cos 文件系统的 SecretKey，与 `secret_id` 成对使用。生产建议参考 `secret_id`，改用 STS 临时密钥。
### region [string]
-cos文件系统的region。
+Cos 文件系统所在 region。请填入与 bucket 实际所在地域一致的 region（如
`ap-guangzhou`、`ap-shanghai`、`ap-chengdu`）。跨 region 访问虽然可行，但会产生跨地域传输费用和时延。
### read_columns [list]
diff --git a/docs/zh/connectors/source/FtpFile.md
b/docs/zh/connectors/source/FtpFile.md
index 7fbfe85c67..306e786231 100644
--- a/docs/zh/connectors/source/FtpFile.md
+++ b/docs/zh/connectors/source/FtpFile.md
@@ -839,6 +839,31 @@ sink {
}
```
+### 通过 SFTP 读取（SSH 文件传输）
+
+`FtpFile` 通过统一的 Hadoop FileSystem URI 同时支持 FTP 和 SFTP；将 URI 协议改为 `sftp://`
即切换到 SSH 通道。SFTP 需要 SSH 密钥（或密码）认证，且 host key 必须被运行中的 JVM 信任（通过
`~/.ssh/known_hosts` 或通过 `ftp_properties` 显式指定的 `known_hosts` 文件）。
+
+```hocon
+source {
+ FtpFile {
+ fs.defaultFS = "sftp://sftp.example.example.com:22";
+ path = "/upload/landing/"
+ user = "seatunnel"
+ file_format_type = "csv"
+ delimiter = ","
+ ftp_properties = {
+ "fs.sftp.user." = "seatunnel"
+ "fs.sftp.keyfile" = "/etc/seatunnel/id_rsa"
+ "fs.sftp.host" = "sftp.example.example.com"
+ "fs.sftp.port" = "22"
+ "fs.sftp.knownHosts" = "/etc/seatunnel/known_hosts"
+ }
+ }
+}
+```
+
+如果 SFTP 服务器使用的是自签 host key，请提前把它加进 `known_hosts`——否则第一次读取会抛出 `SftpException`
并提示 host 校验未通过。连接器本身不缓存或刷新 `known_hosts`，更新文件后重启作业即可生效。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/HdfsFile.md
b/docs/zh/connectors/source/HdfsFile.md
index 4b3fa99498..5f155c4495 100644
--- a/docs/zh/connectors/source/HdfsFile.md
+++ b/docs/zh/connectors/source/HdfsFile.md
@@ -694,6 +694,23 @@ sink {
```
+### 从 HA HDFS 集群（Nameservice）读取
+
+当 HDFS namenode 以 HA 模式部署（多个 namenode 共享一个 nameservice）时，把 `fs.defaultFS` 指向
nameservice URI（而不是单个 namenode），以便客户端在 namenode 故障时自动切换。nameservice ID 必须与
`hdfs-site.xml` 中的 `dfs.nameservices` 一致。
+
+```hocon
+source {
+ HdfsFile {
+ fs.defaultFS = "hdfs://mycluster"
+ path = "/data/orders/dt=2026-08-11"
+ file_format_type = "parquet"
+ hdfs_site_path = "/etc/hadoop/conf/hdfs-site.xml"
+ }
+}
+```
+
+如果集群使用 ViewFS（联邦 HDFS），则 `fs.defaultFS` 应使用 `viewfs://<nameservice-path>`
URI——连接器会把 URI 直接交给 Hadoop FileSystem 客户端处理。`hdfs_site_path` 选项用于加载外部
`hdfs-site.xml`（如 `/etc/hadoop/conf/`），这样集群的 HA / 联邦配置无需在作业里重复声明即可生效。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/ObsFile.md
b/docs/zh/connectors/source/ObsFile.md
index b3af3fe993..fbfeaaaf57 100644
--- a/docs/zh/connectors/source/ObsFile.md
+++ b/docs/zh/connectors/source/ObsFile.md
@@ -141,6 +141,28 @@ PDF 特有的解析行为如下：
- 读取具有不断演化的 schema 的文件，且希望 schema 推断使用最新的文件
- 需要按时间顺序处理文件
+### 使用 OBS STS 临时安全凭证读取
+
+生产环境建议通过 [OBS
STS](https://support.huaweicloud.com/intl/zh-cn/api-obs/obs_04_0081.html) 颁发临时
AK/SK，并配合细粒度自定义策略限制只能访问指定 bucket 前缀，再通过 `hadoop_obs_properties` 传给连接器。
+
+```hocon
+source {
+ ObsFile {
+ path = "/staging/prefix"
+ bucket = "obs://target-bucket"
+ endpoint = "obs.ap-southeast-1.myhuaweicloud.com"
+ hadoop_obs_properties = {
+ "fs.obs.access.key" = "<临时-access-key>"
+ "fs.obs.secret.key" = "<临时-secret-key>"
+ "fs.obs.session.token" = "<临时-security-token>"
+ }
+ file_format_type = "parquet"
+ }
+}
+```
+
+provider 的 jar 必须放在每个运行节点的
classpath（`${SEATUNNEL_HOME}/lib`）上。生产环境应避免在作业配置中硬编码长期 AK/SK；运行在华为云内时推荐使用 ECS
委托（Agency）或 STS 临时凭证。
+
## 变更日志
<ChangeLog />
diff --git a/docs/zh/connectors/source/S3File.md
b/docs/zh/connectors/source/S3File.md
index a3f392dbeb..aba0625d58 100644
--- a/docs/zh/connectors/source/S3File.md
+++ b/docs/zh/connectors/source/S3File.md
@@ -564,6 +564,29 @@ sink {
}
```
+### 使用 STS AssumeRole 读取（跨账号或联邦身份）
+
+如果作业需要读取另一个 AWS 账号拥有的 bucket，或者通过 STS 切换 IAM 角色，可以把 AssumeRole 颁发的临时会话凭证通过
`hadoop_s3_properties` 传给连接器，并配合自定义凭据 provider 使用。
+
+```hocon
+source {
+ S3File {
+ path = "/cross-account/prefix"
+ bucket = "s3a://target-bucket"
+ fs.s3a.endpoint = "s3.cn-north-1.amazonaws.com.cn"
+ fs.s3a.aws.credentials.provider =
"org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider"
+ hadoop_s3_properties = {
+ "fs.s3a.access.key" = "<assumed-role-access-key>"
+ "fs.s3a.secret.key" = "<assumed-role-secret-key>"
+ "fs.s3a.session.token" = "<assumed-role-session-token>"
+ }
+ file_format_type = "parquet"
+ }
+}
+```
+
+对于 AWS SSO / Profile 这类 provider，只需要把 provider 类换成
`com.amazonaws.auth.profile.ProfileCredentialsProvider`，并在
`hadoop_s3_properties` 里配置 `fs.s3a.profile`、`fs.s3a.credentialsFile` 等 provider
特定键。完整的 `fs.s3a.*` 键集合参见 [Hadoop
AWS](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html)
文档。
+
## 变更日志
<ChangeLog />
