参加你附近的 ,了解 VS Code 中的 AI 辅助开发。

自定义开发容器特性

2022年9月15日,由 Brigit Murtaugh (@BrigitMurtaugh) 发表

我们在设置开发环境时都曾有过这样的时刻——“哦,我还需要一样东西!”——这个“东西”是多一种语言或工具集(或者可能更多😊),以便在你的项目上工作。

开发容器是简化环境设置的好方法——它们提供了一个完整的编码环境,包含了你项目所需的工具。它们使用镜像、Dockerfile 或 Docker Compose 文件以及 devcontainer.json 进行配置,后者是一种元数据格式,用于通过开发特定的内容和设置来丰富容器。

在创建开发容器时,你可能会反复遇到同样的“我只需要一样东西!”的反应——也许你在 Dockerfile 中使用了一个 Node.js 镜像,而只需要添加 Git。或者,你可能需要添加更复杂的东西,比如在你的开发容器内使用 Docker 或 Kubernetes。开发容器非常棒,因为任何访问你代码的人都会获得相同、一致的体验,包括你添加的所有工具——但添加它们的最佳方式是什么呢?

如果有一种简单的方法,只需提及工具的名称和版本,就能在你的开发容器中安装那个额外的工具,那会怎么样?或者,作为工具用户或作者,你是否可以创建一种简单的方式让其他人安装它?共享手动脚本有助于重用,但在引用时,你可能会忘记引用容器或工具的设置,例如为 Go、Rust 或 C++ 调试启用 ptrace 支持,添加一个在容器启动时触发的特定入口点,或确保包含正确的 VS Code 扩展。

功能

我们很高兴地宣布,开发容器的**特性 (Features)** 能帮助你顺利地在开发容器中获得所需的工具!

特性是独立的安装代码、容器配置和/或设置及扩展单元,旨在为你的开发容器带来新的开发能力。它们可以被构建成能与多种基础容器镜像配合使用。作为我们致力于开放开发容器规范工作的一部分,我们对你从何处获取预创建的特性,以及如何编写和分发自己的特性进行了一些改进。

让我们看看有哪些新内容,以及如何开始使用任何支持开发容器的工具或服务(例如 VS Code 开发容器扩展或 GitHub Codespaces)中的特性!

向你的开发容器添加特性

开发容器特性提供了一种将开发容器元数据与一些安装步骤快速关联的方法。你可以通过简单的引用将它们添加到你的开发容器中。

这些特性现在可以作为 OCI 工件 (Artifacts) 存储在任何支持的容器注册表中,这意味着你可以使用与引用容器镜像相同类型的标识符来引用它们。我们已经将一些早期存在于 vscode-dev-containers 仓库中的特性迁移到了一个新的 devcontainers/features 仓库中,在那里它们使用这种新方法进行发布。

从 devcontainers/features 仓库引用不同的特性非常简单,只需在你的 devcontainer.json 中添加一个 features 属性即可。每个特性都有一个 README.md 文件,展示了如何引用该特性以及它有哪些可用选项。

下面的示例安装了 godocker-in-docker 特性。

"name": "my-project-devcontainer",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
    "ghcr.io/devcontainers/features/go:1": {
        "version": "1.18"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:1": {
        "version": "latest",
        "moby": true
    }
}

你也可以在规范网站上探索官方和社区贡献的特性。任何特性都可以通过编辑 devcontainer.json 来添加,而公开发布的特性可以通过现有的开发容器配置体验(例如 VS Code 开发容器扩展中提供的)来添加。

Specification site list of available Features

你甚至可以使用开发容器 CLI、GitHub Action 或 Azure DevOps 任务,在你喜欢的 CI 系统中使用带有特性的开发容器。我们在 devcontainers/ci 仓库中提供了 GitHub Action 和 Azure DevOps 任务。开发容器 CLI、GitHub Action 或 Azure DevOps 任务也可以用于预构建包含特性内容的镜像,以加快启动时间。

如果你不仅想使用公开可用的特性,还想创建自己的私有或公共特性来共享,请继续阅读!

编写特性

开始创建自己的特性的一个好地方是新的 特性模板仓库。除了包含一个适用于特定特性内容的良好模板外,该模板还包含一个 GitHub Actions 工作流,以便快速发布它们,它使用你账户的GitHub 容器注册表 (GHCR),让你能尽快上手。我们稍后会更多地讨论发布。

一个特性的源代码有两个组成部分:一个安装脚本 (install.sh) 和一个配置文件 (devcontainer-feature.json)。

+-- feature
|    +-- devcontainer-feature.json
|    +-- install.sh
|    +-- (other files)

install.sh: 安装入口点脚本——它在概念上被添加为镜像 Dockerfile 的一层,并在构建时执行。这个入口点脚本可以安装各种工具,如语言(例如 Ruby)和工具(GitHub CLI)。

