envd

简体中文

English

简体中文

English

Appearance

远程缓存 ​

你可以使用远程缓存来加速构建过程。envd 构建缓存[1]可以被上传到镜像仓库、目的目录或其他地方。目前支持以下五种：

  • registry: 分别推送镜像和缓存到镜像仓库。
  • inline: 把缓存内嵌到镜像中，然后一起推送到镜像仓库。
  • local: 从本地路径导入/导出
  • gha（试验中 🧪）：从 GitHub Actions cache 导入/导出
  • s3（试验中 🧪）：从 S3 导入/导出

大多数情况下推荐使用 registry。

如何使用 ​

可以使用 --export-cache 和 --import-cache 参数来从缓存中导入和导出。

指定 --export-cache 的情况下，构建缓存会被导出到指定位置。同理，指定 --import-cache 的时候会从该位置导入缓存。

bash
envd build ... \
  --output type=image,name=docker.io/username/image,push=true \
  --export-cache type=registry,ref=docker.io/username/cache-name \
  --import-cache type=registry,ref=docker.io/username/cache-name

你可以利用该机制大幅加速构建过程。

参考 ​

这个特性由 BuildKit 支持。

Registry（分别推送镜像和缓存） ​

envd build ... \
  --output type=image,name=docker.io/username/image,push=true \
  --export-cache type=registry,ref=docker.io/username/image \
  --import-cache type=registry,ref=docker.io/username/image

--export-cache 选项：

  • type=registry
  • mode=<min|max>: 指定导出缓存的模式（默认：min）
    • min: 仅导出最终镜像的 layers
    • max: 导出所有中间过程的 layers
  • ref=<ref>: 指定要保存到的仓库位置，例如 docker.io/user/image:tag
  • oci-mediatypes=<true|false>: 是否要在导出的 manifests 中使用 OCI mediatypes（从 BuildKit v0.8 开始默认为 true）
  • compression=<uncompressed|gzip|estargz|zstd>: 选择对新创建和缓存 layer 使用的压缩方式，默认使用 gzip。如果要使用 estargz 或者 zstd，则需要同时指定 oci-mediatypes=true
  • compression-level=<value>: 选择压缩粒度：gzip（1-9），estargz（0-9），zstd（0-22）
  • force-compression=true: 强制压缩所有 layers

--import-cache 选项：

  • type=registry
  • ref=<ref>: 指定要导入的仓库位置，例如 docker.io/user/image:tag

Inline（同时推送镜像和缓存） ​

bash
envd build ... \
  --output type=image,name=docker.io/username/image,push=true \
  --export-cache type=inline \
  --import-cache type=registry,ref=docker.io/username/image

只有指定 --import-cache type=registry,ref=... 的情况下才会导入 inline 缓存。

Inline 缓存会把元信息内嵌到镜像配置中，镜像 layers 中的信息和不使用缓存的镜像别无二致。

本地目录 ​

bash
envd build ... --export-cache type=local,dest=path/to/output-dir
envd build ... --import-cache type=local,src=path/to/input-dir

目录的布局符合 OCI 镜像标准 v1.0。

--export-cache 选项：

  • type=local
  • mode=<min|max>: 指定导出模式（默认为 min）
    • min: 仅导出最终镜像的 layers
    • max: 导出所有中间过程的 layers
  • dest=<path>: 导出缓存的目标路径
  • oci-mediatypes=<true|false>: 是否要在导出的 manifests 中使用 OCI mediatypes（从 BuildKit v0.8 开始默认为 true）
  • compression=<uncompressed|gzip|estargz|zstd>: 选择对新创建和缓存 layer 使用的压缩方式，默认使用 gzip。如果要使用 estargz 或者 zstd，则需要同时指定 oci-mediatypes=true
  • compression-level=<value>: 选择压缩粒度：gzip（1-9），estargz（0-9），zstd（0-22）
  • force-compression=true: 强制压缩所有 layers

--import-cache 选项：

  • type=local
  • src=<path>: 导入缓存的来源路径
  • digest=sha256:<sha256digest>: 显式指定要导入的 manifest digest 列表
  • tag=<tag>: 指定镜像的自定义 tag。index.json 中默认的"latest" tag 是 digest，不是 tag

