Skip to content

Rewrite the alpha-to-beta migration guide for clarity and flow. #2539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 7, 2020
Merged

Rewrite the alpha-to-beta migration guide for clarity and flow. #2539

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 57 additions & 54 deletions docs/migrating-v1alpha1-to-v1beta1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,36 @@
# Migrating From v1alpha1 to v1beta1
# Migrating From Tekton `v1alpha1` to Tekton `v1beta1`

- [Migrating From v1alpha1 to v1beta1](#migrating-from-v1alpha1-to-v1beta1)
- [Inputs and Outputs](#inputs-and-outputs)
- [Input Params](#input-params)
- [Input and Output PipelineResources](#input-and-output-pipelineresources)
- [PipelineResources and Catalog Tasks](#pipelineresources-and-catalog-tasks)
- [Git Resource](#git-resource)
- [Pull Request Resource](#pull-request-resource)
- [Image Resource](#image-resource)
- [GCS Resource](#gcs-resource)
- [Changes to fields](#changes-to-fields)
- [Changes to input parameters](#changes-to-input-parameters)
- [Changes to `PipelineResources`](#changes-to-pipelineresources)
- [Replacing `PipelineResources` with `Tasks`](#replacing-pipelineresources-with-tasks)
- [Replacing a `git` resource](#replacing-a-git-resource)
- [Replacing a `pullrequest` resource](#replacing-a-pullrequest-resource)
- [Replacing a `gcs` resource](#replacing-a-gcs-resource)
- [Replacing an `image` resource](#replacing-an-image-resource)

This doc describes the changes you'll need to make when converting your `Task`s,
`Pipeline`s, `TaskRun`s, and `PipelineRun`s from the `v1alpha1` `apiVersion` to
`v1beta1`.
This document describes the differences between `v1alpha` Tekton entities and their
`v1beta1` counterparts. It also describes how to replace the supported types of
`PipelineResources` with `Tasks` from the Tekton Catalog of equivalent functionality.

## Inputs and Outputs
## Changes to fields

The `spec.inputs` and `spec.outputs` fields in `Tasks` are removed in `v1beta1`.
`spec.inputs.params` is moved to `spec.params`. `spec.inputs.resources` becomes
`spec.resources.inputs` and `spec.outputs.resources` becomes `spec.resources.outputs`.
In Tekton `v1beta`, the following fields have been changed:

#### Input Params
| Old field | New field |
| --------- | ----------|
| `spec.inputs.params` | `spec.params` |
| `spec.inputs.resources` | `spec.resources.inputs` |
| `spec.outputs.resources` | `spec.resources.outputs` |
| `spec.inputs` | Removed from `Tasks` |
| `spec.outputs` | Removed from `Tasks` |

Params move from `spec.inputs.params` in v1alpha1 to just `spec.params` in v1beta1.

Example v1alpha1 Params:
## Changes to input parameters

In Tekton `v1beta`, input parameters have been moved from `spec.inputs.params` to `spec.params`.

For example, consider the following `v1alpha1` parameters:

```yaml
# Task.yaml (v1alpha1)
Expand All @@ -43,7 +49,7 @@ spec:
value: https://example.com/foo.json
```

Equivalent v1beta1 Params:
The above parameters are now represented as follows in `v1beta1`:

```yaml
# Task.yaml (v1beta1)
Expand All @@ -60,13 +66,13 @@ spec:
value: https://example.com/foo.json
```

#### Input and Output PipelineResources
## Changes to `PipelineResources`

In v1alpha1, `PipelineResources` were stored under `spec.inputs.resources` and
`spec.outputs.resources`. In v1beta1 these change to `spec.resources.inputs` and
`spec.resources.outputs`.
In Tekton `v1beta`, `PipelineResources` have been moved from `spec.input.respources`
and `spec.output.resources` to `spec.resources.inputs` and `spec.resources.outputs`,
respectively.

Example v1alpha1 PipelineResources:
For example, consider the following `v1alpha1` definition:

```yaml
# Task.yaml (v1alpha1)
Expand Down Expand Up @@ -102,7 +108,7 @@ spec:
value: gcr.io/foo/bar
```

Equivalent v1beta1 PipelineResources:
The above definition becomes the following in `v1beta1`:

```yaml
# Task.yaml (v1beta1)
Expand Down Expand Up @@ -136,42 +142,39 @@ spec:
value: gcr.io/foo/bar
```

## PipelineResources and Catalog Tasks
## Replacing `PipelineResources` with `Tasks`

While Tekton Pipelines has advanced to beta, `PipelineResources` remain in alpha
in a deliberate effort to migrate users away from `PipelineResources` and onto
a broader suite of reusable `Tasks` in the Tekton Catalog.

PipelineResources are remaining in alpha while the other resource kinds are
promoted to beta. This is part of a deliberate effort to migrate users away
from PipelineResources onto a broader suite of reusable Tasks provided by
the Tekton catalog.
In the near term, Tekton continues to support `PipelineResources`; however, they
will be eventually deprecated and removed from Tekton.

In the near-term `PipelineResources` will continue to be supported by Tekton.
At some point the feature may well be deprecated and subsequently replaced.
You can replace the types of `PipelineResources` listed below with `Tasks` from the
Tekton Catalog of equivalent functionality as described below.

To ease migration away from PipelineResources some types have an equivalent
Task in the Catalog.
### Replacing a `git` resource

### Git Resource
You can replace a `git` resource with the [`git-clone` Catalog `Task`](https://github.com/tektoncd/catalog/tree/v1beta1/git).

The [`git-clone` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/git)
provides an equivalent to the Git Resource.
### Replacing a `pullrequest` resource

### Pull Request Resource
You can replace a `pullrequest` resource with the [`pullrequest` Catalog `Task`](https://github.com/tektoncd/catalog/tree/v1beta1/pullrequest).

The [`pullrequest` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/pullrequest)
provides an equivalent to the PullRequest Resource.
### Replacing a `gcs` resource

### Image Resource
You can replace a `gcs` resource with the [`gcs` Catalog `Task`](https://github.com/tektoncd/catalog/tree/v1beta1/gcs).

The Image PipelineResource does not come with specific behaviour, it's simply a way to share
a built image's digest with subsequent `Tasks` in a `Pipeline`. The same effect can be achieved
using [`Task` results](./tasks.md#results) and [`Task` params](./tasks.md#parameters)
### Replacing an `image` resource

For an example of how the Image PipelineResource can be replaced, see
the [Kaniko Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
which demonstrates writing the image digest to a result, and the
[Buildah Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
which shows how to accept an image digest as a parameter.
Since the `image` resource is simply a way to share the digest of a built image with subsequent
`Tasks` in your `Pipeline`, you can use [`Task` results](tasks.md#storing-execution-results) to
achieve equivalent functionality.

### GCS Resource
For examples of replacing an `image` resource, see the following Catalog `Tasks`:

The [`gcs` Tasks in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/gcs) provide
an equivalent to the GCS Resource.
- The [Kaniko Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
illustrates how to write the digest of an image to a result.
- The [Buildah Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
illustrates how to accept an image digest as a parameter.