devcontainer-feature.json: 这包含了关于特性的元数据、一组可以在安装过程中传递给特性安装脚本的选项,以及将合并到最终开发容器中的 devcontainer.json “片段”。例如,如果任何特性在其配置中指明了 "privileged": true,那么整个开发容器将以 --privileged 标志启动。

特性可以使用多种语言编写,最直接的是 shell 脚本。如果一个特性是用其他语言编写的,那么相关信息应该包含在元数据中,以便用户可以做出明智的选择。

注意: 虽然 install.sh 会运行任何语言的特性,但如果你用一种开发容器中不存在的解释型语言编写特性,代码将无法执行。请确保在 install.sh 中获取你需要的语言。

你应该确保你公开发布的特性除了安装特性本身外,还会检查并安装其依赖项。

此外,公共特性很可能会在 arm64 或 x86_64 机器上使用——因此请确保在可能的情况下进行适配。

你可以在规范中查看 devcontainer-feature.json 的属性,以及在 devcontainers/features 仓库中查看公开示例。

既然我们已经了解了如何创建一个特性,那么我该如何将它分发给其他人呢?

分发

特性以 tarball 的形式分发。tarball 包含特性子目录的全部内容,包括 devcontainer-feature.jsoninstall.sh 以及目录中的任何其他文件。

开放容器倡议 (OCI) 定义了容器和容器资源的行业标准。我们将特性视为 OCI 工件,并使用 OCI 注册表的概念来分发特性。

上面提到的 特性模板仓库包含一个 GitHub Actions 工作流来自动化发布过程。它将特性打包成一个 tarball,并将资产作为 OCI 工件发布到 GHCR。要触发模板仓库中的 release.yaml 工作流,只需在 GitHub 上仓库的 Actions 选项卡左侧选择它即可。该 GitHub Action 会将特性发布到 GHCR 的 <owner>/<repo> 命名空间下。只有当特性 devcontainer-feature.json 中的版本属性更新时,才会重新发布该特性。

注意: 对于 GHCR,有一个手动步骤是需要将 OCI 包标记为“公共”。每个特性只需执行一次此操作。私有特性不需要此步骤,只要你使用注册表的凭据登录了 Docker CLI 就可以访问。

与社区分享你的特性

如果你希望你的贡献出现在 VS Code 开发容器GitHub Codespaces 创建开发容器的 UI 中,你可以执行以下步骤:

一旦合并,你的更改将出现在 containers.dev/collections

特性安装顺序

如果我的特性应该在另一个特性之后安装怎么办?作为特性作者,你可能会发现你的特性应该在其他特性之前或之后安装。在你的 devcontainer-feature.json 中,你可以使用 installsAfter 属性来列出应在其之前执行的特性。

作为最终用户,你可以使用 devcontainer.json 中的 overrideFeatureInstallOrder 属性进一步控制执行顺序。此数组中的任何特性 ID 都将按提供的顺序在所有其他特性之前安装。举个例子:

"features": {
      "ghcr.io/devcontainers/features/java:1",
      "ghcr.io/devcontainers/features/node:1",
  },
  "overrideFeatureInstallOrder": [
    "ghcr.io/devcontainers/features/node"
  ]

默认情况下,特性会按照实现工具确定的最佳顺序安装在基础镜像之上。

如果特性的 devcontainer-feature.json 或用户的 devcontainer.json 中提供了以下任何属性,则会遵循这些属性指示的顺序(优先级递减)。

  1. 用户 devcontainer.json 中的 overrideFeatureInstallOrder 属性。允许用户控制其特性的执行顺序。
  2. 在特性的 devcontainer-feature.json 中定义的 installsAfter 属性。

你可以在规范中阅读更多关于特性执行和安装顺序的信息。

还有什么新内容?

除了新的特性仓库,我们最近还开源了一个新的 devcontainers/images 仓库,用于托管之前在 vscode-dev-containers 仓库中的一组特定镜像。

我们正在为开发容器模板(在 vscode-dev-containers 中我们称之为“定义”)制定一个社区分发计划,我们预计它将与特性类似。我们一定会像宣布新特性和镜像仓库时一样,在 vscode-dev-containers 仓库中发布更新。

我如何了解更多信息?

这篇文章只是浅尝辄止地介绍了你可以用特性做什么,我们很高兴你能亲自尝试!

如上文内容中链接所示,了解更多关于特性构成以及如何分发它们的最佳地点是开发容器规范的特性特性分发页面。

我们期待你在使用、创建和发布特性时的反馈——我们很想在特性特性分发的 issue 提案中听到它们对你的帮助。

如果你有兴趣参与整个规范的制定,或者将另一个工具接入以利用它,请查看开发容器的 specCLI 仓库。

祝你创建开发容器愉快,编码快乐!

Brigit Murtaugh, @BrigitMurtaugh