redfactorlabs/concourse-smuggler-resource

concourse-smuggler-resource: Concourse通用资源工具

Smuggler是一个"通用资源"工具，允许你以最少的样板代码快速实现任何Concourse资源，甚至可以直接在流水线中实现。它支持在资源容器中为check/in/out操作运行任意命令或脚本，核心流程包括：解析Concourse输入JSON、设置参数环境变量、执行脚本、生成有效响应。适用于原型开发、PoC或简单资源的快速实现。

基本示例

以下资源定义使用sh ${RANDOM}变量生成随机数，get步骤将随机数写入指定文件并输出当前日期作为元数据：

yaml
# 添加自定义资源类型
resource_types:
- name: smuggler
  type: docker-image
  source:
    repository: redfactorlabs/concourse-smuggler-resource
    tag: alpine

resources:
# 随机数生成器
- name: random_number_generator
  type: smuggler
  source:
    smuggler_debug: true
    target_file: random_number_file
    commands:
      check: |
        echo "${RANDOM}" > ${SMUGGLER_OUTPUT_DIR}/versions
      in: |
        echo "${SMUGGLER_VERSION_ID}" > \
          ${SMUGGLER_DESTINATION_DIR}/${SMUGGLER_target_file}
        echo "date=$(date)" > ${SMUGGLER_OUTPUT_DIR}/metadata

jobs:
# 使用该资源的示例任务
- name: some_job
  plan:
  - get: random_number_generator
    trigger: true
  - task: print_the_number
    config:
      platform: linux
      image_resource:
        type: docker-image
        source:
          repository: alpine
      inputs:
      - name: random_number_generator
        params:
          target_file: my_random_number_file
      run:
        path: sh
        args:
        - -ec
        - |
          cat random_number_generator/my_random_number_file

其他示例

查看https://github.com/redfactorlabs/concourse-smuggler-resource/tree/master/examples%E8%8E%B7%E5%8F%96%E6%9B%B4%E5%A4%9A%E5%9C%BA%E6%99%AF%E7%A4%BA%E4%BE%8B%EF%BC%8C%E5%8C%85%E6%8B%AC%EF%BC%9A

• ssh-keygen资源：生成SSH密钥
• ssh-keygen-s3资源：生成SSH密钥并存储到S3
• s3-with-default资源：扩展官方S3资源，支持文件缺失时使用默认值

使用指南

定义check/in/out命令

通过commands.check、commands.in或commands.out指定脚本：

• commands.check：检查新版本，需将版本写入${SMUGGLER_OUTPUT_DIR}/versions（每行一个版本）
• commands.in：get步骤调用，将数据写入${SMUGGLER_DESTINATION_DIR}
• commands.out：put步骤调用，处理${SMUGGLER_SOURCES_DIR}中的输入文件

输入与输出

脚本通过以下方式与Concourse交互：

• 环境变量：如SMUGGLER_<param_name>（资源参数）、SMUGGLER_VERSION_<key>（版本信息）、SMUGGLER_OUTPUT_DIR（输出目录）等
• 文件：versions（版本列表）、metadata（元数据，key=value格式）
• 标准输入/输出：直接传递Concourse的JSON请求/响应（需符合Concourse资源规范）

资源参数

source或params中的参数会以SMUGGLER_前缀作为环境变量传入脚本，例如source.global_config_entry对应SMUGGLER_global_config_entry。

Smuggler特定参数

• smuggler_debug：是否开启调试日志（输出到stderr）
• filter_raw_request：是否过滤请求中的Smuggler配置参数
• smuggler_params.<param>：分组参数，可通过filter_raw_request过滤

参数优先级

参数覆盖顺序（优先级从高到低）：

1. 镜像内/opt/resource/smuggler.yml配置
2. source.smuggler_params
3. source直接参数
4. get/put步骤的params.smuggler_params
5. get/put步骤的params直接参数

日志与排障

操作日志存储在容器/tmp/smuggler.log，开启smuggler_debug可在Concourse UI查看日志。可通过fly intercept命令进入容器调试：

bash
fly -t demo intercept -c pipeline_name/resource_name # 拦截check容器
fly -t demo intercept -j pipeline_name/job_name # 拦截get/put容器

高级用法

• 镜像内置配置：在镜像/opt/resource/smuggler.yml中定义默认配置，流水线参数会覆盖默认值
• 包装其他资源：通过filter_raw_request过滤Smuggler参数，直接调用第三方资源命令
• 复杂命令：支持多行脚本或指定路径+参数的方式执行命令（如Python/Ruby脚本）

支持的镜像标签

• alpine/x.x.x-alpine：基于Alpine Linux
• ubuntu/x.x.x-ubuntu：基于Ubuntu Linux

贡献

欢迎分享你的实现和改进，详见AUTHORS文件。

致谢

本项目参考了多个开源资源（如s3-resource）的代码，感谢所有贡献者！