Skip to content

Commit

Permalink
TEP-0079: Tekton Catalog Support Tiers [Proposal - Ownership and Main…
Browse files Browse the repository at this point in the history 
…tenance]

In [TEP-0079: Tekton Catalog Support Tiers][tep-0079], we have defined
the problem statement for establishing support tiers for resources in
the Tekton Catalog.

In this change, we address the first goal of [Ownership and Maintenance][goal].

As previously discussed in [TEP-0003][tep-0003-upstream], we propose creating
two support tiers, `Community` and `Official`, through separate Tekton Catalogs.

The Community Catalog would make it easy for contributors to share resources,
while the Official Catalog will be a corpus of high quality resources that
users can rely on.

The other goals and details of testing, scanning and verification will be
explored in the subsequent changes.

[tep-0079]: https://github.com/tektoncd/community/blob/main/teps/0079-tekton-catalog-support-tiers.md
[goal]: https://github.com/tektoncd/community/blob/main/teps/0079-tekton-catalog-support-tiers.md#ownership-and-maintenance
[tep-0003-upstream]: https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md#upstream-catalogs
  • Loading branch information
@jerop
jerop committed Jan 13, 2022
1 parent d32bb36 commit 33a5b09
Show file tree
Hide file tree
Showing 2 changed files with 292 additions and 2 deletions.
292 changes: 291 additions & 1 deletion teps/0079-tekton-catalog-support-tiers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,15 @@
status: proposed
title: Tekton Catalog Support Tiers
creation-date: '2021-08-09'
last-updated: '2022-01-06'
last-updated: '2022-01-12'
authors:
- '@bobcatfish'
- '@jerop'
- '@vdemeester'
- '@vinamra28'
see-also:
- TEP-0003
- TEP-0060
- TEP-0091
---

Expand All @@ -28,6 +29,27 @@ see-also:
- [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)
- [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)
- [Community and Official Catalogs in the Tekton Hub](#community-and-official-catalogs-in-the-tekton-hub)
- [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. Include Verified Support Tier](#3-include-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)
<!-- /toc -->

Expand Down Expand Up @@ -100,14 +122,282 @@ requirements, and provenance attestations can be made to meet software supply ch
[TEP-0091: Verified Remote Resources][tep-0091] will flesh out the details of signing, while this TEP will focus on
surfacing the verification information and building a corpus of verified resources that users can trust.

## 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.

A Catalog is a git repository that complies with the organization contract
defined in [TEP-0003: Tekton Catalog Organization][tep-0003-org].

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.

Both the Community and Official Catalogs will be:
* Owned by the [Tekton Catalog Maintainers][catalog-owners].
* Published in the [Tekton Hub][hub].
* Share infrastructure, such as testing and scanning tooling.

A given resource starts in the Community Catalog. Then it may get
promoted to the Official Catalog if:
* It meets the [requirements of the Official Catalog](#requirements-1).
* The [Tekton Catalog Maintainers][catalog-owners] approve its promotion.

If a resource is promoted to the Official Catalog, it can be
[deprecated][deprecation] in the Community Catalog.
We will provide tooling, through [Caitlin][caitlin], to make it easier
to migrate from the Community Catalog to the Official Catalog.

#### Tekton Community Catalog

To maintain the low barrier to making contributions, users can easily
submit resources to the Community Catalog.

The current Tekton Catalog at `tektoncd/catalog` will be reused as the
Community 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.

Note that resources in the Community Catalog can meet some
[requirements](#requirements-1) of resources in the Official Catalog.

#### 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`.

##### Requirements

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].

#### 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:

```yaml
catalogs:

# community catalog
- name: tekton
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
```
This provides extensibility to the support tiers: we can add additional
Catalogs for other support tiers as needed in the future.
#### Responsibilities
##### Resource Ownership
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.
##### Catalog Ownership
The responsibilities of owning a Catalog include but are not limited to:
1. Reviewing and approving new resources contributed to the Catalogs.
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.

#### Alternatives

##### 1. One Repository and Use Annotations

Instead of creating new repository, 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: 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.
- 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
```

###### 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.
- 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.

##### 3. Include Verified Support Tier

[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:

| | 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

- 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.

### Automated Testing and Dogfooding

TODO

### Image Scanning for Common Vulnerabilities and Exposures (CVEs)

TODO

### Verified Remote Resources

TODO

## References

* [Tekton Catalog and Hub Design][catalog-hub-design]
* [Pipeline Catalog Integration Proposal][catalog-proposal]
* [Original Tekton Catalog Tiers Proposal][catalog-support-tiers]
* [Tekton Catalog Test Infrastructure Design Doc](doc-infra)
* [TEP for Catalog Test Requirements and Infra for Verified+][tep-infra]
* [TEP-0003: Tekton Catalog Organization][tep-0003]
* [TEP-0091: Verified Remote Resources][tep-0091]

[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-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/
[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
[bundle]: https://tekton.dev/docs/pipelines/pipelines/#tekton-bundles
[hub-config]: https://github.com/tektoncd/hub/blob/68dfd7ed39ca9fc6ea8eb3c95a729110c6c7f81c/config.yaml#L37-L43
[caitlin]: https://github.com/tektoncd/plumbing/tree/main/catlin
2 changes: 1 addition & 1 deletion teps/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ This is the complete list of Tekton teps:
|[TEP-0072](0072-results-json-serialized-records.md) | Results: JSON Serialized Records | implementable | 2021-07-26 |
|[TEP-0073](0073-simplify-metrics.md) | Simplify metrics | proposed | 2021-11-01 |
|[TEP-0074](0074-deprecate-pipelineresources.md) | Deprecate PipelineResources | proposed | 2021-11-05 |
|[TEP-0079](0079-tekton-catalog-support-tiers.md) | Tekton Catalog Support Tiers | proposed | 2022-01-06 |
|[TEP-0079](0079-tekton-catalog-support-tiers.md) | Tekton Catalog Support Tiers | proposed | 2022-01-12 |
|[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 | implementable | 2021-10-21 |
|[TEP-0082](0082-workspace-hinting.md) | Workspace Hinting | proposed | 2021-10-26 |
Expand Down

0 comments on commit 33a5b09

Please sign in to comment.