在 AWS CodeBuild 中集成 Earthly:从 buildspec 到构建加速的完整指南

原创2026-09-22 11:11:481,359 阅读
文章标签:CI/CDDevOps构建工具

在 AWS CodeBuild 中集成 Earthly:从 buildspec 到构建加速的完整指南

AWS CodeBuild 是 AWS 提供的一项托管式持续集成服务,而 Earthly 是一个语法类似 Dockerfile 与 Makefile 结合的构建框架,专注于提供快速、可重复的构建能力。本文以仓库中的 AWS CodeBuild 集成文档 为核心,完整讲解如何在 AWS CodeBuild 项目中安装 Earthly、完成 Docker 认证,并通过 earthly --ci --push +build 一键构建目标,同时结合仓库源码与文档深入解析 --ci、--push 等关键参数的真实行为,帮助你获得一套可直接复制运行、生产可用的 CodeBuild + Earthly 流水线。

为什么在 CodeBuild 中使用 Earthly

CodeBuild 的标准构建模型是基于 buildspec.yml 定义的一组脚本命令;而 Earthly 将构建流程声明式地写进 Earthfile 中,天然支持目标(target)依赖、缓存复用、并行执行与跨平台构建。两者结合后,CodeBuild 只负责触发与调度,真正的构建逻辑全部收敛到 Earthly 中,既保留了 CodeBuild 托管的便利性,又获得了 Earthly 带来的可重复构建能力。

从仓库的 CI 集成总览 可以看到,在任何 CI 环境中接入 Earthly 都遵循三个固定步骤:

  1. 安装依赖(docker 与 git);
  2. 安装 Earthly 本身;
  3. 配置认证与 CI 专属参数。

AWS CodeBuild 的接入方式完全遵循这一套路,因此下面的内容会围绕这三步逐一展开。

前置条件:依赖与 Privileged 权限

在创建 CodeBuild 项目之前,需要先确认两件事。

1. 依赖:docker 与 git

Earthly 有两个软件依赖:docker 和 git,它不会替你安装它们(参见 CI 集成总览):

  • docker:用于获取容器化环境信息、管理 earthly-buildkitd 守护进程,以及在构建完成后把镜像保存到本机;
  • git:用于拉取远程目标,并在构建期间为 Earthly 提供仓库元数据。

CodeBuild 的 Ubuntu 标准镜像(Standard Image)中通常已经预装了这两个工具,因此多数情况下无需额外处理。

2. 启用 Privileged 标志(关键!)

原文档特别强调:

在创建 CodeBuild 项目时,务必在项目的 Environment(环境)配置中启用 Privileged 标志,否则 Earthly 无法构建 Docker 镜像。

这一要求并非空穴来风。从仓库文档可知,Earthly 的 earthly-buildkitd 守护进程必须以 --privileged 模式运行(参见 CI 集成总览 与 构建 Earthly CI 镜像)。在 CodeBuild 控制台的 "Environment" 区域勾选 "Enable this flag if you want to build Docker images or want your builds to get elevated privileges" 即可。

如果不启用该标志,构建会在启动 BuildKit 或执行 RUN --privileged 相关步骤时失败。

完整的 buildspec.yml 示例

以下是原文档给出的完整示例。它构建的是当前项目 Earthfile 中的 +build 目标:

# ./buildspec.yml
version: 0.2

phases:
  install:
    commands:
      - wget https://github.com/earthly/earthly/releases/download/v0.8.13/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly
  pre_build:
    commands:
      - echo Logging into Docker
      - docker login --username "$DOCKERHUB_USERNAME" --password "$DOCKERHUB_TOKEN"
  build:
    commands:
      - earthly --ci --push +build

下面逐段拆解这个文件,说明每个阶段做了什么、为什么这样做,以及可以如何扩展。

install 阶段:安装 Earthly 二进制

wget https://github.com/earthly/earthly/releases/download/v0.8.13/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly

