concourse/registry-image-resource

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 用于定义资源的基础信息，必填及可选参数如下：

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

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

示例：拉取 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 中配置）：

示例 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: https://github.com/example/my-app.git
    branch: main

- name: my-app-image
  type: registry-image
  source:
    repository: 123456789.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 版本导致兼容性问题。