Registry Image Resource 技术文档

1. 镜像概述和主要用途

Registry Image Resource 是 Concourse CI 的核心资源类型（Resource Type），用于与 OCI（Open Container Initiative）兼容的容器镜像仓库（如 Docker Hub、AWS ECR、Google GCR、Harbor 等）进行交互。其主要用途是在 CI/CD 管道中实现镜像版本的检查、拉取与推送，支持自动化镜像生命周期管理。

2. 核心功能和特性

2.1 核心操作

检查（Check）：自动检测目标镜像仓库中的镜像版本更新，支持基于标签（tag）或摘要（digest）的版本识别。
拉取（Fetch）：将仓库中指定版本的镜像拉取至 Concourse 工作目录，供后续任务（如部署、测试）使用。
推送（Push）：将本地构建的镜像（或现有镜像）推送至远程仓库，并支持自定义标签、多标签推送等。

2.2 关键特性

OCI 兼容性：全面支持符合 OCI 规范的镜像仓库及镜像格式。
多仓库支持：兼容 Docker Hub、AWS ECR、Google GCR、Azure ACR、Harbor 等主流仓库。
灵活认证：支持用户名密码、AWS ECR 临时凭证、私有仓库证书认证等多种方式。
版本控制：可通过标签（tag）或不可变摘要（digest）精确控制镜像版本。

3. 使用场景和适用范围

3.1 典型场景

镜像推送：CI 构建完成后，将应用镜像推送至远程仓库（如构建→测试→推送镜像至 ECR）。
镜像拉取：从仓库拉取基础镜像（如 Ubuntu、Node.js）用于构建环境初始化，或拉取依赖服务镜像用于集成测试。
版本监控：检测仓库中目标镜像的新版本（如基础镜像更新），触发下游构建或部署流程。

3.2 适用范围

Concourse CI/CD 管道中的镜像管理环节。
需要与 OCI 镜像仓库交互的自动化流程（如微服务部署、容器化应用发布）。

4. 使用方法和配置说明

4.1 资源类型定义（Resource Type）

需在 Pipeline 中声明资源类型，指定***镜像（默认已内置，如需特定版本可显式定义）：

yaml
resource_types:
- name: registry-image
  type: registry-image
  source:
    repository: concourse/registry-image-resource
    tag: latest  # 可指定具体版本，如 v1.16.0

4.2 资源配置（Resource Configuration）

在 resources 中定义具体资源，包含仓库地址、认证信息等核心配置：

yaml
resources:
- name: my-app-image
  type: registry-image
  source:
    # 核心配置参数（详见 4.3.1）
    repository: my-registry.example.com/my-app  # 镜像仓库地址（含命名空间）
    tag: latest  # 目标标签（可选，默认 latest）
    username: ((registry-username))  # 仓库认证用户名（敏感信息建议用 Concourse 凭证管理）
    password: ((registry-password))  # 仓库认证密码
    # 其他可选配置（如 AWS ECR 认证、 insecure 仓库等）

4.3 配置参数详解

4.3.1 Source 配置（资源源配置）

source 用于定义资源的基础信息，必填及可选参数如下：

参数	类型	说明
`repository`	字符串	必填，镜像仓库完整路径（如 `docker.io/library/nginx` 或 `***.dkr.ecr.us-west-2.amazonaws.com/my-app`）。
`tag`	字符串	可选，默认标签（如 `latest`），若不指定则需在 `get/put` 步骤中显式指定。
`username`	字符串	可选，仓库登录用户名（私有仓库必填）。
`password`	字符串	可选，仓库登录密码（私有仓库必填，与 `username` 配对）。
`aws_access_key_id`	字符串	可选，AWS ECR 专用，用于生成临时凭证（需配合 `aws_secret_access_key`）。
`aws_secret_access_key`	字符串	可选，AWS ECR 专用，与 `aws_access_key_id` 配对。
`insecure_registries`	布尔	可选，默认 `false`，是否允许连接未加密的 HTTP 仓库（仅测试环境使用）。
`ca_certs`	字符串	可选，私有仓库 CA 证书内容（PEM 格式），用于自签名证书验证。

