-
Notifications
You must be signed in to change notification settings - Fork 222
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
TEP-0078: Tekton Catalog Support Tiers
As discussed in [TEP-0003: Tekton Catalog Organization](https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md), the support tiers for resources in the Tekton Catalog are *commmunity*, *verified* and *official*, which are differentiated as such: | | Community | Verified | Official | |:----------------------:|:---------:|:------------------:|:------------------:| | Automated Testing | :x: | :heavy_check_mark: | :heavy_check_mark: | | Images scanned for CVE | :x: | :x: | :heavy_check_mark: | | Maintained by Tekton | :x: | :x: | :heavy_check_mark: | Today, all the resources in the Tekton Catalog and Hub should be in the *community* support tier, however this information is not surfaced to users. The aim of this TEP is surface information about the support tiers for resources in the Tekton Catalog, Hub and CLI. In addition, this TEP aims to enable users to filter and search resources from the Tekton Catalog, Hub and CLI for specific support tiers. We propose adding an optional `tekton.dev/tier` annotation, which defaults to *commmunity*, to resources definitions in the Tekton Catalog. Then, the support tier will information will be accessible in the Tekton Hub and CLI as well. Providing this information in a user-friendly way will set us up well to support the *verified* and *official* resources in the Tekton Catalog, Hub and CLI.
- Loading branch information
Showing
2 changed files
with
346 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,345 @@ | ||
| --- | ||
| status: proposed | ||
| title: Tekton Catalog Support Tiers | ||
| creation-date: '2021-08-05' | ||
| last-updated: '2021-08-05' | ||
| authors: | ||
| - '@jerop' | ||
| --- | ||
|
|
||
| # TEP-0078: Tekton Catalog Support Tiers | ||
|
|
||
| <!-- | ||
| **Note:** When your TEP is complete, all of these comment blocks should be removed. | ||
| To get started with this template: | ||
| - [ ] **Fill out this file as best you can.** | ||
| At minimum, you should fill in the "Summary", and "Motivation" sections. | ||
| These should be easy if you've preflighted the idea of the TEP with the | ||
| appropriate Working Group. | ||
| - [ ] **Create a PR for this TEP.** | ||
| Assign it to people in the SIG that are sponsoring this process. | ||
| - [ ] **Merge early and iterate.** | ||
| Avoid getting hung up on specific details and instead aim to get the goals of | ||
| the TEP clarified and merged quickly. The best way to do this is to just | ||
| start with the high-level sections and fill out details incrementally in | ||
| subsequent PRs. | ||
| Just because a TEP is merged does not mean it is complete or approved. Any TEP | ||
| marked as a `proposed` is a working document and subject to change. You can | ||
| denote sections that are under active debate as follows: | ||
| ``` | ||
| <<[UNRESOLVED optional short context or usernames ]>> | ||
| Stuff that is being argued. | ||
| <<[/UNRESOLVED]>> | ||
| ``` | ||
| When editing TEPS, aim for tightly-scoped, single-topic PRs to keep discussions | ||
| focused. If you disagree with what is already in a document, open a new PR | ||
| with suggested changes. | ||
| If there are new details that belong in the TEP, edit the TEP. Once a | ||
| feature has become "implemented", major changes should get new TEPs. | ||
| The canonical place for the latest set of instructions (and the likely source | ||
| of this file) is [here](/teps/NNNN-TEP-template/README.md). | ||
| --> | ||
|
|
||
| <!-- | ||
| This is the title of your TEP. Keep it short, simple, and descriptive. A good | ||
| title can help communicate what the TEP is and should be considered as part of | ||
| any review. | ||
| --> | ||
|
|
||
| <!-- | ||
| A table of contents is helpful for quickly jumping to sections of a TEP and for | ||
| highlighting any additional information provided beyond the standard TEP | ||
| template. | ||
| Ensure the TOC is wrapped with | ||
| <code><!-- toc --&rt;<!-- /toc --&rt;</code> | ||
| tags, and then generate with `hack/update-toc.sh`. | ||
| --> | ||
|
|
||
| <!-- toc --> | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals](#non-goals) | ||
| - [Use Cases](#use-cases) | ||
| - [Requirements](#requirements) | ||
| - [Proposal](#proposal) | ||
| - [Tekton Catalog](#tekton-catalog) | ||
| - [Tekton Hub](#tekton-hub) | ||
| - [Tekton CLI](#tekton-cli) | ||
| - [Design Evaluation](#design-evaluation) | ||
| - [Migration Strategy](#migration-strategy) | ||
| - [Alternatives](#alternatives) | ||
| - [References](#references) | ||
| <!-- /toc --> | ||
|
|
||
| ## Summary | ||
|
|
||
| <!-- | ||
| This section is incredibly important for producing high quality user-focused | ||
| documentation such as release notes or a development roadmap. It should be | ||
| possible to collect this information before implementation begins in order to | ||
| avoid requiring implementors to split their attention between writing release | ||
| notes and implementing the feature itself. | ||
| A good summary is probably at least a paragraph in length. | ||
| Both in this section and below, follow the guidelines of the [documentation | ||
| style guide]. In particular, wrap lines to a reasonable length, to make it | ||
| easier for reviewers to cite specific portions, and to minimize diff churn on | ||
| updates. | ||
| [documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md | ||
| --> | ||
|
|
||
| The aim of this TEP is surface information about the support tiers - *commmunity*, *verified*, *official* - for | ||
| resources in the Tekton Catalog, Hub and CLI. In addition, this TEP aims to enable users to filter and search resources | ||
| from the Tekton Catalog, Hub and CLI for specific support tiers. We propose adding an optional `tekton.dev/tier` | ||
| annotation, which defaults to *commmunity*, to resources definitions in the Tekton Catalog. Then, the support tier will | ||
| information will be accessible in the Tekton Hub and CLI as well. | ||
|
|
||
| ## Motivation | ||
|
|
||
| <!-- | ||
| This section is for explicitly listing the motivation, goals and non-goals of | ||
| this TEP. Describe why the change is important and the benefits to users. The | ||
| motivation section can optionally provide links to [experience reports][] to | ||
| demonstrate the interest in a TEP within the wider Tekton community. | ||
| [experience reports]: https://github.com/golang/go/wiki/ExperienceReports | ||
| --> | ||
|
|
||
| As discussed in [TEP-0003: Tekton Catalog Organization](https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md), | ||
| the support tiers for resources in the Tekton Catalog are *commmunity*, *verified* and *official*, which are | ||
| differentiated as such: | ||
|
|
||
| | | Community | Verified | Official | | ||
| |:----------------------:|:---------:|:------------------:|:------------------:| | ||
| | Automated Testing | :x: | :heavy_check_mark: | :heavy_check_mark: | | ||
| | Images scanned for CVE | :x: | :x: | :heavy_check_mark: | | ||
| | Maintained by Tekton | :x: | :x: | :heavy_check_mark: | | ||
|
|
||
| Today, all the resources in the Tekton Catalog and Hub should be in the *community* support tier, however this | ||
| information is not surfaced to users. | ||
|
|
||
| The aim of this TEP is surface information about the support tiers for resources in the Tekton Catalog, Hub and CLI. | ||
| In addition, this TEP aims to enable users to filter and search resources from the Tekton Catalog, Hub and CLI for | ||
| specific support tiers. Providing this information in a user-friendly way will set us up well to support the *verified* | ||
| and *official* resources in the Tekton Catalog, Hub and CLI. | ||
|
|
||
| ### Goals | ||
|
|
||
| <!-- | ||
| List the specific goals of the TEP. What is it trying to achieve? How will we | ||
| know that this has succeeded? | ||
| --> | ||
|
|
||
| - Define how to add support tiers into resource specifications in the Tekton Catalog. | ||
| - Define how to show the support tiers to users and how to enable users to search and filter based on support tiers. | ||
|
|
||
| ### Non-Goals | ||
|
|
||
| <!-- | ||
| What is out of scope for this TEP? Listing non-goals helps to focus discussion | ||
| and make progress. | ||
| --> | ||
|
|
||
| - Establish *verified* and *official* support tiers for resources in the Tekton Catalog - will be done in future work. | ||
| - Define criteria to promote or demote the support tiers of resources. | ||
|
|
||
| ### Use Cases | ||
|
|
||
| <!-- | ||
| Describe the concrete improvement specific groups of users will see if the | ||
| Motivations in this doc result in a fix or feature. | ||
| Consider both the user's role (are they a Task author? Catalog Task user? | ||
| Cluster Admin? etc...) and experience (what workflows or actions are enhanced | ||
| if this problem is solved?). | ||
| --> | ||
|
|
||
| - Indicate the support tier of resources in the Tekton Catalog and Hub. | ||
| - Discover the support tier of a specific resource in the Tekton Catalog and Hub. | ||
| - Filter resources in the Tekton Hub based on support tiers. | ||
| - Search resources with the Tekton CLI for resources in certain support tiers. | ||
|
|
||
| ## Requirements | ||
|
|
||
| <!-- | ||
| Describe constraints on the solution that must be met. Examples might include | ||
| performance characteristics that must be met, specific edge cases that must | ||
| be handled, or user scenarios that will be affected and must be accomodated. | ||
| --> | ||
|
|
||
| - Contributor should be able to indicate the support tier of a resource when authoring it. | ||
| - Support tier information in the resource yaml in the Catalog should be optional. | ||
| - Definitions and expectations of support tiers should be documented in the Tekton Catalog. | ||
| - Available support tiers should be shown on the Tekton Hub, and users should be able to filter resources based on them. | ||
| - Users should be able to search for resources of specific support tiers using the Tekton CLI. | ||
|
|
||
| ## Proposal | ||
|
|
||
| <!-- | ||
| This is where we get down to the specifics of what the proposal actually is. | ||
| This should have enough detail that reviewers can understand exactly what | ||
| you're proposing, but should not include things like API designs or | ||
| implementation. The "Design Details" section below is for the real | ||
| nitty-gritty. | ||
| --> | ||
|
|
||
| ### Tekton Catalog | ||
|
|
||
| Add a new `tekton.dev/tier` annotation to the resource yaml file with the relevant support tier, for example: | ||
|
|
||
| ```yaml | ||
| annotations: | ||
| tekton.dev/pipelines.minVersion: "0.17.0" | ||
| tekton.dev/tags: image-build | ||
| tekton.dev/tier: verified | ||
| ``` | ||
| The `tekton.dev/tier` annotation should be optional. If the annotation is not specified, `community` support tier is | ||
| meant by default, as this support tier is actually default one in the Tekton Catalog. This would also provide backward | ||
| compatibility to the old versions of the resources in the Tekton Catalog. | ||
|
|
||
| Information about support tier also should be added to the resource's `README.md` as separate `Support Tier` section to | ||
| establish quality expectations for the resource. The criteria to change the support tiers of resources (automated | ||
| testing, image scanning, ownership) should be documented in Tekton Catalog documentation for transparency to users and | ||
| contributors. | ||
|
|
||
| ### Tekton Hub | ||
|
|
||
| Implement logic to fetch, process, store and update information about a resource's tier. The approach is similar to | ||
| what is available for `tags` and `platforms`. If there is no information about tier in the resource definition, | ||
| then the default `community` tier should be used. | ||
|
|
||
| Hub UI should have `tier` filter and show resources based on it. | ||
|
|
||
| CLI code should be extended: | ||
| - to have `--tier` search parameter to filter resources based on support tiers | ||
| - to have support tier information in the resource information view | ||
| - to have support tier informatiion in the resource table | ||
|
|
||
| ### Tekton CLI | ||
|
|
||
| After implementation in Tekton Hub, functionality can be extended to the tkn cli. Support tier information should be | ||
| shown via `tkn hub search --tier` and `tkn hub info` commands. | ||
|
|
||
| ```yaml | ||
| $ tkn hub info task git-clone | ||
| 📦 Name: git-clone | ||
| 🗂 Display Name: git clone | ||
| 📌 Version: 0.4 (Latest) | ||
| 🏆 Tier: Community | ||
| 📖 Description: These Tasks are Git tasks to work with repositories | ||
| used by other tasks in your Pipeline. The git-clone Task will clone a | ||
| repo from the provided url into the output Workspace. By default the | ||
| repo will be cloned into the root of your Workspace. You can clone | ||
| into a subdirectory by setting this Task's subdirectory param. This | ||
| Task also supports sparse checkouts. To perform a sparse checkout, | ||
| pass a list of comma separated directory patterns to this Task's | ||
| sparseCheckoutDirectories param. | ||
| 🗒 Minimum Pipeline Version: 0.21.0 | ||
| ⭐ ️Rating: 3.7 | ||
| 🏷 Tags | ||
| ∙ git | ||
| ⚒ Install Command: | ||
| tkn hub install task git-clone | ||
| ``` | ||
|
|
||
| ```shell | ||
| $ bin/tkn hub search --tier community | ||
| NAME KIND CATALOG TIER DESCRIPTION TAGS | ||
| git-clone (0.4) Task Tekton Community The git-clone Task will clone... git | ||
| ``` | ||
|
|
||
| ## Design Evaluation | ||
| <!-- | ||
| How does this proposal affect the reusability, simplicity, flexibility | ||
| and conformance of Tekton, as described in [design principles](https://github.com/tektoncd/community/blob/master/design-principles.md) | ||
| --> | ||
|
|
||
| - _**Simplicity**_: providing only three support tiers, and making it optional with a default value, provides a simple | ||
| mechanism to define support tiers for resources using annotations to surface information is consistent with other | ||
| available information, e.g. `tekton.dev/tags` and `tekton.dev/platforms`. | ||
|
|
||
| - _**Reusability**_: annotations are used to define information about resources, this proposal reuses annotations for | ||
| the same purpose. | ||
|
|
||
| - _**Flexibility**_: annotations can be easily extended to support additional support tiers. | ||
|
|
||
| ## Migration Strategy | ||
|
|
||
| <!-- | ||
| Use this section to detail whether this feature needs an upgrade or | ||
| migration strategy. This is especially useful when we modify a | ||
| behavior or add a feature that may replace and deprecate a current one. | ||
| --> | ||
|
|
||
| Because the support tier annotation is optional, and defaults to *community* tier, then this proposal would provide | ||
| backward compatibility to old versions of resources in the Tekton Catalog and Hub. Searching and filtering for the old | ||
| resources based on tiers, which don't actually have tiers specified, will still return successfully with the *community* | ||
| tier. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| <!-- | ||
| What other approaches did you consider and why did you rule them out? These do | ||
| not need to be as detailed as the proposal, but should include enough | ||
| information to express the idea and why it was not acceptable. | ||
| --> | ||
|
|
||
| Add new `tekton.dev/community`, `tekton.dev/verified`, and `tekton.dev/official` annotations to the resource yaml file | ||
| with "true" or "false" to indicate the support tier, for example: | ||
|
|
||
| ```yaml | ||
| annotations: | ||
| tekton.dev/pipelines.minVersion: "0.17.0" | ||
| tekton.dev/tags: git | ||
| tekton.dev/community: true | ||
| ``` | ||
|
|
||
| ```yaml | ||
| annotations: | ||
| tekton.dev/pipelines.minVersion: "0.17.0" | ||
| tekton.dev/tags: git | ||
| tekton.dev/verified: true | ||
| ``` | ||
|
|
||
| ```yaml | ||
| annotations: | ||
| tekton.dev/pipelines.minVersion: "0.17.0" | ||
| tekton.dev/tags: git | ||
| tekton.dev/official: true | ||
| ``` | ||
|
|
||
| However, we need to add more validation to ensure that any combinations of the annotations are compatible. Moreover, for | ||
| every new tier, we will need to add a new annotation instead of extending the acceptable fields. | ||
|
|
||
| ## References | ||
|
|
||
| <!-- | ||
| Use this section to add links to GitHub issues, other TEPs, design docs in Tekton | ||
| shared drive, examples, etc. This is useful to refer back to any other related links | ||
| to get more details. | ||
| --> | ||
| - [TEP-0003: Tekton Catalog Organization](https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md) | ||
| - [tektoncd/catalog issue#5: Decide on support levels](https://github.com/tektoncd/catalog/issues/5) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters