Skip to content

Commit

Permalink
Add resolution types to the API
Browse files Browse the repository at this point in the history
TEP-0060 adds remote resource resolution to Tekton Pipelines,
allowing PipelineRuns and TaskRuns to reference Pipelines and Tasks
in remote places like git repos.

This PR adds the initial alpha syntax for the remote resolution feature
to the v1beta1.TaskRef and v1beta1.PipelineRef types along with validation
for them. Some initial documentation is added describing the syntax for
remote tasks and pipelines.
  • Loading branch information
Scott authored and tekton-robot committed Feb 10, 2022
1 parent 2b3a0db commit 5d3f23e
Show file tree
Hide file tree
Showing 16 changed files with 632 additions and 67 deletions.
21 changes: 11 additions & 10 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -402,16 +402,17 @@ the `feature-flags` ConfigMap alongside your Tekton Pipelines deployment.
Features currently in "alpha" are:
| Feature | TEP | Release | Individual Flag |
|:------------------------------------------------------------------------------- |:----------------------------------------------------------------------------------------------------------- |:-------------------------------------------------------------------- |:--------------------------- |
| [Bundles ](./pipelineruns.md#tekton-bundles) | [TEP-0005](https://github.com/tektoncd/community/blob/main/teps/0005-tekton-oci-bundles.md) | [v0.18.0](https://github.com/tektoncd/pipeline/releases/tag/v0.18.0) | `enable-tekton-oci-bundles` |
| [`Runs` and `Custom Tasks`](./runs.md) | [TEP-0002](https://github.com/tektoncd/community/blob/main/teps/0002-custom-tasks.md) | [v0.19.0](https://github.com/tektoncd/pipeline/releases/tag/v0.19.0) | `enable-custom-tasks` |
| [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces) | [TEP-0029](https://github.com/tektoncd/community/blob/main/teps/0029-step-workspaces.md) | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | |
| [Hermetic Execution Mode](./hermetic.md) | [TEP-0025](https://github.com/tektoncd/community/blob/main/teps/0025-hermekton.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [Graceful Termination](./pipelineruns.md#gracefully-cancelling-a-pipelinerun) | [TEP-0058](https://github.com/tektoncd/community/blob/main/teps/0058-graceful-pipeline-run-termination.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [`PipelineRun` Timeouts](./pipelineruns.md#configuring-a-failure-timeout) | [TEP-0046](https://github.com/tektoncd/community/blob/main/teps/0046-finallytask-execution-post-timeout.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [Implicit `Parameters`](./taskruns.md#implicit-parameters) | [TEP-0023](https://github.com/tektoncd/community/blob/main/teps/0023-implicit-mapping.md) | [v0.28.0](https://github.com/tektoncd/pipeline/releases/tag/v0.28.0) | |
| [Windows Scrips](./tasks.md#windows-scripts) | [TEP-0057](https://github.com/tektoncd/community/blob/main/teps/0057-windows-support.md) | [v0.28.0](https://github.com/tektoncd/pipeline/releases/tag/v0.28.0) | |
| Feature | TEP | Release | Individual Flag |
|:------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------- |:-------------------------------------------------------------------- |:--------------------------- |
| [Bundles ](./pipelineruns.md#tekton-bundles) | [TEP-0005](https://github.com/tektoncd/community/blob/main/teps/0005-tekton-oci-bundles.md) | [v0.18.0](https://github.com/tektoncd/pipeline/releases/tag/v0.18.0) | `enable-tekton-oci-bundles` |
| [`Runs` and `Custom Tasks`](./runs.md) | [TEP-0002](https://github.com/tektoncd/community/blob/main/teps/0002-custom-tasks.md) | [v0.19.0](https://github.com/tektoncd/pipeline/releases/tag/v0.19.0) | `enable-custom-tasks` |
| [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces) | [TEP-0029](https://github.com/tektoncd/community/blob/main/teps/0029-step-workspaces.md) | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | |
| [Hermetic Execution Mode](./hermetic.md) | [TEP-0025](https://github.com/tektoncd/community/blob/main/teps/0025-hermekton.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [Graceful Termination](./pipelineruns.md#gracefully-cancelling-a-pipelinerun) | [TEP-0058](https://github.com/tektoncd/community/blob/main/teps/0058-graceful-pipeline-run-termination.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [`PipelineRun` Timeouts](./pipelineruns.md#configuring-a-failure-timeout) | [TEP-0046](https://github.com/tektoncd/community/blob/main/teps/0046-finallytask-execution-post-timeout.md) | [v0.25.0](https://github.com/tektoncd/pipeline/releases/tag/v0.25.0) | |
| [Implicit `Parameters`](./taskruns.md#implicit-parameters) | [TEP-0023](https://github.com/tektoncd/community/blob/main/teps/0023-implicit-mapping.md) | [v0.28.0](https://github.com/tektoncd/pipeline/releases/tag/v0.28.0) | |
| [Windows Scripts](./tasks.md#windows-scripts) | [TEP-0057](https://github.com/tektoncd/community/blob/main/teps/0057-windows-support.md) | [v0.28.0](https://github.com/tektoncd/pipeline/releases/tag/v0.28.0) | |
| [Remote Tasks](./taskruns.md#remote-tasks) and [Remote Pipelines](./pipelineruns.md#remote-pipelines) | [TEP-0060](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resolutiond.md) | | |
## Configuring High Availability
Expand Down
24 changes: 24 additions & 0 deletions docs/pipelineruns.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ weight: 500
- [Configuring a <code>PipelineRun</code>](#configuring-a-pipelinerun)
- [Specifying the target <code>Pipeline</code>](#specifying-the-target-pipeline)
- [Tekton Bundles](#tekton-bundles)
- [Remote Pipelines](#remote-pipelines)
- [Specifying <code>Resources</code>](#specifying-resources)
- [Specifying <code>Parameters</code>](#specifying-parameters)
- [Implicit Parameters](#implicit-parameters)
Expand Down Expand Up @@ -164,6 +165,29 @@ in [Pipelines](pipelines.md#tekton-bundles) or [TaskRuns](taskruns.md#tekton-bun
`Tekton Bundles` may be constructed with any toolsets that produce valid OCI image artifacts
so long as the artifact adheres to the [contract](tekton-bundle-contracts.md).

#### Remote Pipelines

**([alpha only](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features))**

**Warning: This feature is still in very early stage of development and is not yet functional. Do not use it.**

A `pipelineRef` field may specify a Pipeline in a remote location such as git.
Support for specific types of remote will depend on the Resolvers your
cluster's operator has installed. The below example demonstrates
referencing a Pipeline in git:

```yaml
spec:
pipelineRef:
resolver: git
resource:
- name: repo
value: https://github.com/tektoncd/catalog.git
- name: commit
value: abc123
- name: path
value: /pipeline/buildpacks/0.1/buildpacks.yaml
```

### Specifying `Resources`

Expand Down
25 changes: 25 additions & 0 deletions docs/taskruns.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ weight: 300
- [Configuring a `TaskRun`](#configuring-a-taskrun)
- [Specifying the target `Task`](#specifying-the-target-task)
- [Tekton Bundles](#tekton-bundles)
- [Remote Tasks](#remote-tasks)
- [Specifying `Parameters`](#specifying-parameters)
- [Implicit Parameters](#implicit-parameters)
- [Extra Parameters](#extra-parameters)
Expand Down Expand Up @@ -158,6 +159,30 @@ of the same named `Task` to be run at once.
the artifact adheres to the [contract](tekton-bundle-contracts.md). Additionally, you may also use the `tkn`
cli *(coming soon)*.

### Remote Tasks

**([alpha only](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features))**

**Warning: This feature is still in very early stage of development and is not yet functional. Do not use it.**

A `taskRef` field may specify a Task in a remote location such as git.
Support for specific types of remote will depend on the Resolvers your
cluster's operator has installed. The below example demonstrates
referencing a Task in git:

```yaml
spec:
taskRef:
resolver: git
resource:
- name: repo
value: https://github.com/tektoncd/catalog.git
- name: commit
value: abc123
- name: path
value: /task/golang-build/0.3/golang-build.yaml
```

### Specifying `Parameters`

If a `Task` has [`parameters`](tasks.md#parameters), you can use the `params` field to specify their values:
Expand Down
8 changes: 4 additions & 4 deletions pkg/apis/pipeline/v1alpha1/zz_generated.deepcopy.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

68 changes: 68 additions & 0 deletions pkg/apis/pipeline/v1beta1/openapi_generated.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

88 changes: 88 additions & 0 deletions pkg/apis/pipeline/v1beta1/pipelineref_validation.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
/*
Copyright 2022 The Tekton Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package v1beta1

import (
"context"

"github.com/google/go-containerregistry/pkg/name"
"github.com/tektoncd/pipeline/pkg/apis/config"
"knative.dev/pkg/apis"
)

// Validate ensures that a supplied PipelineRef field is populated
// correctly. No errors are returned for a nil PipelineRef.
func (ref *PipelineRef) Validate(ctx context.Context) (errs *apis.FieldError) {
cfg := config.FromContextOrDefaults(ctx)
if ref == nil {
return
}
if cfg.FeatureFlags.EnableAPIFields == config.AlphaAPIFields {
errs = errs.Also(ref.validateAlphaRef(ctx))
} else {
errs = errs.Also(ref.validateInTreeRef(ctx))
}
return
}

// validateInTreeRef returns errors if the given pipelineRef is not
// valid for Pipelines' built-in resolution machinery.
func (ref *PipelineRef) validateInTreeRef(ctx context.Context) (errs *apis.FieldError) {
cfg := config.FromContextOrDefaults(ctx)
if ref.Resolver != "" {
errs = errs.Also(apis.ErrDisallowedFields("resolver"))
}
if ref.Resource != nil {
errs = errs.Also(apis.ErrDisallowedFields("resource"))
}
if ref.Name == "" {
errs = errs.Also(apis.ErrMissingField("name"))
}
if cfg.FeatureFlags.EnableTektonOCIBundles {
if ref.Bundle != "" && ref.Name == "" {
errs = errs.Also(apis.ErrMissingField("name"))
}
if ref.Bundle != "" {
if _, err := name.ParseReference(ref.Bundle); err != nil {
errs = errs.Also(apis.ErrInvalidValue("invalid bundle reference", "bundle", err.Error()))
}
}
} else if ref.Bundle != "" {
errs = errs.Also(apis.ErrDisallowedFields("bundle"))
}
return
}

// validateAlphaRef ensures that the user has passed either a
// valid remote resource reference or a valid in-tree resource reference,
// but not both.
func (ref *PipelineRef) validateAlphaRef(ctx context.Context) (errs *apis.FieldError) {
switch {
case ref.Resolver == "" && ref.Resource != nil:
errs = errs.Also(apis.ErrMissingField("resolver"))
case ref.Resolver == "":
errs = errs.Also(ref.validateInTreeRef(ctx))
default:
if ref.Name != "" {
errs = errs.Also(apis.ErrMultipleOneOf("name", "resolver"))
}
if ref.Bundle != "" {
errs = errs.Also(apis.ErrMultipleOneOf("bundle", "resolver"))
}
}
return
}
6 changes: 6 additions & 0 deletions pkg/apis/pipeline/v1beta1/pipelinerun_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,12 @@ type PipelineRef struct {
// Bundle url reference to a Tekton Bundle.
// +optional
Bundle string `json:"bundle,omitempty"`

// ResolverRef allows referencing a Pipeline in a remote location
// like a git repo. This field is only supported when the alpha
// feature gate is enabled.
// +optional
ResolverRef `json:",omitempty"`
}

// PipelineRunStatus defines the observed state of PipelineRun
Expand Down
26 changes: 3 additions & 23 deletions pkg/apis/pipeline/v1beta1/pipelinerun_validation.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ import (
"fmt"
"time"

"github.com/google/go-containerregistry/pkg/name"
"github.com/tektoncd/pipeline/pkg/apis/config"
apisconfig "github.com/tektoncd/pipeline/pkg/apis/config"
"github.com/tektoncd/pipeline/pkg/apis/validate"
Expand All @@ -48,8 +47,6 @@ func (pr *PipelineRun) Validate(ctx context.Context) *apis.FieldError {

// Validate pipelinerun spec
func (ps *PipelineRunSpec) Validate(ctx context.Context) (errs *apis.FieldError) {
cfg := config.FromContextOrDefaults(ctx)

// Must have exactly one of pipelineRef and pipelineSpec.
if ps.PipelineRef == nil && ps.PipelineSpec == nil {
errs = errs.Also(apis.ErrMissingOneOf("pipelineRef", "pipelineSpec"))
Expand All @@ -58,26 +55,9 @@ func (ps *PipelineRunSpec) Validate(ctx context.Context) (errs *apis.FieldError)
errs = errs.Also(apis.ErrMultipleOneOf("pipelineRef", "pipelineSpec"))
}

// Validate that a pipelineRef has a name; this may be refactored elsewhere later.
if ps.PipelineRef != nil && ps.PipelineRef.Name == "" {
errs = errs.Also(apis.ErrMissingField("pipelineRef.name"))
}

// If EnableTektonOCIBundles feature flag is on validate it.
// Otherwise, fail if it is present (as it won't be allowed nor used)
if cfg.FeatureFlags.EnableTektonOCIBundles {
// Check that if a pipelineRef.bundle is specified, that a pipelineRef.name is specified as well.
if ps.PipelineRef != nil && ps.PipelineRef.Bundle != "" && ps.PipelineRef.Name == "" {
errs = errs.Also(apis.ErrMissingField("pipelineRef.name"))
}
// If a bundle url is specified, ensure it is parseable.
if ps.PipelineRef != nil && ps.PipelineRef.Bundle != "" {
if _, err := name.ParseReference(ps.PipelineRef.Bundle); err != nil {
errs = errs.Also(apis.ErrInvalidValue("invalid bundle reference", "pipelineRef.bundle", err.Error()))
}
}
} else if ps.PipelineRef != nil && ps.PipelineRef.Bundle != "" {
errs = errs.Also(apis.ErrDisallowedFields("pipelineRef.bundle"))
// Validate PipelineRef if it's present
if ps.PipelineRef != nil {
errs = errs.Also(ps.PipelineRef.Validate(ctx).ViaField("pipelineRef"))
}

// Validate PipelineSpec if it's present
Expand Down
Loading

0 comments on commit 5d3f23e

Please sign in to comment.