Skip to content

Latest commit

 

History

History
176 lines (125 loc) · 5.85 KB

proposal.md

File metadata and controls

176 lines (125 loc) · 5.85 KB

Resource Prototypes

A resource prototype is an interface implemented by a prototype which allows it to be used as a resource in a pipeline.

Motivation

Proposal

A resource prototype implements the following messages:

  • check
  • get
  • put (optional)
  • delete (optional)

Their behavior is described as follows.

check: discover new versions of a resource

Initially, the check handler will be invoked with an object containing only the fields configured by the resource's source: in the pipeline. A MessageResponse must be emitted for all versions available in the source, in chronological order.

Subsequent check calls will be run with a clone of the configuration object with the last emitted version object merged in. The check handler must emit the specified version if it still exists, followed by all versions detected after it in chronological order.

If the specified version is no longer present, the check handler must instead emit all available versions, as if the version was not specified. Concourse will detect this scenario by noticing that the first version emitted does not match the requested version. The given version, along with any other versions that are not present in the returned set of versions, will be marked as deleted and no longer be available.

The check handler can use the bits directory to cache state between runs. On the first run, the directory will be empty.

There is no check step syntax. Concourse will check every configured resource and maintain its version history.

get: fetch a version of a resource

The get handler will be invoked with an object specifying the version to fetch.

The get handler must fetch the resource into an output named resource under the bits directory.

A MessageResponse must be emitted for all versions that have been fetched into the bits directory. Each version will be recorded as an input to the build.

When a get handler is invoked by a get step in a build plan, the output will be mapped to the resource's name in the pipeline:

resources:
- name: some-resource
  type: git
  source:
    uri: https://example.com/some-repo

jobs:
- name: get-and-test
  plan:
  - get: some-resource
  - task: unit
    file: some-resource/ci/unit.yml

Assuming the latest commit of some-resource is abcdef, this would be similar to the following build plan:

jobs:
- name: get-and-test
  plan:
  - run: get
    type: git
    params:
      uri: https://example.com/some-repo
      ref: abcdef
    output_mapping:
      resource: some-resource
  - task: unit
    file: some-resource/ci/unit.yml

The bits fetched by a get step may be cached so that the same version does not have to be fetched repeatedly.

put: idempotently create resource versions

The put handler will be invoked with user-provided configuration and arbitrary bits.

A MessageResponse must be emitted for all versions that have been created/updated.

When a put step is used in a build plan, each version emitted will be recorded as an output of the build.

A get field may be explicitly added to the step, specifying a name to fetch the last-emitted version as:

jobs:
- name: push-pull-resource
  plan:
  # put to 'my-resource', and then get the last emitted version object as
  # 'some-name' for use later in the build plan
  - put: my-resource
    get: some-name

This replaces the "implicit get after put" behavior, which will remain for resources provided by resource_types: for backwards-compatibility.

delete: idempotently destroy resource versions

The delete handler will be invoked with user-provided configuration and arbitrary bits.

A MessageResponse must be emitted for all versions that have been destroyed.

When a delete step is used in a build plan, each version emitted will be marked as "deleted" and no longer be available for use in other builds.

jobs:
- name: prune-release-candidates
  plan:
  - delete: concourse-rc
    params: {regexp: concourse-[0-9]+\.[0-9]+\.[0-9]+-rc.[0-9]+.tgz}

Migration Path

Concourse pipelines will support resource_types: and prototypes: side-by-side.

Resources backed by a resource type will retain all of today's behavior for backwards-compatibility. We don't want to force a big-bang migration of every Concourse user's pipelines.

Resources backed by a prototype will gain all the behavior described in this proposal. Pipeline authors are encouraged to transition from resource types to prototypes, which they can do gradually.

There is no EOL date specified for resource types support. They would likely be supported for a number of years.

Open Questions

n/a

Answered Questions