这一步把 Earthly 的 Linux amd64 二进制下载到 /usr/local/bin/earthly 并赋予执行权限。

关于版本,有两个值得注意的实践要点:

  • 固定版本(pinning):原文档中固定到了 v0.8.13。仓库的 CI 集成总览 明确建议将 Earthly 固定在具体版本上,以避免未来版本行为变化导致流水线意外失效;
  • 安装时机的选择:建议把安装 Earthly 放在构建主机的初始化配置中(例如 CodeBuild 的安装命令或自建镜像里),而不是作为每次构建的一部分。这样既省去每次构建都下载二进制的开销,又能提高构建稳定性(同一来源参见 CI 集成总览)。

如果不想在每次构建中都下载,也可以选择 earthly/earthly 官方镜像方案,相关细节见 构建 Earthly CI 镜像。

pre_build 阶段:登录 Docker

echo Logging into Docker
docker login --username "$DOCKERHUB_USERNAME" --password "$DOCKERHUB_TOKEN"

docker login 是为了让构建可以拉取私有基础镜像(通过 FROM)以及推送镜像(通过 SAVE IMAGE --push)。

在仓库的 认证指南 中可以看到,Earthly 的 Docker 认证是"开箱即用"的——它复用系统上 Docker 的凭据存储,因此只需要在运行 Earthly 命令之前执行 docker login 即可,Earthly 会自动继承这些凭据。

在 CodeBuild 中,DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN 通常通过 CodeBuild 项目配置中的环境变量注入(建议在 AWS Systems Manager Parameter Store 或 Secrets Manager 中存放真实值,而非硬编码到 buildspec 中)。

提示:如果使用 AWS ECR 等私有镜像仓库,可以改用 ECR 的凭据助手或 aws ecr get-login-password 方式登录,Earthly 同样可以复用这些凭据(参见 认证指南)。

build 阶段:执行构建

earthly --ci --push +build

这是整个流水线的核心命令,由三部分组成:

+build:目标引用。+<target-name> 引用当前目录下 Earthfile 中的目标(参见 Earthly 命令参考)。示例假设项目根目录已存在包含 +build 目标的 Earthfile,例如:

VERSION 0.8
FROM golang:1.19-alpine3.15

deps:
    COPY go.mod go.sum .
    RUN go mod download

build:
    FROM +deps
    COPY . .
    RUN go build -o /bin/app
    SAVE ARTIFACT /bin/app AS LOCAL ./app

--ci:CI 模式开关。根据 Earthly 命令参考,在目标模式下 --ci 是以下两个选项的别名:

--no-output --strict
  • --no-output:不输出任何镜像或工件(避免在 CI 中产生无用的本地输出);
  • --strict:禁止使用可能导致构建不可重复的特性(例如未声明的全局参数等)。

在工件模式(--artifact)和镜像模式(--image)下,--ci 等价于 --strict。如果你的 CI 流水线确实需要输出工件或镜像,可以使用 --output 选项在 --ci 模式下显式允许输出(参见 Earthly 命令参考)。

--push:推送开关。仅当构建成功后才执行推送,包括推送声明了 --push 的 Docker 镜像以及执行 RUN --push 命令(参见 Earthly 命令参考)。这是开发工作流与 CI 工作流的关键区别:本地构建默认不推送,而 CI 中通常需要该标志来真正发布产物。

原文档在 CI 集成总览 中也强调,--ci 与 --push 是 CI 场景下强烈推荐启用的选项。

在 CodeBuild 控制台中的配置要点

将上述 buildspec.yml 放入仓库根目录后,创建 CodeBuild 项目时请重点检查以下配置:

