cfje/http-resource

HTTP Concourse Resource 镜像文档

1. 镜像概述

该镜像为Concourse CI/CD平台提供HTTP资源类型支持，允许流水线与HTTP端点进行交互。作为Concourse资源，它可作为输入资源（从HTTP服务获取数据）或输出资源（向HTTP服务发送数据），实现流水线与外部HTTP服务的集成。

2. 核心功能与特性

• 多HTTP方法支持：兼容GET、POST、PUT、DELETE等标准HTTP方法
• 响应格式处理：支持JSON、XML、纯文本等多种响应格式解析
• 认证机制：集成Basic Auth、Bearer Token等常见HTTP认证方式
• 版本化跟踪：通过检测HTTP响应变化自动识别资源新版本，支持流水线触发
• 网络配置：可自定义请求超时时间、重试策略及请求头
• 灵活数据处理：支持请求体自定义及响应数据过滤提取

3. 使用场景与适用范围

• 从外部API获取配置数据或依赖包作为流水线输入
• 向webhook服务发送构建结果、部署状态等通知
• 与RESTful服务集成实现数据同步或状态更新
• 监控HTTP端点健康状态并触发异常处理流水线
• 提交表单数据或上传文件至HTTP服务

4. 使用方法与配置说明

4.1 定义资源类型

在Concourse Pipeline配置中，首先声明HTTP资源类型：

yaml
resource_types:
- name: http-resource
  type: docker-image
  source:
    repository: [镜像仓库地址]  # 例如: concourse/http-resource
    tag: latest  # 建议使用具体版本号

4.2 配置资源实例

使用声明的资源类型定义具体HTTP资源，配置source参数指定HTTP交互细节：

yaml
resources:
- name: example-http-resource
  type: http-resource
  source:
    url: "https://api.example.com/data"  # 目标HTTP端点URL（必填）
    method: "GET"  # HTTP请求方法（可选，默认GET）
    headers:  # 自定义请求头（可选）
      Accept: "application/json"
      User-Agent: "concourse-http-resource/1.0"
    auth:  # 认证配置（可选）
      type: "basic"  # 认证类型，支持"basic"或"bearer"
      username: "admin"  # Basic Auth用户名（type为basic时必填）
      password: "secret"  # Basic Auth密码（type为basic时必填）
      # token: "xyz123"  # Bearer Token（type为bearer时必填）
    response_filter: ".metadata.version"  # JSONPath表达式，提取版本标识（可选）
    timeout: "30s"  # 请求超时时间（可选，默认30s）
    retry_count: 2  # 请求失败重试次数（可选，默认0）
    body: '{"param": "value"}'  # 请求体内容（POST/PUT等方法时使用，可选）

4.3 在流水线Job中使用

4.3.1 作为输入资源（获取HTTP数据）

通过get步骤获取HTTP端点数据，支持自动触发：

yaml
jobs:
- name: process-http-data
  plan:
  - get: example-http-resource
    trigger: true  # 当HTTP响应变化时自动触发Job
  - task: analyze-data
    config:
      platform: linux
      image_resource:
        type: docker-image
        source: { repository: alpine }
      inputs:
      - name: example-http-resource  # 输入资源挂载路径
      run:
        path: sh
        args:
        - -c
        - |
          # HTTP响应数据默认保存至资源目录下的output文件
          cat example-http-resource/output.json  # JSON响应示例

4.3.2 作为输出资源（发送HTTP数据）

通过put步骤向HTTP端点发送数据，支持文件内容作为请求体：

yaml
jobs:
- name: send-to-api
  plan:
  - task: generate-payload
    config:
      platform: linux
      image_resource: { type: docker-image, source: { repository: alpine } }
      outputs:
      - name: payload  # 输出目录，存放请求体文件
      run:
        path: sh
        args:
        - -c
        - |
          echo '{"status": "success", "build_id": "123"}' > payload/body.json
  - put: example-http-resource
    params:
      file: payload/body.json  # 指定请求体文件路径（必填）

4.4 核心配置参数说明

5. 完整Pipeline示例

yaml
resource_types:
- name: http-resource
  type: docker-image
  source:
    repository: concourse/http-resource
    tag: v1.2.0

resources:
- name: app-config
  type: http-resource
  source:
    url: "[***]"
    method: "GET"
    headers:
      Accept: "application/json"
    auth:
      type: "bearer"
      token: ((config-api-token))  # 引用Concourse密钥管理中的变量

- name: deployment-webhook
  type: http-resource
  source:
    url: "[***]"
    method: "POST"
    headers:
      Content-Type: "application/json"

jobs:
- name: deploy-with-config
  plan:
  - get: app-config
    trigger: true  # 配置更新时自动触发部署
  - task: prepare-deploy
    config:
      platform: linux
      image_resource: { type: docker-image, source: { repository: alpine } }
      inputs: [name: app-config]
      outputs: [name: deploy-info]
      run:
        path: sh
        args:
        - -c
        - |
          CONFIG_VERSION=$(jq -r .version app-config/output.json)
          echo '{"version": "'"$CONFIG_VERSION"'", "status": "ready"}' > deploy-info/payload.json
  - put: deployment-webhook
    params:
      file: deploy-info/payload.json  # 发送部署信息至webhook