Buildkite Agent Docker 镜像文档

镜像概述和主要用途

Buildkite Agent Docker 镜像是用于在 Docker 环境中运行 Buildkite Agent 的官方镜像。Buildkite Agent 是 Buildkite CI/CD 平台的客户端组件，负责接收和执行来自 Buildkite 服务的构建任务，支持自动化构建、测试和部署流程。该镜像提供了便捷的容器化部署方式，简化了 Agent 的配置与管理。

核心功能和特性

• 多版本支持：提供稳定版本标签（如 3）和精确版本标签（如 3.0.1），满足不同环境需求。
• 灵活配置：支持通过环境变量或配置文件进行 Agent 配置，敏感数据推荐使用配置文件。
• 钩子自定义：允许挂载或添加自定义钩子（hooks），扩展构建流程（如环境准备、构建前后操作）。
• 机密管理：支持通过只读卷挂载构建机密（如密钥、证书），保障敏感信息安全。
• Git/SSH 集成：提供多种方式配置私有 Git 仓库认证（如 SSH 密钥、Git 凭据）。
• Docker-in-Docker 支持：可挂载 Docker 套接字，允许在构建过程中调用 Docker 命令。
• Entrypoint 扩展：支持通过 /docker-entrypoint.d/ 目录自定义启动流程，无需修改 ENTRYPOINT。

使用场景和适用范围

• 容器化 CI/CD 环境：在 Docker 或 Kubernetes 等容器平台中部署 Buildkite Agent。
• 隔离构建环境：通过容器隔离不同项目或任务的构建依赖，避免环境冲突。
• 多版本 Agent 管理：通过标签选择特定版本 Agent，确保构建环境一致性。
• 自定义构建流程：通过钩子机制集成私有工具链、认证流程或环境初始化逻辑。

版本选择

标签说明

• buildkite/agent 或 buildkite/agent:latest：默认指向最新稳定版（当前为 3.x 系列）。
• buildkite/agent:3：推荐用于新部署，指向 3.x 系列的最新稳定版。
• buildkite/agent:<版本号>：指定精确版本（如 3.0.1），适用于需要版本固定的场景。

查看所有版本

可访问 Docker Hub 标签页 查看所有可用版本。

详细使用方法和配置说明

基本使用

查看 Agent 帮助信息：

docker run --rm buildkite/agent:3 --help

配置 Agent

环境变量配置

大多数 Agent 配置项 可通过环境变量设置。注意：敏感数据（如 Agent Token）不建议通过环境变量或命令行参数传递，因为会在 docker inspect 等命令中暴露。

配置文件配置

推荐通过挂载配置文件进行配置，文件路径为容器内 /buildkite/buildkite-agent.cfg。示例：

docker run -it \
  -v "$HOME/buildkite-agent.cfg:/buildkite/buildkite-agent.cfg:ro" \
  buildkite/agent:3

配置文件格式参考 Buildkite Agent 配置文档。

添加钩子

钩子（hooks）用于自定义构建流程（如环境准备、构建前后操作），需挂载或复制到容器内 /buildkite/hooks 目录，并确保可执行。

挂载钩子目录（推荐）

通过只读卷挂载主机钩子目录：

docker run -it \
  -v "$HOME/buildkite-hooks:/buildkite/hooks:ro" \
  buildkite/agent:3

buildkite-hooks 目录下的文件（如 environment、pre-checkout）将作为钩子执行。

构建自定义镜像

基于官方镜像添加钩子：

FROM buildkite/agent:3
ADD ./hooks /buildkite/hooks/
# 确保钩子可执行
RUN chmod +x /buildkite/hooks/*

暴露构建机密

构建过程中需使用的机密（如密钥、证书）可通过只读卷挂载到容器内。推荐将主机机密目录挂载为只读数据卷。

示例：挂载主机 $HOME/buildkite-secrets 目录到容器 /buildkite-secrets：

docker run -it \
  -v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \
  buildkite/agent:3

可通过 environment 钩子将机密暴露为环境变量或配置工具（如 git、ssh）。

私有 Git 仓库认证

使用 Git 凭据文件

若机密目录包含 Git 凭据文件（如 /buildkite-secrets/git-credentials），可通过 environment 钩子配置 Git：

1. 创建主机钩子文件 $HOME/buildkite-hooks/environment：

#!/bin/bash
set -euo pipefail
git config --global credential.helper "store --file=/buildkite-secrets/git-credentials"
# 可添加其他环境变量
# export API_KEY=$(cat /buildkite-secrets/api-key)

2. 挂载钩子和机密目录：

docker run -it \
  -v "$HOME/buildkite-hooks:/buildkite/hooks:ro" \
  -v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \
  buildkite/agent:3

使用 SSH 密钥

若机密目录包含 SSH 密钥（如 /buildkite-secrets/id_rsa_buildkite_git），通过 environment 钩子配置 SSH：

1. 创建主机钩子文件 $HOME/buildkite-hooks/environment：

#!/bin/bash
set -euo pipefail
eval "$(ssh-agent -s)"
ssh-add -k /buildkite-secrets/id_rsa_buildkite_git
# 可添加其他环境变量
# export SSH_PASSPHRASE=$(cat /buildkite-secrets/ssh-passphrase)

2. 挂载钩子和机密目录（同上）。

其他认证方式

• 主机 SSH Agent：在主机运行 ssh-agent，将其套接字挂载到容器（如 -v $SSH_AUTH_SOCK:/ssh-agent，并设置 SSH_AUTH_SOCK=/ssh-agent）。
• 环境变量传递密钥：通过 docker-ssh-env-config 传递密钥（安全性较低，不推荐）。

在构建中调用 Docker

若构建任务需执行 Docker 命令（如构建镜像），需将主机 Docker 套接字挂载到容器：

docker run -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  buildkite/agent:3

注意：此配置赋予构建任务与主机 Docker 相同的权限（通常为 root 权限），需谨慎使用。

Entrypoint 自定义

镜像 Entrypoint 使用 tini 管理子进程信号传递。如需自定义启动流程，不建议重定义 ENTRYPOINT，推荐将可执行脚本复制到 /docker-entrypoint.d/ 目录。脚本需满足：

• 无文件扩展名；
• 具有可执行权限；
• 按字母数字顺序执行。

示例：添加自定义初始化脚本 my-init-script：

FROM buildkite/agent:3
ADD my-init-script /docker-entrypoint.d/
RUN chmod +x /docker-entrypoint.d/my-init-script

Docker 部署示例

docker run 完整示例

以下示例整合配置文件、钩子、机密和 Docker 套接字挂载：

docker run -d \
  --name buildkite-agent \
  -v "$HOME/buildkite-agent.cfg:/buildkite/buildkite-agent.cfg:ro" \
  -v "$HOME/buildkite-hooks:/buildkite/hooks:ro" \
  -v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  buildkite/agent:3

docker-compose 示例

创建 docker-compose.yml：

version: '3'
services:
  buildkite-agent:
    image: buildkite/agent:3
    volumes:
      - ./buildkite-agent.cfg:/buildkite/buildkite-agent.cfg:ro
      - ./hooks:/buildkite/hooks:ro
      - ./secrets:/buildkite-secrets:ro
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always

启动命令：docker-compose up -d