From f03f3555e685c04d2acf50eba439a55861c70c29 Mon Sep 17 00:00:00 2001 From: Quan Zhang Date: Mon, 17 Oct 2022 11:35:12 -0400 Subject: [PATCH] [TEP-0079] Ownership and Maintenance This commit updates the "Ownership and Maintenance" section of TEP-0079, reflecting recent changes in: - [TEP-0110][tep-0110]: Decouple Tekton Catalog Organization from Resource Reference - [TEP-0115][tep-0115]: Tekton Catalog Git-Based Versioning - https://github.com/tektoncd/hub/issues/667: Migration from Tekton Hub to Artifact Hub This commit also renames the "official" support tier to "verified" to avoid naming confusion with the [official status][official-status] in Artifact Hub /kind tep [tep-0079]: https://github.com/tektoncd/community/blob/main/teps/0079-tekton-catalog-support-tiers.md [tep-0110]: https://github.com/tektoncd/community/blob/main/teps/0110-decouple-catalog-organization-and-reference.md [tep-0115]: https://github.com/tektoncd/community/blob/main/teps/0115-tekton-catalog-git-based-versioning.md [official-status]: https://artifacthub.io/docs/topics/repositories/#official-status --- teps/0079-tekton-catalog-support-tiers.md | 740 ++++++++++------------ teps/README.md | 2 +- 2 files changed, 342 insertions(+), 400 deletions(-) diff --git a/teps/0079-tekton-catalog-support-tiers.md b/teps/0079-tekton-catalog-support-tiers.md index 72bbeaaa1..592673dac 100644 --- a/teps/0079-tekton-catalog-support-tiers.md +++ b/teps/0079-tekton-catalog-support-tiers.md @@ -2,68 +2,73 @@ status: proposed title: Tekton Catalog Support Tiers creation-date: '2021-08-09' -last-updated: '2022-01-25' +last-updated: '2022-10-17' authors: - '@bobcatfish' - '@jerop' - '@vdemeester' - '@vinamra28' - '@chmouel' +- '@QuanZhang-William' see-also: - TEP-0003 - TEP-0060 - TEP-0091 +- TEP-0110 +- TEP-0115 --- # TEP-0079: Tekton Catalog Support Tiers -- [Summary](#summary) -- [Motivation](#motivation) - - [Critical User Journeys](#critical-user-journeys) - - [User](#user) - - [Casual Contributor](#casual-contributor) - - [Dedicated Contributor](#dedicated-contributor) - - [Tekton Maintainer](#tekton-maintainer) - - [Goals](#goals) - - [Ownership and Maintenance](#ownership-and-maintenance) - - [Automated Testing and Dogfooding](#automated-testing-and-dogfooding) - - [Image Scanning for Common Vulnerabilities and Exposures (CVEs)](#image-scanning-for-common-vulnerabilities-and-exposures-cves) - - [Verified Remote Resources](#verified-remote-resources) -- [Definitions](#definitions) -- [Proposal](#proposal) - - [Ownership and Maintenance](#ownership-and-maintenance-1) - - [Tekton Community Catalog](#tekton-community-catalog) - - [Requirements](#requirements) - - [Tekton Official Catalog](#tekton-official-catalog) - - [Requirements](#requirements-1) - - [Promotion from Community Catalog to Official Catalog](#promotion-from-community-catalog-to-official-catalog) - - [Community and Official Catalogs in the Tekton Hub](#community-and-official-catalogs-in-the-tekton-hub) - - [Community and Official Catalogs in the Tekton CLI](#community-and-official-catalogs-in-the-tekton-cli) - - [Community and Official Catalogs in the Cluster](#community-and-official-catalogs-in-the-cluster) - - [Community and Official Catalogs in Tekton Bundles](#community-and-official-catalogs-in-tekton-bundles) - - [Community and Official Catalogs in Remote Resolution](#community-and-official-catalogs-in-remote-resolution) - - [Responsibilities](#responsibilities) - - [Resource Ownership](#resource-ownership) - - [Catalog Ownership](#catalog-ownership) - - [Design Evaluation](#design-evaluation) - - [Alternatives](#alternatives) - - [1. One Repository and Use Annotations](#1-one-repository-and-use-annotations) - - [Design Evaluation](#design-evaluation-1) - - [2. One Repository and Use OWNERS](#2-one-repository-and-use-owners) - - [Design Evaluation](#design-evaluation-2) - - [3. Verified Support Tier](#3-verified-support-tier) - - [Design Evaluation](#design-evaluation-3) - - [Automated Testing and Dogfooding](#automated-testing-and-dogfooding-1) - - [Image Scanning for Common Vulnerabilities and Exposures (CVEs)](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1) - - [Verified Remote Resources](#verified-remote-resources-1) -- [References](#references) + - [Summary](#summary) + - [Motivation](#motivation) + - [Critical User Journeys](#critical-user-journeys) + - [User](#user) + - [Casual Contributor](#casual-contributor) + - [Dedicated Contributor](#dedicated-contributor) + - [Tekton Maintainer](#tekton-maintainer) + - [Goals](#goals) + - [Ownership and Maintenance](#ownership-and-maintenance) + - [Automated Testing and Dogfooding](#automated-testing-and-dogfooding) + - [Image Scanning for Common Vulnerabilities and Exposures (CVEs)](#image-scanning-for-common-vulnerabilities-and-exposures-cves) + - [Verified Remote Resources](#verified-remote-resources) + - [Definitions](#definitions) + - [Proposal](#proposal) + - [Ownership and Maintenance](#ownership-and-maintenance-1) + - [Community Catalogs](#community-catalogs) + - [Requirements](#requirements) + - [Verified Catalogs](#verified-catalogs) + - [Requirements](#requirements-1) + - [Additions to Verified Catalogs](#additions-to-verified-catalogs) + - [Hub](#hub) + - [CLI](#cli) + - [Cluster](#cluster) + - [Bundles](#bundles) + - [Remote Resolution](#remote-resolution) + - [Bundles Resolver](#bundles-resolver) + - [Git Resolver](#git-resolver) + - [Hub Resolver](#hub-resolver) + - [Responsibilities](#responsibilities) + - [Resource Ownership](#resource-ownership) + - [Catalog Ownership](#catalog-ownership) + - [Design Evaluation](#design-evaluation) + - [Alternatives](#alternatives) + - [1. Verified Support Tier](#1-verified-support-tier) + - [Design Evaluation](#design-evaluation-1) + - [2. Community Catalogs in tektoncd-catalog GitHub Org](#2-community-catalogs-in-tektoncd-catalog-github-org) + - [Design Evaluation](#design-evaluation-2) + - [Automated Testing and Dogfooding](#automated-testing-and-dogfooding-1) + - [Image Scanning for Common Vulnerabilities and Exposures (CVEs)](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1) + - [Verified Remote Resources](#verified-remote-resources-1) + - [References](#references) ## Summary -The aim of this TEP is to establish support tiers for resources in the Tekton Catalog to ensure users get high quality -resources that they can rely on while making it easy for contributors to submit resources to the Tekton Catalog. +The aim of this TEP is to establish support tiers for resources in the Artifact Hub to ensure users get high quality +resources that they can rely on while making it easy for Contributors to share resources in the Artifact Hub. This TEP +builds on prior work in [TEP-0003][tep-0003], [TEP-0110][tep-0110]. ## Motivation @@ -71,58 +76,56 @@ resources that they can rely on while making it easy for contributors to submit #### User -Story: As a user of *Tekton Pipelines*, I want to be able to use `Tasks` and `Pipelines` from the *Tekton Hub*. -I want to know that I can rely on them to work as advertised. +Story: As a user of Tekton Pipelines, I want to be able to use `Tasks` and `Pipelines` from the Artifact Hub. I want to +know that I can rely on them to work as advertised. -Anti-story: As a user of Tekton Pipelines, I try to use a Task from the Tekton Hub but it turns out that it doesn't -actually work, e.g. the Result that the Task is supposed to produce is invalid and/or the Steps fail for unexpected -reasons. +Anti-story: As a user of Tekton Pipelines, I try to use a `Task` from the Artifact Hub, but it turns out that it doesn't +work, e.g. the `Result` that the `Task` is supposed to produce is invalid or the `Steps` fail for unexpected reasons. #### Casual Contributor -As a casual contributor to the Tekton Catalog, I have created a Task that works for me, and I'd like to submit it to the -Catalog, but I don't want to do much more work than that. I'm willing to deal with bugs reported and pull requests +As a casual Contributor to the Tekton Catalog, I have created a `Task` that works for me, and I'd like to submit it to +the Catalog, but I don't want to do much more work than that. I'm willing to deal with bugs reported and pull requests opened for it, but I don't want to have to bother submitting tests with it. #### Dedicated Contributor -As a dedicated contributor to the Tekton Catalog, I have created a Task and I want to make sure it continues to work -over time. I'm willing to put in the time to create a test but I want to understand exactly how to create that test -without having to track down a maintainer to help me. Moreover, I want to sign the Task to mark it as trusted. +As a dedicated Contributor to the Tekton Catalog, I have created a `Task` and I want to make sure it continues to work +over time. I'm willing to put in the time to create a test, but I want to understand exactly how to create that test +without having to track down a Maintainer to help me. Moreover, I want to sign the `Task` to mark it as trusted. #### Tekton Maintainer -As a maintainer of a Tekton project, I have a Task which I would like to be an official part of Tekton and I would -like other Tekton maintainers to help maintain over time. In addition to automated testing for the Task, I want the -image used in the Task to be regularly scanned for common vulnerabilities and exposures so that we ensure *official* -Tasks are secure. I also want this official Task to demonstrate best and secure practices that users can confidently -imitate when authoring their own Tasks. Even more, I want to dogfood features and components in Tekton to gather +As a Maintainer of a Tekton project, I have a `Task` which I would like to be an verified part of Tekton and I would +like other Tekton Maintainers to help maintain over time. In addition to automated testing for the `Task`, I want the +image used in the `Task` to be regularly scanned for common vulnerabilities and exposures so that we ensure verified +`Tasks` are secure. I also want this verified `Task` to demonstrate best and secure practices that users can use as a +sample when authoring their own `Tasks`. Even more, I want to dogfood features and components in Tekton to gather feedback and iterate quickly. ### Goals #### Ownership and Maintenance -Every resource in the *Tekton Catalog* needs to have Owners to maintain them. The Ownership needs to be distributed among -community members and Tekton maintainers to ensure that the workload is manageable and sustainable. +Every resource in the [`tektoncd-catalog`](https://github.com/tektoncd-catalog) GitHub organization needs to have Owners to maintain them. The Ownership needs to be distributed among community members and Tekton Maintainers to ensure that the workload is manageable and sustainable. #### Automated Testing and Dogfooding Users need to be able to check that shared Tekton resources work as expected so that they can rely on them. -Contributors need to know how to provide tests to ensure the resources they are contributing to the Catalog work. -In addition, they need an infrastructure that they can use to run those tests against. +Contributors need to know how to provide tests to ensure their resources in Catalogs work as expected. In addition, +they need to know how to set up the infrastructure that they can use to run those tests against. Maintainers need to dogfood Tekton to gather feedback and iterate quickly, so the test infrastructure should use Tekton. #### Image Scanning for Common Vulnerabilities and Exposures (CVEs) Shared Tekton resources refer to images from a lot of places. We need to regularly scan these images for common -vulnerabilities and exposures, and surface any issues to maintainers and contributors. +vulnerabilities and exposures, and surface any issues to Maintainers and Contributors. #### Verified Remote Resources -Contributors need to sign resources they own in the Catalog and maintainers need to sign resources that are officially +Contributors need to sign resources they own in the Catalog and Maintainers need to sign resources that are officially provided and maintained by Tekton. They need to sign the resources so that they may be trusted, depending on users' requirements, and provenance attestations can be made to meet software supply chain security goals. @@ -131,194 +134,110 @@ surfacing the verification information and building a corpus of verified resourc ## Definitions -The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, -“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and -“OPTIONAL” are to be interpreted as described in [RFC 2119][rfc2119]. +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, +“NOT RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in [RFC 2119][rfc2119]. Terms used in this TEP are defined as follows: -* **Catalog**: A repository that complies with the organization contract - defined in [TEP-0003: Tekton Catalog Organization][tep-0003-org]. + +* **Catalog**: A repository that complies with the organization contracts defined in [TEP-0003][tep-0003-org] or +[TEP-0115][tep-0115]. The git-based versioning defined in [TEP-0115][tep-0115] is preferred. + * **Resource**: Item shared in a Tekton Catalog e.g. `Task` or `Pipeline`. -* **Tekton Catalog Maintainers**: The core group of OWNERS who can approve - changes in Tekton Catalogs. They are defined in [OWNERS][catalog-owners] - file in the existing Catalog at `tektoncd/catalog`. + +* **Tekton Catalog Maintainers**: The core group of OWNERS who can approve changes in verified Tekton Catalogs. +Today, they are defined in [OWNERS][catalog-owners] file in the existing Catalog at `tektoncd/catalog`. The current maintainers of `tektoncd/catalog` should become the maintainers in the `tektoncd-catalog` github org. ## Proposal ### Ownership and Maintenance -As previously discussed in [TEP-0003][tep-0003-upstream], we propose -creating two support tiers, `Community` and `Official`, through -separate Tekton Catalogs. +As previously discussed in [TEP-0115][tep-0115-org] and [migration](https://github.com/tektoncd/hub/issues/667) to the [Artifact Hub][hub], +the Tekton Community has decided to migrate to the decentralized model for Catalogs and use the Artifact Hub to surface Tekton Catalogs. +Given the above changes, we propose creating two support tiers: `Community` and `Verified`. Community Catalogs make it easy for Contributors to share resources, while the Verified Catalogs provide high quality resources that users can rely on. Community and Verified Catalogs will be published in the [Hub][hub]. -The Community Catalog makes it easy for contributors to share resources, -while the Official Catalog provides a corpus of high quality resources -that users can rely on. +#### Community Catalogs -Both the Community and Official Catalogs will be: -* Owned by the [Tekton Catalog Maintainers][catalog-owners]. - The resources in the Community Catalog are owned by contributors, - but the Catalog itself is owned by the Tekton Catalog Maintainers. -* Published in the [Tekton Hub][hub]. -* Share infrastructure, such as testing and scanning tooling. +To ensure the workload of maintaining shared resources is sustainable, Contributors can share and maintain resources +in their own Community Catalogs. Community Catalogs will provide a low barrier of entry, in the testing and security +requirements, to encourage community contributions. -#### Tekton Community Catalog - -To ensure the workload of maintaining shared resources is sustainable, -contributors can share and maintain resources in the Community Catalog. -The Community Catalog will maintain a low barrier of entry, in the -testing and security requirements, to encourage community contributions. +##### Requirements -The current Tekton Catalog at `tektoncd/catalog` will be reused as the -Community Catalog. +1. The Catalog MUST comply with the contract and versioning defined in [TEP-0003][tep-0003-org] or [TEP-0115][tep-0115]. +We will support the directory-based versioning for backwards compatibility during migration; new Catalogs should use the +git-based versioning defined in TEP-0115. +2. The Catalog MUST define an OWNER file that specifies at least one Maintainer. +3. The Catalog MAY have automated testing (using Tekton or not). If there are any failures, they MAY be resolved. The automated +testing is discussed further [below](#automated-testing-and-dogfooding-1). +4. The Catalog MAY be scanned for common vulnerabilities and exposures. If any issues are discovered, they MAY be +patched or disclosed. Scanning is discussed [below](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1). +5. The Catalog MAY support verification as proposed in [TEP-0091: Verified Remote Resources][tep-0091]. For now, it +MAY be published to a public OCI registry as a [Tekton Bundle][bundle] and signed by the Owners. In the future, it MAY +be updated to support accepted proposal of [TEP-0091: Verified Remote Resources][tep-0091]. Verification is discussed +further [below](#verified-remote-resources-1). +6. The Catalog MAY be well documented with all configuration options described and working examples provided. +7. The Catalog MAY follow and demonstrate best practices e.g. [`Task` authoring recommendations][task-authoring-recs]. +If there are new best practices, the Catalog MAY be updated. +8. The Catalog MAY be updated to the latest version of Tekton and other dependencies. + +#### Verified Catalogs + +To provide a corpus of high quality resources that users can rely on, we propose creating Verified Catalogs with high +maintenance, testing and security standards. + +As described in [TEP-0115][tep-0115], the Verified Catalogs will be in repositories in `tektoncd-catalog` GitHub +organization - https://github.com/tektoncd-catalog. ##### Requirements -1. The resource MUST comply with the contract defined in - [TEP-0003: Tekton Catalog Organization][tep-0003-org]. -2. The resource MUST define an OWNER file in - `/{resource-type}/{resource-name}/OWNERS`, that specifies - at least one maintainer for that specific resource. -3. The resource MAY have automated testing using Tekton for dogfooding. - If there are any failures, they MAY be resolved. The automated - testing is discussed further [below](#automated-testing-and-dogfooding-1). -4. The resource MAY be scanned for common vulnerabilities and exposures. - If any issues are discovered, they MAY be patched or disclosed. - The scanning for CVEs is discussed further - [below](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1). -5. The resource MAY support verification as proposed in - [TEP-0091: Verified Remote Resources][tep-0091]. For now, it MAY be - published to a public OCI registry as a [Tekton Bundle][bundle] and - signed by Tekton. In the future, it MAY be updated to support accepted - proposal of TEP-0091 depending on the direction of - [TEP-0060: Remote Resource Resolution][tep-0060]. - The verification is discussed further [below](#verified-remote-resources-1). -6. The resource MAY be well documented with all configuration options described - and a working example provided. -7. The resource MAY follow and demonstrate best practices, such as the - [`Task` authoring recommendations][task-authoring-recommendations]. - If there are new best practices, the resource MAY be updated. -8. The resource MAY be updated to the latest version of Tekton and other - dependencies. - -#### Tekton Official Catalog - -To provide a corpus of high quality resources that users can rely on, -we propose creating an Official Catalog with high maintenance, testing -and security standards. - -The Official Catalog will be in a new repository named -`tektoncd/catalog-official`. +These are requirements for Verified Catalogs: -##### Requirements +1. The Catalog MUST comply with the contract and versioning defined in [TEP-0115][tep-0115]. +2. The Catalog MUST define an OWNER file listing the Tekton Catalog Maintainers. The ownership responsibilities are +described [below](#responsibilities). +3. The Catalog MUST have automated testing using Tekton for dogfooding. If there are any failures, they MUST be +resolved as soon as possible; the SLO is one week. Automated testing is discussed further +[below](#automated-testing-and-dogfooding-1). +4. The Catalog MUST be scanned for common vulnerabilities and exposures. If any issues are discovered, they MUST be +patched or disclosed as soon as possible; the SLO is one week. Scanning for CVEs is discussed further +[below](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1). +5. The Catalog MUST support verification as proposed in [TEP-0091: Verified Remote Resources][tep-0091]. For now, +it MUST be published to a public OCI registry as a [Tekton Bundle][bundle] and signed by Tekton. In the future, it MUST +be updated to support accepted proposal of [TEP-0091: Verified Remote Resources][tep-0091]. Verification is discussed +further [below](#verified-remote-resources-1). +6. The Catalog MUST be well documented with all configuration options described and working examples provided. +7. The Catalog MUST follow and demonstrate best practices e.g. [`Task` authoring recommendations][task-authoring-recs]. +If there are new best practices, the Catalog MUST be updated if applicable. +8. The Catalog SHOULD be updated to the latest version of Tekton and other dependencies. -These are requirement that a resource must meet to be added to the -Official Catalog: - -1. The resource MUST comply with the contract defined in - [TEP-0003: Tekton Catalog Organization][tep-0003-org]. -2. The resource MUST not define an OWNER file, given that it is owned - and maintained by Tekton Catalog Maintainers who are defined at the - root of the Catalog. The ownership responsibilities are described - [below](#responsibilities). -3. The resource MUST have automated testing using Tekton for dogfooding. - If there are any failures, they MUST be resolved as soon as possible; - the SLO is one week. The automated testing is discussed further - [below](#automated-testing-and-dogfooding-1). -4. The resource MUST be scanned for common vulnerabilities and exposures. - If any issues are discovered, they MUST be patched or disclosed as soon as - possible; the SLO is one week. The scanning for CVEs is discussed further - [below](#image-scanning-for-common-vulnerabilities-and-exposures-cves-1). -5. The resource MUST support verification as proposed in - [TEP-0091: Verified Remote Resources][tep-0091]. For now, it MUST be - published to a public OCI registry as a [Tekton Bundle][bundle] and - signed by Tekton. In the future, it MUST be updated to support accepted - proposal of TEP-0091 depending on the direction of - [TEP-0060: Remote Resource Resolution][tep-0060]. - The verification is discussed further [below](#verified-remote-resources-1). -6. The resource MUST be well documented with all configuration options described - and a working example provided. -7. The resource MUST follow and demonstrate best practices, such as the - [`Task` authoring recommendations][task-authoring-recommendations]. - If there are new best practices, the resource MUST be updated if needed. -8. The resource SHOULD be updated to the latest version of Tekton and other - dependencies. - -#### Promotion from Community Catalog to Official Catalog - -Promoting a resource from the Community Catalog to the Official Catalog -should be an exception, not the norm. The set of resources in the -Official Catalog should relatively small so that it's sustainable for the -Tekton Catalog Owners to maintain. - -A resource in the Community Catalog may get promoted to the Official Catalog -if: -* _Quality_: It meets the [requirements of the Official Catalog](#requirements-1). -* _Bandwidth_: The [Tekton Catalog Maintainers][catalog-owners] approve its - promotion based on its usefulness to the community and existing bandwidth - to maintain the resource. - -If a resource is promoted to the Official Catalog: -* Its minor version MUST be bumped during the migration. - For example, if we want to bump *git-clone* `Task` whose latest version - is 0.5 in the Community Catalog, we would add version 0.6 to the Official - Catalog. This ensures that there won't be multiple resources with the same - name and version in the cluster. -* It can be [deprecated][deprecation] in the Community Catalog. A resource - is deprecated through the `tekton.dev/deprecated: "true"` annotation. - -We will provide tooling, through [catlin][catlin], to make it easier for -Tekton Catalog Maintainers to migrate resources from the Community Catalog -to the Official Catalog. - -#### Community and Official Catalogs in the Tekton Hub - -Users rely on the [Tekton Hub][hub] to discover shared resources. -The Tekton Hub supports publishing resources from multiple Catalogs. -As described in [TEP-0003][tep-0003-hub], the goal was to set it up to -support providing support tiers for shared resources. It also allows -users and organizations to create their own Catalogs and share them in -the Tekton Hub, as long as they comply with the Catalog contract. The -Tekton Hub can indicate the source Catalog of each resource, such as -through a badge or tag. - -To add the Official Catalog, we only have to modify the Catalogs -[configuration][hub-config] in the Hub, as such: +##### Additions to Verified Catalogs -```yaml -catalogs: - - # community catalog - - name: tekton-community - org: tektoncd - type: community - provider: github - url: https://github.com/tektoncd/catalog - revision: main - - # official catalog - - name: tekton-official - org: tektoncd - type: official - provider: github - url: https://github.com/tektoncd/catalog-official - revision: main -``` +Adding a new Verified Catalog or adding a resource into an Verified Catalog should be an exception, not the norm. The +set of Verified Catalogs and their resources should be relatively small so that it is sustainable to maintain them. + +A new Verified Catalog may be created, or a new resource added to it if: +* _Quality_: It meets the [requirements of the Verified Catalog](#requirements-1). +* _Bandwidth_: The [Tekton Catalog Maintainers][catalog-owners] approve its addition based on its usefulness to the +community and existing bandwidth to maintain the resource. -This provides extensibility to the support tiers: we can add additional -Catalogs for other support tiers as needed in the future. +#### Hub -#### Community and Official Catalogs in the Tekton CLI +Users rely on the [Artifact Hub][hub] to discover shared resources. The Artifact Hub supports publishing resources from +multiple Catalogs. Users and organizations can create their own Catalogs and share them in the Artifact Hub ([guide](https://artifacthub.io/docs/topics/repositories/tekton-tasks/)), as long as they comply with the Catalog contract. -Today, users can use the CLI to install resources from Catalogs by -passing in the Catalog name to the `--from` argument as shown in the -examples below. This will add a label to the resource indicating the -source Catalog: `hub.tekton.dev/catalog=`. +To distinguish the Catalogs support tier in the Hub, the [Tekton Catalog Maintainers][catalog-owners] have reserved the `tektoncd` org in the Artifact Hub. **Only** the catalogs published under the `tektoncd` org are with the `Verified` support tier. The community contributors are able to create their own Artifact Hub organization to publish Catalogs, the support tier of such Catalogs are `Community`. + +The [Tekton Catalog Maintainers][catalog-owners] also reserved the `tektoncd-legacy` org in the Hub, surfacing the current [centralized Catalog repo](https://github.com/tektoncd/catalog) following the legacy directory-based versioning. We will stop surfacing catalogs from the centralized Catalog repo in the Artifact Hub after the 9-month migration period as discussed in [TEP-0115][tep-0115-migration]. + +#### CLI + +Today, users can use the CLI to install resources from Catalogs by passing in the Catalog name to the `--from` argument +as shown in the examples below. This adds a label to the resource indicating the source Catalog: ```shell # Community Catalog -$ tkn hub install task golang-lint --version 0.3 --from tekton-community +$ tkn hub install task golang-lint --version 0.3 --from tekton Task golang-lint(0.3) installed in default namespace @@ -327,139 +246,212 @@ $ kubectl describe task.tekton.dev/golang-lint Name: golang-lint Namespace: default Labels: app.kubernetes.io/version=0.3 - hub.tekton.dev/catalog=tekton-community + hub.tekton.dev/catalog=tekton +... +``` + +The Artifact Hub guarantees the uniqueness of the Catalog name and Org name, so we can continue using the `--from` to indicate the Catalog name. +This should add labels to the resource indicating the source Catalog (`artifacthub.io/catalog`), the source Org (`artifacthub.io/org`) and the support tier (`artifacthub.io/support-tier`). The source Org is returned in the Artifact Hub API response, and the support tier is determined by the value of the source Org (i.e. `if org == "tektoncd"`) + +```shell +# Buildpacks Community Catalog + +$ tkn hub install task buildpacks --version 0.3 --from buildpacks + +Task buildpacks(0.3) installed in default namespace + +$ kubectl describe task.tekton.dev/buildpacks + +Name: buildpacks +Namespace: default +Labels: app.kubernetes.io/version=0.3 + artifacthub.io/catalog=buildpacks + artifacthub.io/org=buildpacks + artifacthub.io/support-tier=community ... -# Official Catalog +# Git Verified Catalog -$ tkn hub install task golang-fuzz --version 0.1 --from tekton-official +$ tkn hub install task git-clone --version 0.7 --from git-clone -Task golang-fuzz(0.1) installed in default namespace +Task git-clone(0.7) installed in default namespace -$ kubectl describe task.tekton.dev/golang-fuzz +$ kubectl describe task.tekton.dev/git-clone -Name: golang-fuzz +Name: git-clone Namespace: default -Labels: app.kubernetes.io/version=0.1 - hub.tekton.dev/catalog=tekton-official +Labels: app.kubernetes.io/version=0.7 + artifacthub.io/catalog=git-clone + artifacthub.io/org=tektoncd # return by the Artifact Hub API + artifacthub.io/support-tier=verified # verified because the org is "tektoncd" ... ``` -#### Community and Official Catalogs in the Cluster +#### Cluster -When resources are installed in a cluster, without using the CLI, -it may be difficult to identify which Tekton Catalog it came from -because they won't have the labels added by the CLI. +When resources are installed in a cluster, without using the CLI, it may be difficult to identify which Tekton Catalog +it came from because they won't have the labels added by the CLI. -To make it easy for users to identify the source Catalog, we propose -adding two annotations: -* `tekton.dev/catalog` with the three part domain unique identifier +To make it easy for users to identify the source Catalog from the Hub, we propose adding three annotations: +* `tekton.dev/catalog` with the two-part domain unique identifier: `.` +* `tekton.dev/catalog-support-tier` with the support tier of the Catalog, either `"verified"` or `"community"` * `tekton.dev/catalog-url` with the repository path of the Catalog -```yaml -# resource from the community catalog -annotations: - tekton.dev/pipelines.minVersion: "0.17.0" - tekton.dev/tags: golang-lint - tekton.dev/catalog: dev.tekton.catalog-community - tekton.dev/catalog-url: https://github.com/tektoncd/catalog - -# resource from the official catalog -annotations: - tekton.dev/pipelines.minVersion: "0.30.0" - tekton.dev/tags: golang-fuzz - tekton.dev/catalog: dev.tekton.catalog-official - tekton.dev/catalog-url: https://github.com/tektoncd/catalog-official -``` - -The rationale for adding the three dot domain is: -* URL can change and resource can be moved elsewhere - if we want to know the - provenance of a Catalog resource, the URL is not something we can rely on. -* Domain identifier allow us to easily know which provider is providing a given - Catalog. A company may want to introduce their own Catalogs for their users and - having a domain id make sure there would be no conflicts with official resources. +The rationale for adding the two-part dot domain is: +* URL can change and resource can be moved elsewhere - if we want to know the provenance of a Catalog resource, the URL +is not something we can rely on. +* Domain identifier allow us to easily know which provider is providing a given Catalog. A company may want to introduce +their own Catalogs for their users and having a domain id make sure there would be no conflicts with verified resources. * Tools can always rely on the domain id to remain the same. -Example usage of the annotations in Catalogs belonging to organizations: - ```yaml -# resource from the openshift catalog +# annotations on resource from the "buildpacks" community catalog +annotations: + tekton.dev/pipelines.minVersion: "0.7.0" + tekton.dev/tags: build + tekton.dev/catalog: buildpacks.tekton-integration + tekton.dev/catalog-support-tier: community + tekton.dev/catalog-url: https://github.com/buildpacks/tekton-integration + +# annotations on resource from the "openshift" community catalog annotations: tekton.dev/pipelines.minVersion: "0.17.0" - tekton.dev/tags: openshift-build - tekton.dev/catalog: com.redhat.openshift + tekton.dev/tags: build + tekton.dev/catalog: openshift.catalog + tekton.dev/catalog-support-tier: community tekton.dev/catalog-url: https://github.com/openshift/catalog -# resource from the gke catalog +# annotations on resource from the "git" verified catalog annotations: tekton.dev/pipelines.minVersion: "0.30.0" - tekton.dev/tags: gke-build - tekton.dev/catalog: com.google.gke - tekton.dev/catalog-url: https://github.com/gke/catalog -``` + tekton.dev/tags: gitops + tekton.dev/catalog: tektoncd.git + tekton.dev/catalog-support-tier: verified + tekton.dev/catalog-url: https://github.com/tektoncd-catalog/git -#### Community and Official Catalogs in Tekton Bundles +# annotations on resource from the "kaniko" verified catalog +annotations: + tekton.dev/pipelines.minVersion: "0.30.0" + tekton.dev/tags: build + tekton.dev/catalog: tektoncd.kaniko + tekton.dev/catalog-support-tier: verified + tekton.dev/catalog-url: https://github.com/tektoncd-catalog/kaniko +``` -We propose publishing the resources in Catalogs as bundles separate OCI registries: -* Community Catalog - `gcr.io/tekton-releases/catalog/upstream/:` -* Official Catalog - `gcr.io/tekton-releases/catalog-official/upstream/:` +#### Bundles -Users can use the applicable reference to fetch and use the resource, as such: +We propose publishing Tekton Bundles of the resources in the Verified Catalogs; note that we publish one Bundle per +resource currently. Users can use the applicable reference to fetch and use the resource, as such: ```yaml -# bundle from a resource in the community catalog +# bundle from a resource in the verified "git" catalog taskRef: - name: golang-lint - bundle: gcr.io/tekton-releases/catalog/upstream/golang-lint:0.1 + name: git-clone + bundle: gcr.io/tekton-releases/catalogs/git/git-clone:0.7 -# bundle from a resource in the official catalog +# bundle from a resource in the verified "kaniko" catalog taskRef: - name: golang-fuzz - bundle: gcr.io/tekton-releases/catalog-official/upstream/golang-fuzz:0.1 + name: kaniko + bundle: gcr.io/tekton-releases/catalogs/kaniko/kaniko:0.3 ``` -#### Community and Official Catalogs in Remote Resolution +Community Contributors can publish Tekton Bundles from their own Catalogs to the their own registries using the resources provided by Tekton e.g. there is a `Task` for [publishing resource in a Catalog to Bundles][catalog-publish] in the existing Tekton Catalog. + +#### Remote Resolution + +In [TEP-0060: Remote Resource Resolution][tep-0060], we introduced fetching resources from remote resources. +Remote Resolution works well with the Community and verified Catalogs as demonstrated in the examples below. -In [TEP-0060: Remote Resource Resolution][tep-0060], we are looking to support -fetching and running resources from remote resources. It works well with the -Community and Official Catalogs as demonstrated in the examples below. +##### Bundles Resolver Using [Bundles Resolver][bundle-resolver]: ```yaml -# bundle from a resource in the community catalog +# bundle of a resource from the verified "git" catalog taskRef: resolver: bundle - resource: - image_url: gcr.io/tekton-releases/catalog/upstream/golang-lint:0.1 - name: golang-lint - -# bundle from a resource in the official catalog + params: + - name: bundle + value: gcr.io/tekton/catalog/git/git-clone:0.7 + - name: name + value: git-clone + - name: kind + value: task + +# bundle of a resource from the community "buildpacks" catalog taskRef: resolver: bundle - resource: - image_url: gcr.io/tekton-releases/catalog-official/upstream/golang-fuzz:0.1 - name: golang-fuzz + params: + - name: bundle + value: gcr.io/buildpacks/catalog/buildpacks/buildpacks:0.3 + - name: name + value: buildpacks + - name: kind + value: task ``` +##### Git Resolver + Using [Git Resolver][git-resolver]: ```yaml -# resource in the community catalog +# "clone" task in the verified "git" catalog taskRef: resolver: git - resource: - repository_url: https://github.com/tektoncd/catalog.git - branch: main - path: /task/golang-lint/0.1/golang-lint.yaml - -# resource in the official catalog + params: + - name: url + value: https://github.com/tektoncd-catalog/git + - name: revision + value: v0.5 + - name: pathInRepo + value: task/clone/clone.yaml + +# "buildpacks" task the community "buildpacks" catalog taskRef: resolver: git resource: - repository_url: https://github.com/tektoncd/catalog-official.git - branch: main - path: /task/golang-fuzz/0.1/golang-fuzz.yaml + - name: url + value: https://github.com/buildpacks/tekton-integration + - name: revision + value: main + - name: pathInRepo + value: task/buildpacks/buildpacks.yaml +``` + +##### Hub Resolver + +Using [Hub Resolver][hub-resolver]: + +```yaml +# "clone" task in the verified "git" catalog +taskRef: + resolver: hub + params: + - name: type + value: artifact + - name: catalog + value: git + - name: kind + value: task + - name: name + value: clone + - name: version + value: 0.5 + +# "buildpacks" task the community "buildpacks" catalog +taskRef: + resolver: hub + params: + - name: type + value: artifact + - name: catalog + value: buildpacks + - name: kind + value: task + - name: name + value: buildpacks + - name: version + value: 0.3 ``` #### Responsibilities @@ -471,111 +463,53 @@ The responsibilities of owning a resource include but are not limited to: 1. Reviewing and approving all changes to the resource. 2. Resolving any failures of tests validating the resource. 3. Responding to and resolving any issues reported concerning the resource. -4. Updating the resources to be compatible with new versions of Tekton, and - other dependencies. +4. Updating the resources to be compatible with new versions of Tekton, and other dependencies. ##### Catalog Ownership The responsibilities of owning a Catalog include but are not limited to: -1. Reviewing and approving new resources contributed to the Catalogs. +1. Reviewing and approving new resources contributed to the Catalog. 2. Maintaining the health of the testing infrastructure. 3. Triaging issues and involving the owners of the affected resources. 4. Ensuring the resources meet the quality standards of the Catalog. #### Design Evaluation -The Catalogs will leverage existing structure and infrastructure that -supports the existing `tektoncd/catalog`. Decoupling the support tiers -into separate repositories makes it easy to distinguish the support tiers, -enforce the applicable quality standards, and leverage existing structure -and infrastructure. Moreover, reusing the existing Catalog at -`tektoncd/catalog` minimizes effort to provide the support tiers. +This design builds on the prior work to decouple Catalog organization from resource reference in [TEP-0110][tep-0110] +and git-based versioning in [TEP-0115][tep-0115]. The Catalogs used to provide Verified and Community support tiers +makes it easier to enforce the applicable quality standards while maintaining the lower barrier of entry. #### Alternatives -##### 1. One Repository and Use Annotations +##### 1. Verified Support Tier -Instead of creating new repository, add a new `tekton.dev/tier` annotation -to the resource yaml file with the relevant support tier, for example: +[TEP-0003: Tekton Catalog Organization][tep-0003] proposed three support tiers for resources in the Tekton Catalog, +*community*, *verified* and *official*, which are differentiated as such: -```yaml - annotations: - tekton.dev/pipelines.minVersion: "0.17.0" - tekton.dev/tags: image-build - tekton.dev/tier: official -``` - -The `tekton.dev/tier` annotation should be optional. If the annotation -is not specified, `community` support tier is the default. - -###### Design Evaluation - -+ This provides backward compatibility to the existing resources - in the Tekton Catalog, given the default to `community`. -- It makes it difficult to distinguish between community and official - resources in the one repository, without digging into the yamls. - It also makes it harder for maintainers to enforce the quality - requirements, such as SLOs, for the tiers when they are all mixed up. - However, tooling could help make it easier. -- While this approach makes it easier to promote a resource, it - also makes it easier for a resource to be mistakenly placed in - official tier. - -##### 2. One Repository and Use OWNERS - -Instead of creating new repository, modify the `OWNERS` file at -`./{resource-type}/{resource-name}/OWNERS` to indicate the support tier. -Given that a resource would start as community resource before being -bumped to official resource, we would to map specific versions to their -support tier and maintainers list. To limit duplication, we could create -a syntax to indicate the range of versions, such as: - -```yaml -support: - -- tier: community - versions: >= 0.1, <0.5 - maintainers: x@y.com - -- tier: official - versions: >=0.5 - maintainers: x@y.com -``` +| | 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: | ###### Design Evaluation -- This approach changes the Catalog contract defined in [TEP-0003][tep-0003]. -- This approach requires making changes to the all the existing resources in - the Tekton Catalog. -- It makes it difficult to distinguish between community and official - resources in the one repository, without digging into the yamls. - It also makes it harder for maintainers to enforce the quality - requirements, such as SLOs, for the tiers when they are all mixed up. - However, tooling could help make it easier. -- While this approach makes it easier to promote a resource, it - also makes it easier for a resource to be mistakenly placed in - official tier. +Resources in the verified tier are effectively resources in the community tier that are tested. Given that resources in the community tier can be tested or untested, we can use a simpler mechanism to indicate their testing status, such as a badge in the Artifact Hub. Therefore, adding a verified support tier is unnecessary, and we'd prefer to keep the tiers simple. -##### 3. Verified Support Tier +The *official* Tekton Catalog support tier collides with the Artifact Hub ["official status"](https://artifacthub.io/docs/topics/repositories/#official-status), which means the publisher **owns the software deployed by a package** (e.g. the `kaniko` task published by the kaniko maintainers can claim the `official status` instead of the Tekton maintainers). The naming collision causes confusion and inconsistency between the Tekton and the Artifact Hub users, and therefore we prefer to avoid using the term *official* in Tekton Catalogs. -[TEP-0003: Tekton Catalog Organization][tep-0003] proposed three support tiers -for resources in the Tekton Catalog, *community*, *verified* and *official*, -which are differentiated as such: +##### 2. Community Catalogs in tektoncd-catalog GitHub Org -| | 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: | +We could allow hosting Community Catalogs in tektoncd-catalog GitHub Org and use another means to indicate the tier +of the Catalog, such as by using the `catalog-support-tier` field in Hub configuration. ###### Design Evaluation -Resources in the verified tier are effectively resources in the community tier -that are tested. Given that resources in the community tier can be tested or -untested, we can use a simpler mechanism to indicate their testing status, -such as a badge in the Tekton Hub. Therefore, adding a verified support tier -is unnecessary, and we'd prefer to keep the tiers simple. +There's no clear benefit for allowing Contributors to host Catalogs in the tektoncd-catalog GitHub Org. However, +it adds more maintenance burden because the Tekton Maintainers would have to create the repositories, and provide +general oversight. Contributors are already hosting Catalogs in their own organizations and repositories e.g. +[eBay][ebay] and [Buildpacks][buildpacks]. ### Automated Testing and Dogfooding @@ -602,23 +536,31 @@ TODO [catalog-proposal]: https://docs.google.com/document/d/1O8VHZ-7tNuuRjPNjPfdo8bD--WDrkcz-lbtJ3P8Wugs/edit#heading=h.iyqzt1brkg3o [catalog-hub-design]: https://docs.google.com/document/d/1pZY7ROLuW47ymZYqUgAbxskmirrmDg2dd8VPATYXrxI/edit# [catalog-support-tiers]: https://docs.google.com/document/d/1BClb6cHQkbSpnHS_OZkmQyDMrB4QX4E5JXxQ_G2er7M/edit?usp=sharing -[tep-0003]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md -[tep-0003-org]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#organization -[tep-0003-ownership]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#ownership -[tep-0003-upstream]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#upstream-catalogs -[tep-0003-hub]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#the-hub-and-multiple-catalogs -[tep-0091]: https://github.com/tektoncd/community/pull/537 -[tep-0060]: https://github.com/tektoncd/community/blob/main/teps/0060-remote-resource-resolution.md +[tep-0003]: ./0003-tekton-catalog-organization.md +[tep-0003-org]: ./0003-tekton-catalog-organization.md#organization +[tep-0003-ownership]: ./0003-tekton-catalog-organization.md#ownership +[tep-0003-upstream]: ./0003-tekton-catalog-organization.md#upstream-catalogs +[tep-0003-hub]: ./0003-tekton-catalog-organization.md#the-hub-and-multiple-catalogs +[tep-0091]: ./0091-trusted-resources.md +[tep-0060]: ./0060-remote-resource-resolution.md +[tep-0110]: ./0110-decouple-catalog-organization-and-reference.md +[tep-0115]: ./0115-tekton-catalog-git-based-versioning.md +[tep-0115-org]: ./0115-tekton-catalog-git-based-versioning.md#git-based-versioning +[tep-0115-migration]: ./0115-tekton-catalog-git-based-versioning.md#migration [tep-infra]: https://github.com/tektoncd/community/pull/170 [doc-infra]: https://docs.google.com/document/d/1-czjvjfpuIqYKsfkvZ5RxIbtoFNLTEtOxaZB71Aehdg [github-rename]: https://docs.github.com/en/repositories/creating-and-managing-repositories/renaming-a-repository [catalog-owners]: https://github.com/tektoncd/catalog/blob/main/OWNERS -[hub]: https://hub.tekton.dev/ +[hub]: https://artifacthub.io/ [deprecation]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#deprecation--removal-strategy -[task-authoring-recommendations]: https://github.com/tektoncd/catalog/blob/main/recommendations.md +[task-authoring-recs]: https://github.com/tektoncd/catalog/blob/main/recommendations.md [bundle]: https://tekton.dev/docs/pipelines/pipelines/#tekton-bundles [hub-config]: https://github.com/tektoncd/hub/blob/68dfd7ed39ca9fc6ea8eb3c95a729110c6c7f81c/config.yaml#L37-L43 [catlin]: https://github.com/tektoncd/plumbing/tree/main/catlin [rfc2119]: https://datatracker.ietf.org/doc/html/rfc2119 -[bundle-resolver]: https://github.com/tektoncd/community/blob/main/teps/0060-remote-resource-resolution.md#bundle-resolver -[git-resolver]: https://github.com/tektoncd/community/blob/main/teps/0060-remote-resource-resolution.md#git-resolver +[bundle-resolver]: https://github.com/tektoncd/resolution/tree/5d7918cb5b6f183d79cf0f91f4f08ecb204505a0/bundleresolver +[git-resolver]: https://github.com/tektoncd/resolution/tree/7f92187843085874229aa4c43e5c6d7d392a26fa/gitresolver +[hub-resolver]: https://github.com/tektoncd/resolution/tree/5d7918cb5b6f183d79cf0f91f4f08ecb204505a0/hubresolver +[catalog-publish]: https://github.com/tektoncd/catalog/tree/e91c9135dbffc088d70ab60434622b4b65680784/task/tekton-catalog-publish/0.1 +[buildpacks]: https://github.com/buildpacks/tekton-integration +[eBay]: https://github.com/eBay/tekton-slack-notify \ No newline at end of file diff --git a/teps/README.md b/teps/README.md index 6660366d4..63bfeba67 100644 --- a/teps/README.md +++ b/teps/README.md @@ -249,7 +249,7 @@ This is the complete list of Tekton teps: |[TEP-0074](0074-deprecate-pipelineresources.md) | Deprecate PipelineResources | implementable | 2022-04-11 | |[TEP-0075](0075-object-param-and-result-types.md) | Object/Dictionary param and result types | implemented | 2022-09-26 | |[TEP-0076](0076-array-result-types.md) | Array result types | implemented | 2022-09-26 | -|[TEP-0079](0079-tekton-catalog-support-tiers.md) | Tekton Catalog Support Tiers | proposed | 2022-01-25 | +|[TEP-0079](0079-tekton-catalog-support-tiers.md) | Tekton Catalog Support Tiers | proposed | 2022-10-17 | |[TEP-0080](0080-support-domainscoped-parameterresult-names.md) | Support domain-scoped parameter/result names | implemented | 2021-08-19 | |[TEP-0081](0081-add-chains-subcommand-to-the-cli.md) | Add Chains sub-command to the CLI | implemented | 2022-04-27 | |[TEP-0082](0082-workspace-hinting.md) | Workspace Hinting | proposed | 2021-10-26 |