concourse/s3-resource

S3 Resource 镜像文档

1. 镜像概述和主要用途

S3 Resource 是一个用于版本化 Amazon S3 存储桶中对象的工具，通过文件名模式匹配自动识别版本号。该工具主要作为 Concourse CI/CD 流水线的资源类型，用于在 CI/CD 流程中管理 S3 存储桶内带有版本标识的文件（如软件包、构建产物等），实现版本的自动识别与追踪。

源码及完整文档：https://github.com/concourse/s3-resource

2. 核心功能和特性

• S3 对象版本化：通过文件名模式匹配对 S3 存储桶中的对象进行版本管理
• 文件名模式匹配：支持自定义正则表达式匹配文件名，提取版本标识
• 版本自动识别：基于文件名中的版本模式（如语义化版本 v1.2.3、日期戳 20240501 等）自动识别版本号
• Concourse 集成：作为 Concourse 资源类型，无缝集成到 CI/CD 流水线，支持资源的获取（get）和上传（put）操作

3. 使用场景和适用范围

• Concourse CI/CD 流水线：在软件构建、测试、发布流程中，管理 S3 存储的版本化文件（如安装包、镜像制品、配置文件等）
• 版本化文件管理：适用于需要通过文件名显式标识版本的场景，如开源软件发布包（app-v1.0.0.tar.gz）、按日期归档的日志文件（logs-20240501.zip）等
• S3 资源自动化：替代手动版本追踪，通过流水线自动关联 S3 对象版本与构建/发布流程

4. 使用方法和配置说明

4.1 前置条件

• 已部署 Concourse CI 环境
• 拥有 AWS S3 存储桶访问权限（需配置访问密钥）
• 目标 S3 文件的文件名包含可提取的版本标识（如 package-v2.1.0.zip）

4.2 Concourse 资源配置

4.2.1 资源类型定义

在 Concourse 流水线中，需先定义 s3-resource 资源类型：

yaml
resource_types:
- name: s3-resource
  type: docker-image
  source:
    repository: concourse/s3-resource
    tag: latest  # 或指定具体版本，如 v1.2.3

4.2.2 资源配置参数

定义资源时，需通过 source 字段配置 S3 连接信息及版本匹配规则，核心参数如下：

4.3 流水线任务示例

4.3.1 资源定义示例

yaml
resources:
- name: my-s3-assets
  type: s3-resource
  source:
    bucket: my-app-assets  # S3 存储桶名称
    access_key_id: ((aws-access-key))  # 通过 Concourse 变量存储密钥
    secret_access_key: ((aws-secret-key))
    region: ap-southeast-1
    regexp: app-(v\d+\.\d+\.\d+)\.tar\.gz  # 匹配文件名并提取版本（如 v1.2.3）
    version_pattern: v\d+\.\d+\.\d+  # 验证版本格式为 v+语义化版本

4.3.2 任务中使用资源

获取最新版本文件（get 操作）：

yaml
jobs:
- name: fetch-s3-asset
  plan:
  - get: my-s3-assets
    trigger: true  # 当 S3 有新版本文件时自动触发任务
  - task: use-asset
    config:
      platform: linux
      image_resource:
        type: docker-image
        source: {repository: alpine}
      inputs:
      - name: my-s3-assets  # 输入资源，包含从 S3 获取的文件
      run:
        path: sh
        args:
        - -c
        - |
          ls -l my-s3-assets/  # 列出获取的文件（含版本信息）

上传文件到 S3（put 操作）：

yaml
jobs:
- name: upload-to-s3
  plan:
  - task: build-asset
    config:
      # 省略构建步骤，假设输出文件为 output/app-v1.3.0.tar.gz
  - put: my-s3-assets
    params:
      file: output/app-*.tar.gz  # 上传匹配的文件到 S3

5. 环境变量说明

若未在 source 中配置 access_key_id 和 secret_access_key，可通过环境变量注入 AWS 认证信息（优先级低于资源配置）：

6. 版本匹配规则示例

假设目标文件名为 app-v2.1.0-beta.tar.gz，配置 regexp: app-(v.*)\.tar\.gz，则提取的版本号为 v2.1.0-beta。若同时配置 version_pattern: v\d+\.\d+\.\d+，则仅匹配 v2.1.0 格式，v2.1.0-beta 会被过滤。