Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: generalize resource interface #24

wants to merge 28 commits into from


Copy link

@vito vito commented Apr 3, 2019


Status: stable draft

Please leave comments on individual lines so that conversations can be threaded and resolved. Comments left at the toplevel unnecessarily will be brutally destroyed maintained so that the conversation doesn't get out of hand.

Related RFCs which specify how this interface is interpreted:

  • #26 (artifact resources)
  • #27 (trigger resources)
  • #28 (notification resources)
  • #29 (spatial resources)

Previous discussions:

vito added 2 commits Apr 3, 2019
the proposal itself is not yet fleshed out at all - still in the
information collecting phase so that the motivations are clear

Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
@vito vito changed the title RFC: generalized resource interface RFC: generalize resource interface Apr 3, 2019
vito added 15 commits Apr 3, 2019
Signed-off-by: Alex Suraci <> a bunch of tweaks to make the markdown linter happy

Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
I decided to stray from the initial v2 doc, which had a 'reset' event
type and a 'discovered' event type. Instead 'check' only returns a
stream of JSON objects containing config and metadata.

Signed-off-by: Alex Suraci <>
Since `put` can both create and delete configs, it seems better to keep
them all using the same event structure, even if 'check' can only emit
one type of event (`discovered`).

The alternative to this would be to split deleting out of 'put'. At that
point they would each emit a single type of event, and the interface
would be less open-ended. There's value in that, but that value has to
be weighed against the value of being able to create + delete in one
action. It's also not super clear that all resource types would support
'delete'. (But then, not all of them will support 'put', either.)

Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
this removes 'event types' from the response from each action, and
now they all have the same response.

event types were needed because 'put' could both create and delete, and
we needed a way to tell the difference. so instead, we've split 'delete'
out, and now each action has only one way to interpret the events, so
the types are no longer needed.

this makes the interface a bit less flexible, but it seems worth seeing
how far we can go with this constraint for the sake of having a simpler,
more focused interface. if we can go the distance with this limitation
it feels like stronger validation of the resources concept.

along the way I've put the configuration for each command under an
'actions' field in the info response. i'd like to also have it so
actions are optional, i.e. you can have a resource that doesn't
implement 'delete' or 'put'. this seems like it'll be necessary if we
want a common resource interface to be used for things like
notifications or triggers where there's nothing to really delete, and
even today there are cases where resources are 'read-only' and don't
support put at all (e.g. RSS).

Signed-off-by: Alex Suraci <>
we were already relying on image semantics here by expecting it to be in
the working directory, so relying on CMD should be no worse.

this will allow greater flexibility for resource type authors, allowing
for a single-binary entrypoint rather than forcing them to have an
'info' executable in a particular location.

Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
check no longer emits 'reset', it emits the given version first to show
it still exists (just as today)

Signed-off-by: Alex Suraci <>
Signed-off-by: Alex Suraci <>
these all go hand-in-hand so they have the same RFC number and are in
the same PR, but they each deserve their own proposals

Signed-off-by: Alex Suraci <>
@vito vito force-pushed the generalized-resources branch from ca06f53 to 80f3ce1 Compare Apr 8, 2019
vito added 3 commits Apr 8, 2019
Signed-off-by: Alex Suraci <>
this will allow us to have a common mechanism for configuring TLS across
all resource types. having it be a formal part of the interface feels
sensible as all resources are meant to interact with external state -
and in doing so, TLS will be a commonplace.

a later RFC (or perhaps another proposal within this one) will
demonstrate how users configure TLS - it may be something like the
pipeline-level, or another field alongside 'source' on the resource

Signed-off-by: Alex Suraci <>
this is not well-defined yet and this is easy enough to do as a later
iteration of the resource interface, now that it's versioned.

Signed-off-by: Alex Suraci <>
024-generalized-resources/ Outdated Show resolved Hide resolved
fixes concourse/concourse#3789

Signed-off-by: Alex Suraci <>
vito added 2 commits May 18, 2019
Signed-off-by: Alex Suraci <>
* introduce artifacts: and how it can be used as a migration path for
  explicit `get` after `put`
* update open/closed questions (they are all now closed)

Signed-off-by: Alex Suraci <>
@vito vito mentioned this pull request May 21, 2019
@vito vito mentioned this pull request May 21, 2019
@vito vito mentioned this pull request May 21, 2019
vito added 3 commits May 21, 2019
each of these proposals should be submitted as separate RFCs. each RFC
should show how the v2 *and* v1 interfaces are to be interpreted.

i've also removed the artifact resources proposal, which I initially
included in order to provide a concrete example relating today's
resource usage to the v2 interface. however, it can technically be done
independently of the v2 interface, if not just as a way of achieving
'explicit `get` after `put`' in a backwards-compatible way. so let's
just propose it separately and link to all four to demonstrate how it is
just one of four proposed interpretations.

Signed-off-by: Alex Suraci <>
these are being made independent of v1 vs. v2

Signed-off-by: Alex Suraci <>
calling this something that sounds like better english until someone
has a good reason otherwise

Signed-off-by: Alex Suraci <>
@concourse concourse deleted a comment from jchesterpivotal May 22, 2019
@concourse concourse deleted a comment from jchesterpivotal May 22, 2019
@concourse concourse deleted a comment from jchesterpivotal May 22, 2019
Signed-off-by: Alex Suraci <>
@vito vito marked this pull request as ready for review May 28, 2019
* Examples: `{"uri":""}`, `{"interval":"10m"}`

* **Config fragment**: a smaller JSON object intended to be "spliced" into a **config** by assigning each field from the fragment into the config.
* Examples: `{"ref":"abcdef"}`, `{"branch":"develop"}`
Copy link
Member Author

@vito vito Jun 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be careful with the allowed syntax for the keys - i.e. disallow : since we use it for version syntax in fly check-resource.

Copy link
Member Author

@vito vito commented Nov 7, 2019

closing in favor of #37

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet
1 participant