Additionnal Tekton Bundle reserved annotations for extra information

[vdemeester]

trafficstars

Tekton bundles are oci images. And oci image, according to its spec, can have annotations.

Today, the tekton bundle spec defines a few, dev.tekton.image.name, dev.tekton.image.kind and dev.tekton.image.apiVersion. Those are set on the layers "only".

This issue proposes to define more annotations (optional) that could be set on the manifest and/or layers for the following:

• sources : where is the source of this "layer" (aka resource)
• documentations: where to find documentation for this resource(s)
• build informations : how was it build, by which tool, on which service, …
  • SBOM link
  • Attestastion link (in-toto, …)

The idea is to make a bundle more self-describe. One could look at a bundle and get informations about it (how it was build, …). In a Secure Supply Chain world, it could be helpful as well.

[vdemeester]

Note: we could reuse some org-opencontainers.image annotations (for source or documentation for example)

[arewm]

+1 to this feature. It is currently very hard to identify the sources for tekton bundles that are in a repository.

It may even be possible to fill out some other annotations based on the content of the bundle, i.e.

• org.opencontainers.image.version
• org.opencontainers.image.title
• org.opencontainers.image.description
• org.opencontainers.image.documentation

Is it possible for a single bundle to have content from more than one pipeline and/or task? If so, these annotations may be hard to auto-detect, but they could still be provided on invocation.

[ralphbean]

Yes, I think that is possible (for a single bundle to have content from more than one pipeline and/or task) -- but, I see Vincent's proposal is to add these annotations per layer. I don't know if layers can include more than one resource.

[ralphbean]

Looks like tkn bundle push already supports a --annotate option. A bundle creator can annotate like this:

❯ skopeo inspect --raw docker://quay.io/rbean/task-fbc-validation:0.1 | jq .annotations                                                                                         
{
  "dev.tekton.docs.troubleshooting": "https://github.com/konflux-ci/build-definitions/tree/9541dda01c47940db6a2d9f969cb5804a5b529f0/task/fbc-validation/0.1/TROUBLESHOOTING.md",
  "dev.tekton.docs.usage": "https://github.com/konflux-ci/build-definitions/tree/9541dda01c47940db6a2d9f969cb5804a5b529f0/task/fbc-validation/0.1/USAGE.md",
  "org.opencontainers.image.documentation": "https://github.com/konflux-ci/build-definitions/tree/9541dda01c47940db6a2d9f969cb5804a5b529f0/task/fbc-validation/0.1/README.md",
  "org.opencontainers.image.revision": "9541dda01c47940db6a2d9f969cb5804a5b529f0",
  "org.opencontainers.image.source": "https://github.com/konflux-ci/build-definitions",
  "org.opencontainers.image.url": "https://github.com/konflux-ci/build-definitions/tree/9541dda01c47940db6a2d9f969cb5804a5b529f0/task/fbc-validation/0.1/"
}

[vdemeester]

I don't know if layers can include more than one resource.

Today, they cannot if I remember correctly.

[arewm]

In the above PR that @ralphbean linked, annotations were added to link USAGE.md and TROUBLESHOOTING.md files using the keys dev.tekton.docs.usage and dev.tekton.docs.troubleshooting, respectively.

Unlike the dev.tekton.image.* annotations, however, these are not defined in any specification. Would it be possible to add these annotations to the spec? If so, should the annotations be of the form dev.tekton.image.usage and dev.tekton.image.troubleshooting? Or does this pattern not make sense for the bundle because this content wouldn't be stored in the referenced task/pipeline?

For the README.md, the org.opencontainers.image.documentation annotation was used but the OCI-spec does not have anything that would suffice for a readme or troubleshooting-typed file.