Earthly 构建中的 AWS OIDC 认证配置与源码原理全解【免费下载链接】earthlySuper simple build framework with fast, repeatable builds and an instantly familiar syntax – like Dockerfile and Makefile had a baby.项目地址: https://gitcode.com/gh_mirrors/ea/earthlyEarthly 的 OpenID Connect (OIDC) 认证能力允许构建过程直接向第三方云厂商目前支持 AWS换取临时凭证从而在 CI 中无需存储任何长期密钥也无需本地环境凭据。本指南以 docs/cloud/oidc.md 为主线完整覆盖 AWS IAM OIDC Provider 与信任策略的配置步骤、RUN --aws --oidc的实战用法并结合当前仓库源码剖析 OIDC 规格解析、特性开关与凭证注入的底层实现帮助读者在 CI尤其是强制 MFA 的场景中安全地让构建访问 AWS 资源。为什么需要 OIDC摆脱 CI 中的密钥存储与 MFA 困境在常规的 CI 流水线中要让构建访问 AWS 资源通常有两种做法把 AWS Access Key 作为明文 secret 存进 CI 环境或者把本地环境的临时凭证带入构建。这两种方式都存在明显短板长期密钥一旦泄露影响范围大且难以追踪本地凭据与 CI 环境耦合可移植性差在强制启用 MFA多因素认证的团队中CI 无法像人一样完成交互式二次认证导致自动化受阻。OIDC 协议恰好解决了这一问题构建过程中由 Earthly Cloud 签发的 ID Token 直接向 AWS 换取短期临时凭证全程无需在 CI 或本地存储任何长期凭据。这也正是该特性被设计为面向 CI 场景的主要原因其完整说明位于 oidc.md。当前仓库中该能力只对 AWS 提供支持源码注释// we currently only support oidc for AWS明确此点其他云厂商的接入属于未来扩展方向。配置流程总览在 Earthfile 中使用 AWS OIDC 前需要完成两部分工作AWS 侧配置一次性在 AWS IAM 中注册 Earthly 作为 OIDC Provider并创建可被该 Provider 承担的 IAM RoleEarthfile 侧配置开启VERSION --run-with-aws --run-with-aws-oidc 0.8特性并在RUN命令中使用--aws --oidc标志。第一步在 AWS IAM 中注册 Earthly OIDC Provider参照 AWS IAM 官方文档创建 OIDC identity provider关键配置如下配置项值Provider URLhttps://api.earthly.devAudiencests.amazonaws.com即Earthly Cloud 的令牌签发端点https://api.earthly.dev作为受信任的身份源sts.amazonaws.com作为 audience受众表示这些令牌专门用于调用 AWS STS 服务。第二步创建或复用IAM Role 并配置信任策略创建一个新的 IAM Role或复用已有的 Role并注意两点限制权限Role 所附的策略决定了承担该角色后能执行哪些操作务必遵循最小权限原则限制谁可以承担通过信任策略trust policy精确指定允许承担的 Earthly 组织/项目成员。一个典型的信任策略示例如下{ Version: 2012-10-17, Statement: [ { Effect: Allow, Principal: { Federated: oidc-provider-name }, Action: sts:AssumeRoleWithWebIdentity, Condition: { StringEquals: { api.earthly.dev:aud: sts.amazonaws.com, api.earthly.dev:sub: earthly-org/earthly-project } } } ] }其中各占位符含义如下oidc-provider-name第一步中创建的 OIDC Provider 的 ARNearthly-org用户所属的 Earthly 组织在 Earthfile 的PROJECT指令或构建执行参数中指定下文详述earthly-project用户拥有读取权限的 Earthly 项目权限等级详见 managing-permissions.md同样在PROJECT指令或构建执行参数中指定。信任策略的灵活组合信任策略的Condition部分支持多种规则可以按需混合搭配精确控制团队内谁能承担该 Role允许整个组织所有成员访问使用StringLike 通配符Condition: { StringLike: { api.earthly.dev:sub: earthly-org/* } }仅允许指定用户访问基于与 Earthly 账号绑定的邮箱Condition: { StringEquals: { api.earthly.dev:email: user-email } }其中user-email是该用户 Earthly 账号对应的邮箱地址。第三步在 Earthfile 中使用 OIDC 访问 AWSOIDC 配置完成后即可在构建中访问 AWS 资源。原文档给出了一个列出 S3 对象的完整示例VERSION --run-with-aws --run-with-aws-oidc 0.8 PROJECT your-org/your-project aws: FROM amazon/aws-cli LET OIDCrole-arnarn:aws:iam::1234567890:role/your-oidc-role,session-namemy-session,regionus-east-1 RUN --aws --oidc$OIDC aws s3 ls逐行解读这个示例VERSION --run-with-aws --run-with-aws-oidc 0.8同时开启两个实验特性。--run-with-aws允许RUN命令使用 AWS 凭据features.go--run-with-aws-oidc则允许通过 OIDC Provider 获取 AWS 凭据features.goPROJECT your-org/your-project声明本次构建所属的 Earthly 组织与项目信任策略中的api.earthly.dev:sub即与此对应LET OIDC...以逗号分隔的键值对定义 OIDC 规格支持 ARG 展开RUN --aws --oidc$OIDC aws s3 ls执行命令前Earthly 通过 OIDC 换取临时 AWS 凭据并注入命令环境。--oidc规格详解四个可配置键RUN --aws --oidcoidc-spec中的oidc-spec是一串逗号分隔的键值对允许的键及含义见 earthfile.md键说明示例session-name出现在 AWS 日志中的会话名称。若多个RUN ... --oidc命令使用相同session-name它们将共享同一个临时令牌session-namemy-sessionrole-arn要为其获取凭据的 AWS Role 的 ARNrole-arnarn:aws:iam::123456789012:role/some-roleregion获取凭据时连接的 AWS 区域同时也是后续 AWS 命令默认使用的区域可在命令中覆盖不指定则使用 AWS 全局端点regionus-east-1session-duration临时凭据的有效时长默认取 AWS 最小值 15 分钟session-duration20m源码中的解析与校验规则oidc-spec的解析实现在 util/oidcutil/aws.go其行为可以作为上述表格的补充证据ParseAWSOIDCInfoaws.go首先把字符串解析为键值映射再通过mapstructure解码为AWSOIDCInfo结构体aws.gorole-arn与session-name是必填项缺失会直接报错requiredFields定义于 aws.go出现未知键同样报错key(s) [...] are invalidrole-arn必须是iam服务且资源以role/开头的合法 ARNaws.gosession-duration必须落在900 秒15 分钟到 43200 秒12 小时之间aws.go超出范围会提示duration must be between 900s and 43200s。底层实现从 Earthfile 到临时凭据注入RUN --aws --oidc的完整调用链横跨解释器与转换器两个模块理解它有助于排查问题。解释器阶段特性开关与前置校验earthfile2llb/interpreter.go的handleOIDC函数interpreter.go负责处理该标志依次执行若未开启--run-with-aws-oidc特性报错RUN --aws-oidc requires the --run-with-aws-oidc feature flag若未同时使用--aws报错RUN --oidc also requires the --aws RUN flag对oidc-spec执行 ARG 展开expandArgs因此LET OIDCrole-arn$ROLE_ARN,...这类引用变量的写法是合法的调用oidcutil.ParseAWSOIDCInfo完成上节所述的解析与校验。转换器阶段以 Secret 形式注入 AWS 凭据earthfile2llb/converter.go的awsSecrets函数converter.go负责将凭据接入构建当OIDCInfo非空时把 OIDC 信息编码进 secret ID 的查询参数secretprovider.SetURLValuesFunc为每个 AWS 凭据项secretprovider.AWSCredentials创建 LLB secret挂载到/run/secrets/name权限0444同时生成对应的环境变量赋值如AWS_ACCESS_KEY_ID$(cat /run/secrets/...)注入命令环境。也就是说OIDC 换取到的临时凭据最终是以构建内 secret 环境变量的形式提供给RUN命令的命令本身并不接触任何明文密钥。与其他命令的联动OIDC 信息不仅作用于普通RUN也会传递到WITH DOCKER场景解释器在handleOIDC后将其写入i.withDocker.OIDCInfointerpreter.go并在WITH DOCKER的四种执行路径本地 registry、本地 tar、远程 registry、远程 tar中一并传入参见 with_docker_run_local_reg.go、with_docker_run_local_tar.go、with_docker_run_reg.go、with_docker_run_tar.go即 Docker 容器内执行命令时同样可以拿到 AWS 临时凭据。集成测试仓库如何验证该能力仓库的 tests/oidc 目录提供了完整的集成测试可作为可复现的参考用例aws.earth以VERSION --run-with-aws --run-with-aws-oidc 0.8开头声明PROJECT other-serviceoidc-ci-test/my-project。oidc目标先用普通RUN验证环境变量中没有任何AWS_前缀变量基线为 0再通过RUN --aws --oidc$OIDC验证环境变量数量变为 4即临时凭据已注入oidc-with-docker目标在WITH DOCKER块内重复同样的断言验证容器内凭据注入同样生效test-aws.sh 驱动测试执行Earthfile 中test-aws-failure目标则验证了信任策略错误时的失败行为——使用一个不存在的 Role ARN断言输出中包含make sure the role ... has a valid trust policy configured in AWS的提示。注意事项与限制实验特性RUN --aws与RUN --oidc均为 experimental 状态必须通过VERSION --run-with-aws --run-with-aws-oidc 0.8显式开启对应源码 features.go 中标记为 unreleased 的特性开关仅支持 AWS当前实现只覆盖 AWS--oidc也只能与--aws组合使用单独使用会直接报错PROJECT 声明的重要性信任策略通过api.earthly.dev:suborg/project与api.earthly.dev:email进行条件匹配因此 Earthfile 中的PROJECT指令必须与实际组织/项目一致否则 STS 换证会失败凭据为短期令牌默认有效期 15 分钟可通过session-duration延长至最多 12 小时令牌过期后需要重新换取最小权限原则Role 的权限策略与信任策略应尽量收紧仅授予构建实际需要的 AWS 操作。小结Earthly 的 AWS OIDC 集成让构建可以无密钥地访问云资源AWS 侧注册 Provider、配置信任策略Earthfile 侧开启特性并声明PROJECT再以RUN --aws --oidc换取短期临时凭据。从 oidc.md 的配置指南到 oidcutil/aws.go 的严格校验再到 converter.go 的 secret 注入整条链路在仓库中均有清晰的实现与测试佐证适合作为 CI 安全访问 AWS 的落地模板。【免费下载链接】earthlySuper simple build framework with fast, repeatable builds and an instantly familiar syntax – like Dockerfile and Makefile had a baby.项目地址: https://gitcode.com/gh_mirrors/ea/earthly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考