OCI Build Task 镜像文档

1. 镜像概述和主要用途

OCI Build Task 是一个用于构建符合 OCI 镜像规范的 Concourse 任务镜像。该任务基于 Buildkit 构建引擎，旨在为 Concourse CI/CD 流水线提供标准化、高效的容器镜像构建能力。

主要用途：在 Concourse 流水线中集成镜像构建步骤，将应用代码或服务打包为符合 OCI 标准的容器镜像，支持后续的镜像推送、部署等流程。

2. 核心功能和特性

OCI 标准兼容：构建产物严格遵循 OCI 镜像规范，确保与 Docker、containerd、CRI-O 等主流容器运行时兼容。
Buildkit 引擎支持：采用 Buildkit 作为底层构建引擎，支持增量构建、多阶段构建、并行依赖解析等高级特性，提升构建效率。
Concourse 原生集成：适配 Concourse 任务模型，支持通过流水线输入输出机制传递构建上下文、Dockerfile 及产物。
灵活配置：支持自定义构建参数、上下文路径、目标镜像标签等，满足多样化构建需求。

3. 使用场景和适用范围

适用场景

Concourse CI/CD 流水线中需构建容器镜像的环节。
团队需要标准化镜像构建流程，确保输出符合 OCI 规范的场景。
需利用 Buildkit 高级特性（如多阶段构建、缓存优化）提升构建效率的场景。

适用范围

使用 Concourse 作为 CI/CD 平台的开发团队。
对容器镜像可移植性、标准化有要求的项目（如跨平台部署、多运行时支持）。
需要在 CI/CD 流程中集成高效镜像构建能力的场景。

4. 使用方法和配置说明

4.1 前置条件

已部署 Concourse 环境，且流水线可访问该任务镜像。
流水线中已配置构建上下文资源（如代码仓库），包含 Dockerfile 及构建依赖文件。

4.2 Concourse 任务配置示例

在 Concourse 流水线（pipeline.yml）中定义 OCI Build Task 任务，典型配置如下：

yaml
jobs:
- name: build-oci-image
  plan:
  - get: source-code  # 输入：代码仓库资源（含 Dockerfile 和源代码）
    trigger: true
  - task: build-image
    image_resource:
      type: registry-image
      source: {repository: concourse/oci-build-task}  # OCI Build Task 镜像
    params:
      CONTEXT: source-code  # 构建上下文路径（相对于输入资源的根目录）
      DOCKERFILE: source-code/Dockerfile  # Dockerfile 路径
      IMAGE_NAME: my-app  # 目标镜像名称
      IMAGE_TAG: v1.0.0  # 目标镜像标签
      BUILD_ARG_APP_VERSION: v1.0.0  # 构建参数（对应 Dockerfile 中的 ARG APP_VERSION）
    inputs:
    - name: source-code  # 输入资源名称（与 get 步骤对应）
    outputs:
    - name: image  # 输出：构建生成的 OCI 镜像归档（image.tar）

4.3 参数说明

参数名	类型	描述	是否必填	默认值
`CONTEXT`	字符串	构建上下文路径，指定包含构建依赖文件的目录（相对于输入资源根目录）	是	-
`DOCKERFILE`	字符串	Dockerfile 文件路径（相对于 `CONTEXT` 路径）	否	`./Dockerfile`
`IMAGE_NAME`	字符串	目标镜像名称（如 `my-app`）	是	-
`IMAGE_TAG`	字符串	目标镜像标签（如 `v1.0.0`）	否	`latest`
`BUILD_ARG_<NAME>`	字符串	构建参数，格式为 `BUILD_ARG_<NAME>=<VALUE>`，对应 Dockerfile 中的 `ARG <NAME>`	否	-
`PUSH`	布尔值	是否推送镜像至仓库（需额外配置镜像仓库资源）	否	`false`
`REGISTRY`	字符串	镜像仓库地址（如 `docker.io/my-repo`，当 `PUSH=true` 时必填）	否	-