4.3.2 Get 操作参数（拉取镜像）

通过 get 步骤拉取镜像，支持以下参数（在 params 中配置）：

参数	类型	说明
`skip_download`	布尔	可选，默认 `false`，是否仅获取镜像元数据（如 digest）而不下载完整镜像。
`format`	字符串	可选，默认 `docker`，输出格式（`docker` 为 Docker 镜像格式，`oci` 为 OCI 镜像格式）。
`output_metadata`	字符串	可选，指定元数据输出文件路径（如 `metadata.json`），包含镜像 digest、tag 等信息。

示例：拉取 my-app-image 并输出元数据

yaml
jobs:
- name: pull-image
  plan:
  - get: my-app-image
    params:
      output_metadata: image-metadata.json  # 元数据输出至当前目录

4.3.3 Put 操作参数（推送镜像）

通过 put 步骤推送镜像，支持以下核心参数（在 params 中配置）：

参数	类型	说明
`image`	字符串	必填，本地镜像路径（如 `./my-app-image.tar`，需为 `docker save` 或 OCI 归档格式）。
`tag`	字符串/列表	可选，推送的标签（支持单个标签字符串或多个标签列表，如 `v1.0.0` 或 `[v1, latest]`）。
`build`	映射	可选，直接基于 Dockerfile 构建并推送（替代 `image` 参数），包含 `dockerfile`（Dockerfile 路径）、`context`（构建上下文路径）等子参数。
`cache`	布尔	可选，默认 `true`，是否启用构建缓存（仅 `build` 参数生效）。
`digest_file`	字符串	可选，指定 digest 输出文件路径（如 `digest.txt`），记录推送后的镜像唯一标识。

示例 1：推送本地归档镜像

yaml
jobs:
- name: push-image
  plan:
  - put: my-app-image
    params:
      image: ./built-image.tar  # 本地镜像归档文件
      tag: v1.0.0  # 推送标签

示例 2：基于 Dockerfile 构建并推送

yaml
jobs:
- name: build-and-push
  plan:
  - get: source-code  # 假设已通过 git 资源拉取源码
  - put: my-app-image
    params:
      build:
        dockerfile: source-code/Dockerfile  # Dockerfile 路径
        context: source-code  # 构建上下文（源码目录）
      tag: [v1.0.0, latest]  # 推送多个标签

5. 完整 Pipeline 示例

以下为包含镜像拉取、构建、推送的完整 Pipeline 配置示例：

yaml
resource_types:
- name: registry-image
  type: registry-image
  source:
    repository: concourse/registry-image-resource
    tag: v1.16.0  # 指定资源版本

resources:
- name: app-source
  type: git
  source:
    uri: [***]
    branch: main

- name: my-app-image
  type: registry-image
  source:
    repository: ***.dkr.ecr.us-west-2.amazonaws.com/my-app  # AWS ECR 仓库
    aws_access_key_id: ((aws-access-key))
    aws_secret_access_key: ((aws-secret-key))

jobs:
- name: build-and-push
  plan:
  - get: app-source  # 拉取源码
  - put: my-app-image  # 构建并推送镜像
    params:
      build:
        dockerfile: app-source/Dockerfile
        context: app-source
      tag: 
        - $(cat app-source/VERSION)  # 从源码 VERSION 文件读取标签
        - latest  # 附加 latest 标签

6. 注意事项

敏感信息管理：仓库认证信息（如 username、password）需通过 Concourse Credentials Manager（如 Vault、CredHub）注入，避免明文暴露。
仓库兼容性：确保目标仓库支持 OCI 规范（Docker 仓库 v2.3+ 均兼容）。
网络配置：Concourse Worker 需能访问目标镜像仓库（开放网络端口，配置代理或私有仓库 DNS）。
版本稳定性：生产环境建议指定资源类型的具体版本（如 tag: v1.16.0），避免依赖 latest 版本导致兼容性问题。