TeamCity On-Premises 2024.03 Help

将 TeamCity 与容器管理器集成

TeamCity 与多个层级的容器管理器（Docker，Podman）进行集成。

  • Docker build runner 在构建过程中启动 Docker 命令并创建 Docker 镜像。

  • Docker Compose 构建运行程序在构建期间借助Docker Compose 工具启动服务。

  • 容器包装器 扩展 在容器内执行构建步骤。 支持 Docker 和 Podman。 适用于多个运行器。

  • Docker 支持 构建功能 会在开始构建之前自动使用 Docker 或 Podman 登录到容器注册表。 此功能还在 构建结果 中添加了 容器信息 标签页，其中包含有关在构建过程中发布到注册表的镜像的信息。

    容器信息"选项卡

您可以在上面链接的专门帮助文章中，了解有关所列工具的更多详细信息。 以下文章包含了这些工具的通用信息。

兼容性和需求

环境要求

要运行与 Docker 或 Podman 相关的操作，构建代理必须能够使用 docker 或 podman 可执行文件。

Docker 可以在 Linux、Windows 和 macOS 构建代理上安装。

  • 在 Linux 上，如果检测到已安装的 Docker，Docker 支持集成将会运行。

  • 在 Windows 上，该集成适用于 Linux 和 Windows 容器模式。

  • 在 macOS 上，运行构建代理的用户应安装官方的 Docker support for Mac。

Podman 主要是为 Linux 设计的工具。 要在 Windows 和 macOS 上运行，Podman 需要一个已安装的 Linux 虚拟机（"Podman machine"）。 参阅以下文章，了解如何在不同的操作系统上安装 Podman ：Podman 安装指南。

  • 在您的构建代理机器上的 registries.conf 文件中指定容器注册表域。 例如： unqualified-search-registries = ["docker.io"]。 Podman 和 TeamCity 需要此注册表列表来：

    • 当一个 podman ... 命令使用短镜像名称（例如， podman pull ubi8 而不是 podman pull registry.access.redhat.com/ubi8:latest ）时，解析完整的容器地址。

    • 如果您的构建配置具有 Docker 支持 构建功能，则成功登录注册表。

    请参阅以下文章，以了解更多关于 registries.conf 文件的信息： 如何管理 Linux 容器注册表。

  • 如果您正在运行配置为通过 systemd 自动启动的 Linux 构建代理，请启用用户驻留以保持用户会话运行： loginctl enable-linger my_agent_user。

工具

构建参数与代理需求

TeamCity 检查以下 parameters 来确定可用的代理软件：

  • container.engine — 根据 agent 机器上安装的容器管理器，返回 "docker" 、 "podman" 或 "docker,podman"。 如果 Docker 和 Podman 都已安装，TeamCity 默认会使用 Docker。

  • teamcity.default.сontainer.engine — 将此属性设置为 docker 或 podman ，以始终使用所需的工具。 此属性允许您覆盖默认逻辑，该逻辑在两种工具都可用时强制 TeamCity 使用 Docker。 您可以将此属性设置为 配置参数 或者作为单个代理的设置（在 buildAgent.properties 文件中）。

  • docker.server.version， docker.version — 分别返回已安装的 Docker Engine 和 Docker CLI 的版本。

  • podman.version — 存储已安装的 Podman 软件的版本。

  • docker.server.osType， podman.osType — 返回代理操作系统的类型。 支持的值包括 "linux"（适用于 Linux 和 macOS 代理）和 "windows"。

  • dockerCompose.version — 如果使用了 Docker Compose 构建步骤，则返回 Docker Compose 文件版本。

根据您使用的具体 Docker / Podman 集成，TeamCity 会指定不同的 代理兼容性要求。 例如，如果您的 构建配置 使用了 Docker 运行程序，那么只有满足 docker.server.version 存在 要求的代理才能运行此配置。

Docker 磁盘空间清理器

Docker Disk Space Cleaner 是 Free disk space 构建功能的扩展，确保构建有足够的磁盘空间。

TeamCity 定期清理它相关的已标记 / 拉取的 Docker 镜像：

对于这样的构建，

  • TeamCity 代理跟踪在构建过程中标记或拉取的 Docker 镜像（镜像列表存储在 buildAgent / system / docker-used-images.dat 文件中）。

  • 在清理 / 释放磁盘空间期间，如果这些镜像在过去3天（或1天或0天，再次尝试释放磁盘空间时）内未被使用，TeamCity 代理会尝试删除这些镜像。

此外，TeamCity 使用 docker/podman system prune --volumes 命令清理本地缓存。 对于 Docker 安装，此清理工作适用于 v.17.06.1 或更高版本。

报告推送镜像的服务消息

如果出于某些原因，TeamCity 无法确定已推送了镜像，用户可以发送特殊的 服务信息 向 TeamCity 服务器报告此信息：

##teamcity[dockerMessage type='dockerImage.push' value='<full_image_tag>,size:<size in bytes>,digest:<hash>']

例如：

##teamcity[dockerMessage type='dockerImage.push' value='myRegistry/repo-test:17,size:2632,digest:sha256:8dc5a195c3dcdc7c288d16288ff3f9ab1d8a5a230e09afb9c8dc9215e861aa55']

符合 Docker 下载速率限制

自2020年11月1日起，Docker Hub 为公开的镜像拉取引入了 下载速率限制。

如果您的 TeamCity 构建使用 容器包装器 或 Docker Compose 从 Docker Hub 拉取镜像，请确保这些拉取不超过以下限制：

  • 匿名 Docker 用户：每6小时内可拉取100次

  • 使用免费方案的 Docker 用户：每 6 小时可进行 200 次拉取

如果您有 Docker 的团队或专业帐户，拉取次数将保持无限制。

一般的 TeamCity 代理会在其缓存中存储一次拉取的镜像。 这允许定期使用同一拉取的镜像运行无限数量的构建。
然而，有几个情况需要考虑：

  • 如果您正在使用云代理，每次启动新的云代理时，将下载所有所需的镜像。

  • 如果在构建步骤设置中启用了 显式拉取镜像 选项，即使在本地代理上，每次新的构建运行也都会下载该镜像。 我们建议您禁用此选项，以防止达到速率限制。

  • 在为构建释放磁盘空间时，TeamCity 可能会从本地缓存中清理旧的未使用的 Docker 镜像。

如果您之前的构建是匿名访问 Docker Hub，您可以通过创建一个免费的 Docker 用户配置文件，并在您的 TeamCity 项目中配置一个 Docker connection，从而使允许的拉取次数翻倍。 TeamCity 代理将能够使用此连接在每次构建前进行 Docker Hub 的身份验证。

最后修改日期： 16日 7月 2024年
与 Perforce Helix Swarm 的集成 容器包装器