配置项 推荐值 / 操作
Environment image 选择托管的标准 Ubuntu 镜像(或使用自建的含 Earthly 镜像)
Privileged 必须勾选,否则无法构建 Docker 镜像
Service role 赋予项目拉取代码与访问 ECR 等资源的权限
Environment variables 注入 DOCKERHUB_USERNAME、DOCKERHUB_TOKEN 等敏感变量
Buildspec 默认使用根目录 buildspec.yml,或通过 buildspec 字段指定自定义路径

其中 Privileged 标志是最容易遗漏的一环,请务必确认。

CI 场景下的进阶配置

原文档在最后引导读者查看完整的 CI 集成指南。结合这份总览,CodeBuild 场景下还有几个值得落地的进阶配置。

CI 常用环境变量

变量 用途
NO_COLOR / FORCE_COLOR 强制关闭/开启 ANSI 颜色输出。当 earthly 误判终端存在时,可设为 1 来修正日志格式
CNI_MTU 当外部 MTU 与 Earthly 内部 CNI 网络的 MTU 不一致导致无法访问外网时,手动指定内部网络 MTU
EARTHLY_BUILDKIT_HOST 指定外部 BuildKit 实例地址,跳过 Earthly 自管理的 earthly-buildkitd

这些变量均可在 CodeBuild 的环境变量中直接配置(表格来源:CI 集成总览)。

大构建的镜像拉取优化:Pull-through Cache

大型构建会对某些镜像产生大量 docker pull 请求。可以在 CodeBuild 中配置并使用 pull-through cache 来规避拉取瓶颈,减少构建时间与网络开销。

连接远程 BuildKit / Satellite

如果不想在每个 CodeBuild 实例上都维护一个本地 earthly-buildkitd,可以改用远程 BuildKit 实例。此时需要设置 EARTHLY_BUILDKIT_HOST 指向远程地址,相关的部署与安全注意事项参见 远程 BuildKit 指南。结合官方镜像使用时,还可以通过 NO_BUILDKIT=1 环境变量禁用镜像内嵌的 BuildKit 守护进程(参见 构建 Earthly CI 镜像)。

跨平台构建

如果需要跨平台构建,需要先安装 binfmt_misc 支持条目:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

该命令会安装所需条目与 qemu-user-static 二进制,属于内核级变更,每台物理机只需执行一次(参见 CI 集成总览)。

密钥注入

需要向构建传递密钥时,使用 --secret 选项(earthly --secret <secret-id>=<value> +build),在 Earthfile 中通过 RUN --secret 引用(参见 Earthly 命令参考)。

常见问题与排查

  • 构建报 "cannot connect to the Docker daemon":确认 CodeBuild 项目已启用 Privileged 标志,且 docker 服务正常。
  • 拉取私有镜像失败:确认 pre_build 阶段的 docker login 已执行成功,且环境变量 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN 已正确注入。
  • 网络异常 / 无法访问外网:检查是否为 CNI MTU 问题,尝试设置 CNI_MTU 环境变量。
  • 需要更详细的日志:在命令中追加 --verbose 获取调试信息;BuildKit 的低层日志可以通过 docker logs earthly-buildkitd 查看(参见 认证指南)。
  • 构建不可重复的警告:--ci 已自动开启 --strict,若仍有告警,检查 Earthfile 中是否存在未声明的全局参数等违规用法。

总结

将 Earthly 接入 AWS CodeBuild 的完整路径是:在 CodeBuild 项目启用 Privileged 标志 → 在 install 阶段安装固定版本的 Earthly 二进制 → 在 pre_build 阶段通过 docker login 完成镜像仓库认证 → 在 build 阶段执行 earthly --ci --push +build。其中 --ci(等价于 --no-output --strict)保证构建的可重复性,--push 确保构建成功后才会推送产物。

对更完整的 CI 集成方法论(依赖安装、镜像方案、网络与安全、各 CI 系统示例),可以继续阅读仓库中的 CI 集成指南,以及 Earthly 命令参考、认证指南、Earthly 配置参考 等文档获取更多细节。

登录后查看全文
earthly