[TEP-0081] Proposal: Convention for param/result reserved names

[mattmoor]

This builds on #503 to actually define a convention for parameter and result names.

/hold

Putting a hold since this is dependent on the other PR (separate commits).

[jerop]

/assign @jerop @bobcatfish @vdemeester

[bobcatfish]

i think asking Tasks to produce chains specific outputs introduces some coupling between specific Tasks and Pipelines and chains that it would be nice to avoid

maybe im getting caught up on the name, maybe if it was tekton.attestion instead of tekton.chains.attestation it would resonate with me more

the point is that chains is just one possible tool that could be observing this data - i think we should avoid introducing coupling between chains and pipelines if we can

[mattmoor]

To be completely clear: there should be zero code in tektoncd/pipeline that is aware of these conventions, but it should support users expressing them (thus the . TEP, but that's where it should end).

The point is to enable Task/Pipeline authors to target certain conventions (think: implement an interface or duck type) in order to hook into a semantic of a higher level system.

Whether chains is in the string or not, is a bikeshed out of scope for this TEP, this TEP is strictly about using reverse-domain scoping. This example is purely illustrative.

[bobcatfish]

side note about volumes and volumemounts, workspaces provide a way to make it easy to provide the actual volumes at runtime instead of requiring the volume be declared in the Task

[mattmoor]

Ack. I don't want to paint the bikeshed on illustrative examples, but I'm sure I could come up with (perhaps contrived) examples where each is "better" than the other in some regard.

[bobcatfish]

im guessing that the reverse domain approach has a lot of precedent - maybe it would be helpful to point to some?

having less exposure to these, from my perspective dev.tekton confuses me when i read it b/c i start wondering "what is dev" and additionaly wondering if it is some kind of stability indication (e.g. is there some kind like v1.tekton)

one (maybe minor) downside i can think of is what if we want to establish some kind of namespace that doesnt map to a some specific domain name

(and would dev.tekton.chains imply that chains.tekton.dev should resolve to something?)

[mattmoor]

I thought I did, but off the top of my head:

• Java imports
• CloudEvent types
• containerd plugins

(I'll make sure these land in the TEP, but I thought they were there 🤔 )

and would dev.tekton.chains imply that chains.tekton.dev should resolve to something

As with K8s apiGroup this is a subjective thing, but a nice thing folks could elect to do.

[mattmoor]

You are totally right. I think I spaced on including these as I was plowing through the sections of the template. I'll rebase and push a list of these now.

[mattmoor]

Ok, I added it under "Notes / Caveats" for now, lmk if there's someplace better, but I figured with it being right under "Proposal" it fit.

[bobcatfish]

would this be enforced somehow?

[mattmoor]

Whether it is even possible to create a conformance test is impossible to say outside of the context of a specific semantic, and this TEP isn't about defining any of these semantic interfaces, simply around laying the foundation to enable them.

I suspect for certain semantics, it could be possible to test certain point aspects of conformance (like "this Task emits results that are compatible with what something like Chains would sign")

[tekton-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign bobcatfish
You can assign the PR to them by writing /assign @bobcatfish in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• teps/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[vdemeester]

Very naive question, what differs from #503 ? Is it just about "making" a convention out of what would results from #503 ?

[mattmoor]

Is it just about "making" a convention out of what would results from #503 ?

Yes, #503 is just about allowing ., this is about establishing a convention akin to the use of domains in K8s labels/annotations or reverse-domain for Java packages et al.

[mattmoor]

/hold cancel

I have rebased this now that TEP-0080 has landed, and added the precedent of OCI annotations. This should be RFAL.

[bobcatfish]

@mattmoor I'm not totally understanding what it would mean to accept this TEP - i.e. what would we actually DO? (e.g. publish some docs, maintain a list of reserved scopes?) if I missed this info in the PR plz just point me in the right direction

[mattmoor]

@bobcatfish Yeah, good question.

It could be docs, but in some sense I see this (and acknowledgement of this agreement by some of the core stewards) as the sort of core meta artifact.

Beyond the scope of this, I think the subsequent artifacts (owned by Tekton) will be the sorts of conventions Tekton adopts using this (under dev.tekton.*), and how those manifest in the various repos (for instance, I think Catalog will have a strong voice in shaping those!).

[tekton-robot]

@mattmoor: PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[bobcatfish]

I think the subsequent artifacts (owned by Tekton) will be the sorts of conventions Tekton adopts using this (under dev.tekton.*)

Do you have any examples of what these artifacts might look like?

(for instance, I think Catalog will have a strong voice in shaping those!).

If you have any ideas of specifically how this would impact the catalog (maybe an example of an existing Task that would benefit) I think that would be great to include

I'm not sure if this is the kind of thing you have in mind, but a couple important "schemas" I think Tekton should define and care about are: details when an image has been built and params that are needed when you clone a git repo (and probably outputs as well to reflect what was actually cloned). Is that the kind of thing you image using something like dev.tekton for? e.g. if you're producing an image artifact, (borrowing the object syntax from TEP-0075) something like:

     results:
       - name: "dev.tekton.builtImage"
         type: object
         properties:
           url:
            type: string
           digest:
            type: string

(nit could we do "tekton.dev/buildImage" instead...)

[mattmoor]

Do you have any examples of what these artifacts might look like?

I'd say a mix of TEPs, and (for those) docs so it is clear how folks integrate with conventions like these.

I'm not sure if this is the kind of thing you have in mind

Yeah, images that are produced are exactly one of the cases I had in mind, and probably one of the first cases we should tackle because the pattern matching Chains has to do today is extremely janky 😅

I totally agree that TEP-0075 would be very complementary here, and avoid an explosion of things that could be objects, but I suspect we will quickly yearn for SchemaRefs 😁

could we do "tekton.dev/buildImage" instead

It's certainly an option. K8s does this, but has limits like single-slash. One thing I think we should think about (it can be here or elsewhere) is how we deal with higher-arity things. To be fair, the answer here may just be TEP-0075, most of my thinking on this aspect predates that.

One of the things I had in mind was that folks could use dev.tekton.build-image if a single image was produced, but we could also use dev.tekton.build-image.<name> to support multiple named outputs (maybe both if one is the "main" output).

[bobcatfish]

I'd say a mix of TEPs, and (for those) docs so it is clear how folks integrate with conventions like these.

I'd still like to see something more concrete as a deliverable but maybe agreeing that we think this direction makes sense is enough for now?

One of the things I had in mind was that folks could use dev.tekton.build-image if a single image was produced, but we could also use dev.tekton.build-image. to support multiple named outputs (maybe both if one is the "main" output).

hm it'd be nice if we could find a way to not start encoding even more structure into these reserved names - it feels like an array of dev.tekton.build-image objects is probably what we'd really want here?

Thinking about it more maybe dev.tekton.build-image isn't the way we'd want to go for chains - I think we'd want to have some kind of duck typing vs. requiring any specific name for the result, do you agree? e.g. if you produce an object with the properties image-urland image-digest we assume you've built an image 🤔 🤔 🤔

I think I'd have an easier time wrapping my head around this TEP if we were trying to agree on structure for some specific examples, e.g. what interface Chains will be using an expecting - that's probably a separate TEP but I'm just still not totally understanding what we'd be agreeing to here with this TEP approved - without the TEP there's nothing to stop anyone from using this kind of naming scheme.

[mattmoor]

Listening to Solarwinds talk, one things that came to mind might be to have a standard result name that can be consumed to get turned into a github check / commit status by a separate observer controller (like Chains is)

[bobcatfish]

re the comments ive left above my biggest question is if that interface is defined by the name of the results or if it's by the shape of the results

e.g.

     results:
       - name: "dev.tekton.builtImage"
         type: object
         properties:
           url:
            type: string
           digest:
            type: string

vs

     results:
       - name: "lotsOfImageInfo"
         type: object
         properties:
           dev.tekton.url: #maybe the namespaced idea still makes sense for the fields that fulfill the "duck typing"?
            type: string
           dev.tekton.digest:
            type: string
           phaseOfTheMoon:
            type: string
           taskSpecificStuffImInterestedIn:
            type: string

In the first example chains/github check/whatever would be looking for a result with an explicit name, in the second example, chains would be looking for fields within a result

[tekton-robot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

[tekton-robot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten with a justification.
Rotten issues close after an additional 30d of inactivity.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle rotten

Send feedback to tektoncd/plumbing.

[pritidesai]

@mattmoor any updates or comments?

/lifecycle frozen