GitHub Actions cache（试验中） ​

bash
envd build ... \
  --output type=image,name=docker.io/username/image,push=true \
  --export-cache type=gha \
  --import-cache type=gha

GitHub Actions cache 会把缓存元信息和 layers 保存到 GitHub 的 Cache 服务中。目前单个仓库有 10GB 的大小限制。当超出此限制的时候，GitHub 会保存最新的缓存，同时驱逐旧缓存直到总体大小低于 10GB。如果回收缓存发生得过于频繁，则会拖慢 CI 的整体速度。

类似 actions/cache，缓存是 按照分支区分 的，且默认分支和基础分支是对所有分支开放的。

针对 GitHub Actions Cache service API，需要以下验证信息：

  • url: Cache 服务 URL（默认 $ACTIONS_CACHE_URL）
  • token: Access token（默认 $ACTIONS_RUNTIME_TOKEN）

--export-cache 选项：

  • type=gha
  • mode=<min|max>: 指定导出模式（默认为 min）
    • min: 仅导出最终镜像的 layers
    • max: 导出所有中间过程的 layers
  • scope=<scope>: 选择所属的范围（默认为 buildkit）

--import-cache 选项：

  • type=gha
  • scope=<scope>: 选择所属的范围（默认为 buildkit）

S3 cache（试验中） ​

bash
envd build ... \
  --output type=image,name=docker.io/username/image,push=true \
  --export-cache type=s3,region=eu-west-1,bucket=my_bucket,name=my_image \
  --import-cache type=s3,region=eu-west-1,bucket=my_bucket,name=my_image

需要提供以下参数：

  • bucket: AWS S3 bucket（默认 $AWS_BUCKET）
  • region: AWS region（默认 $AWS_REGION）

保存位置：

  • blobs: s3://<bucket>/<prefix><blobs_prefix>/<sha256>，默认：s3://<bucket>/blobs/<sha256>
  • manifests: s3://<bucket>/<prefix><manifests_prefix>/<name>，默认：s3://<bucket>/manifests/<name>

S3 配置：

  • blobs_prefix: S3 上存储/读取 blobs 的全局前缀（默认：blobs/）
  • manifests_prefix: S3 上存储/读取 manifests 的全局前缀（默认：manifests/）
  • endpoint_url: 指定一个 S3 端点（默认：空）
  • use_path_style: 如果为 true，就在 URL 中设置 bucket 名称，否则放到 hostname 中（默认：false）

AWS 验证：

最简单的方式是使用 IAM 实例配置文件。

其他配置：

  • 任何 AWS Go SDK 支持的环境变量或配置文件。配置必须是可以被 buildkit 守护进程访问到的，而不是客户端可访问的。
  • 对于 Access Key ID 和 Secret Access Key，使用 access_key_id 和 secret_access_key。

--export-cache 配置：

  • type=s3
  • mode=<min|max>: 指定导出模式（默认为 min）
    • min: 仅导出最终镜像的 layers
    • max: 导出所有中间过程的 layers
  • prefix=<prefix>: S3 上存储/读取文件的全局前缀（默认：空）
  • name=<manifest>: 所使用的 manifest 的名称（默认 buildkit）
    • 可以同时设置多个 manifest 名称，并用 ; 分隔。标准用法是使用 Git SHA1 作为名称，并使用分支名称作为备选，并通过 2 个 import-cache 命令加载他们。

--import-cache 配置：

  • type=s3
  • prefix=<prefix>: S3 上存储/读取文件的全局前缀（默认：空）
  • blobs_prefix=<prefix>: S3 上存储/读取 blobs 的全局前缀（默认：blobs/）
  • manifests_prefix=<prefix>: S3 上存储/读取 manifests 的全局前缀（默认：manifests/）
  • name=<manifest>: 所使用的 manifest 的名称（默认 buildkit）

  1. 远程缓存特性依赖 buildkit ↩︎

Released under the Apache-2.0 License. Built with VitePress.

Copyright © 2022 TensorChord, Inc.