如何为 MinIO STS 配置 etcd 以集中存储临时凭证？

如果你的 MinIO 要对外签发临时凭证（Security Token Service，STS），MinIO 官方 STS 快速上手文档把 etcd 列为必备前置组件之一：在与 Keycloak、Casdoor 等身份提供方配好后，"any STS configuration will work including Client Grants, Web Identity or AD/LDAP"。本文按 docs/sts/etcd.md 的主路径，完成三件事：用 podman 拉起 etcd v3.3.9、通过环境变量把 MinIO 接入 etcd、再用 Client Grants 方式请求一次临时凭证，验证 STS 链路可用。

适用前提（来自文档）：

• Docker 18.03 或更高版本（文档命令实际使用 podman 容器工具）；
• 本机已配置好身份提供方（以 Keycloak 为例，步骤见 docs/sts/keycloak.md）；
• 本机可运行 Go，用于执行文档提供的 STS 示例客户端 docs/sts/client-grants.go。

启动 etcd 容器

docs/sts/etcd.md 给出的启动命令如下，etcd 使用 gcr.io/etcd-development/etcd 镜像：

副作用说明：该命令会先执行 rm -rf /tmp/etcd-data.tmp 删除 etcd 的本地数据目录（即清空 etcd 中已有数据），并执行 podman rmi 删除旧的 etcd 镜像。生产环境不要照搬这条"清理 + 启动"命令，应只保留 podman run 部分并确保数据目录持久化。

rm -rf /tmp/etcd-data.tmp && mkdir -p /tmp/etcd-data.tmp && \
  podman rmi gcr.io/etcd-development/etcd:v3.3.9 || true && \
  podman run \
  -p 2379:2379 \
  -p 2380:2380 \
  --mount type=bind,source=/tmp/etcd-data.tmp,destination=/etcd-data \
  --name etcd-gcr-v3.3.9 \
  gcr.io/etcd-development/etcd:v3.3.9 \
  /usr/local/bin/etcd \
  --name s1 \
  --data-dir /etcd-data \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://0.0.0.0:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://0.0.0.0:2380 \
  --initial-cluster s1=http://0.0.0.0:2380 \
  --initial-cluster-token tkn \
  --initial-cluster-state new

该命令暴露 2379（客户端端口）和 2380（peer 端口）。如果 etcd 需要 TLS，文档指向了 CoreOS etcd 的 op-guide/security 说明按 Client-to-server authentication with HTTPS client certificates 方式配置。

通过环境变量把 MinIO 接入 etcd

MinIO server 通过环境变量 MINIO_ETCD_ENDPOINTS 识别 etcd，该变量支持多个逗号分隔的 endpoint：

export MINIO_ETCD_ENDPOINTS=http://localhost:2379
minio server /data

如果 etcd 启用了 HTTPS 客户端证书认证，还需要补充两个环境变量：MINIO_ETCD_CLIENT_CERT 指向 etcd-client.crt，MINIO_ETCD_CLIENT_CERT_KEY 指向 etcd-client.key。

除环境变量外，docs/config/README.md 展示了用 mc admin config 管理同一组 etcd 配置项的方式，可用于查看当前可用参数（--env 形式显示对应环境变量名）：

# 查看 etcd 配置项
mc admin config set play/ etcd

# etcd  federate multiple clusters for IAM and Bucket DNS
# endpoints*      (csv)   comma separated list of etcd endpoints e.g. "http://localhost:2379"
# path_prefix      (path)  namespace prefix to isolate tenants e.g. "customer1/"
# coredns_path     (path)  shared bucket DNS records, default is "/skydns"
# client_cert      (path)  client cert for mTLS authentication
# client_cert_key  (path)  client cert key for mTLS authentication

mc admin config set play/ etcd --env

# MINIO_ETCD_ENDPOINTS*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
# MINIO_ETCD_PATH_PREFIX      (path)      namespace prefix to isolate tenants e.g. "customer1/"
# MINIO_ETCD_COREDNS_PATH     (path)      shared bucket DNS records, default is "/skydns"
# MINIO_ETCD_CLIENT_CERT      (path)      client cert for mTLS authentication
# MINIO_ETCD_CLIENT_CERT_KEY  (path)      client cert key for mTLS authentication

文档对 etcd 配置的用途描述是 "federate multiple clusters for IAM and Bucket DNS"；path_prefix 用作命名空间前缀隔离租户（如 customer1/），多租户共用同一个 etcd 时可用。

启动 MinIO 并接入身份提供方

配置好 etcd 后，按 docs/sts/README.md 的方式再叠加身份提供方配置。以 Keycloak + Client Grants 为例（MINIO_IDENTITY_OPENID_CONFIG_URL 与 MINIO_IDENTITY_OPENID_CLIENT_ID 是文档中的示例值，需替换为你在 docs/sts/keycloak.md 中创建 realm 和客户端后得到的实际值）：

export MINIO_ROOT_USER=minio
export MINIO_ROOT_PASSWORD=minio123
export MINIO_IDENTITY_OPENID_CONFIG_URL=http://localhost:8080/auth/realms/demo/.well-known/openid-configuration
export MINIO_IDENTITY_OPENID_CLIENT_ID="843351d4-1080-11ea-aa20-271ecba3924a"
export MINIO_ETCD_ENDPOINTS=http://localhost:2379
minio server /mnt/data

验证：请求一次 STS 临时凭证

docs/sts/etcd.md 给出的验证方式：用文档自带的示例客户端请求凭证。以下命令中的 -cid/-csec 是文档示例值，需替换为你的 Keycloak client ID 与 secret：

go run docs/sts/client-grants.go -cid PoEgXP6uVO45IsENRngDXj5Au5Ya -csec eKsw6z8CtOJVBtrOWvhRWL4TUCga

成功时终端打印凭证 JSON（以下为文档示例输出，字段名固定，具体值会不同）：

##### Credentials
{
 "accessKey": "IRBLVDGN5QGMDCMO1X8V",
 "secretKey": "KzS3UZKE7xqNdtRbKyfcWgxBS6P1G4kwZn4DXKuY",
 "expiration": "2018-08-21T15:49:38-07:00",
 "sessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJJUkJMVkRHTjVRR01EQ01PMVg4ViIs...
}

拿到 accessKey、secretKey、sessionToken 三项即说明 etcd 与 STS 链路配置完成。文档说明这些凭证可直接用于 MinIO API 操作，并且自动在 1 小时后过期（Client Grants 默认有效期 1 小时，可通过 API 的 DurationSeconds 参数在 900 秒到 365 天之间调整，详见 docs/sts/client-grants.md）。

限制与边界

• etcd 是 STS 的前置组件而非 STS 本身：没有配置好身份提供方（Keycloak/Casdoor/OpenID 等）时，即使 etcd 连通也无法签发凭证；
• 如果多个 MinIO 集群共用同一 etcd，用 MINIO_ETCD_PATH_PREFIX 做命名空间隔离；
• 配置 KMS 时，MinIO 支持把加密的 IAM 资产存入 etcd，加密方法见 docs/kms/IAM.md；
• etcd 端点若混用 http 与 https，启动会报错，文档要求所有 endpoint 协议一致。

完成上述步骤后，可按 docs/sts/README.md 继续用 WebIdentity API 或 MinIO Console 的 "Login with SSO" 入口做进一步验证。