Skip to content

Commit 8fea823

Browse files
JeromeJuJeromeJu
committed
Doc about migrating from v1beta1 to v1
This commit introduces a doc describing how to migrate from v1beta1 to v1. It details changes of fields as well as deprecations.
1 parent af4d0e6 commit 8fea823

File tree

3 files changed

+208
-136
lines changed

3 files changed

+208
-136
lines changed

‎docs/migrating-v1alpha1-to-v1beta1.md‎

Lines changed: 1 addition & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -74,142 +74,7 @@ spec:
7474
```
7575

7676
## Replacing `PipelineResources` with `Tasks`
77-
78-
`PipelineResources` remained in alpha while the other resource kinds were promoted to beta.
79-
Since then, **`PipelineResources` have been deprecated**. We encourage users to use `Tasks` and other replacement
80-
features instead of `PipelineResources`. Read more about the deprecation in [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
81-
82-
_More on the reasoning and what's left to do in
83-
[Why aren't PipelineResources in Beta?](resources.md#why-aren-t-pipelineresources-in-beta)._
84-
85-
To ease migration away from `PipelineResources`
86-
[some types have an equivalent `Task` in the Catalog](#replacing-pipelineresources-with-tasks).
87-
To use these replacement `Tasks` you will need to combine them with your existing `Tasks` via a `Pipeline`.
88-
89-
For example, if you were using this `Task` which was fetching from `git` and building with
90-
`Kaniko`:
91-
92-
```yaml
93-
apiVersion: tekton.dev/v1alpha1
94-
kind: Task
95-
metadata:
96-
name: build-push-kaniko
97-
spec:
98-
inputs:
99-
resources:
100-
- name: workspace
101-
type: git
102-
params:
103-
- name: pathToDockerFile
104-
description: The path to the dockerfile to build
105-
default: /workspace/workspace/Dockerfile
106-
- name: pathToContext
107-
description: The build context used by Kaniko
108-
default: /workspace/workspace
109-
outputs:
110-
resources:
111-
- name: builtImage
112-
type: image
113-
steps:
114-
- name: build-and-push
115-
image: gcr.io/kaniko-project/executor:v0.17.1
116-
env:
117-
- name: "DOCKER_CONFIG"
118-
value: "/tekton/home/.docker/"
119-
args:
120-
- --dockerfile=$(inputs.params.pathToDockerFile)
121-
- --destination=$(outputs.resources.builtImage.url)
122-
- --context=$(inputs.params.pathToContext)
123-
- --oci-layout-path=$(inputs.resources.builtImage.path)
124-
securityContext:
125-
runAsUser: 0
126-
```
127-
128-
To do the same thing with the `git` catalog `Task` and the kaniko `Task` you will need to combine them in a
129-
`Pipeline`.
130-
131-
For example this Pipeline uses the Kaniko and `git` catalog Tasks:
132-
133-
```yaml
134-
apiVersion: tekton.dev/v1beta1
135-
kind: Pipeline
136-
metadata:
137-
name: kaniko-pipeline
138-
spec:
139-
params:
140-
- name: git-url
141-
- name: git-revision
142-
- name: image-name
143-
- name: path-to-image-context
144-
- name: path-to-dockerfile
145-
workspaces:
146-
- name: git-source
147-
tasks:
148-
- name: fetch-from-git
149-
taskRef:
150-
name: git-clone
151-
params:
152-
- name: url
153-
value: $(params.git-url)
154-
- name: revision
155-
value: $(params.git-revision)
156-
workspaces:
157-
- name: output
158-
workspace: git-source
159-
- name: build-image
160-
taskRef:
161-
name: kaniko
162-
params:
163-
- name: IMAGE
164-
value: $(params.image-name)
165-
- name: CONTEXT
166-
value: $(params.path-to-image-context)
167-
- name: DOCKERFILE
168-
value: $(params.path-to-dockerfile)
169-
workspaces:
170-
- name: source
171-
workspace: git-source
172-
# If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
173-
# via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
174-
# able to fully deliver with the Image PipelineResource!
175-
```
176-
177-
_Note that [the `image` `PipelineResource` is gone in this example](#replacing-an-image-resource) (replaced with
178-
a [`result`](tasks.md#emitting-results)), and also that now the `Task` doesn't need to know anything
179-
about where the files come from that it builds from._
180-
181-
### Replacing a `git` resource
182-
183-
You can replace a `git` resource with the [`git-clone` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/git-clone).
184-
185-
### Replacing a `pullrequest` resource
186-
187-
You can replace a `pullrequest` resource with the [`pullrequest` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/pull-request).
188-
189-
### Replacing a `gcs` resource
190-
191-
You can replace a `gcs` resource with the [`gcs` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/gcs-generic).
192-
193-
### Replacing an `image` resource
194-
195-
Since the `image` resource is simply a way to share the digest of a built image with subsequent
196-
`Tasks` in your `Pipeline`, you can use [`Task` results](tasks.md#emitting-results) to
197-
achieve equivalent functionality.
198-
199-
For examples of replacing an `image` resource, see the following Catalog `Tasks`:
200-
201-
- The [Kaniko Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
202-
illustrates how to write the digest of an image to a result.
203-
- The [Buildah Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
204-
illustrates how to accept an image digest as a parameter.
205-
206-
### Replacing a `cluster` resource
207-
208-
You can replace a `cluster` resource with the [`kubeconfig-creator` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/kubeconfig-creator).
209-
210-
### Replacing a `cloudEvent` resource
211-
212-
You can replace a `cloudEvent` resource with the [`CloudEvent` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/cloudevent).
77+
You can replace the `PipelineResources` with `Tasks` following the [reference](https://github.com/tektoncd/pipeline/blob/main/docs/pipelineresources.md)
21378

21479
## Changes to PipelineResources
21580

‎docs/migrating-v1beta1-to-v1.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<!--
2+
---
3+
linkTitle: "Migrating from Tekton v1beta1"
4+
weight: 4000
5+
---
6+
-->
7+
8+
# Migrating From Tekton `v1beta1` to Tekton `v1`
9+
10+
- [Changes to fields](#changes-to-fields)
11+
- [Upgrading `PipelineRun.Timeout` to `PipelineRun.Timeouts`](#upgrading-pipelinerun.timeout-to-pipelinerun.timeouts)
12+
- [Deprecating Resources from Task, TaskRun, Pipeline and PipelineRun](#deprecating-resources-from-task,-taskrun,-pipeline-and-pipelinerun)
13+
- [Replacing `taskRef.bundle` and `pipelineRef.bundle` with Bundle Resolver](#replacing-taskRef.bundle-and-pipelineRef.bundle-with-bundle-resolver)
14+
15+
16+
This document describes the differences between `v1beta1` Tekton entities and their
17+
`v1` counterparts. It also describes the changed fields and the deprecated fields into v1.
18+
## Changes to fields
19+
20+
In Tekton `v1`, the following fields have been changed:
21+
22+
| Old field | Replacement |
23+
| --------- | ----------|
24+
| `pipelineRun.spec.Timeout`| `pipelineRun.spec.timeouts.pipeline` |
25+
| `pipelineRun.spec.taskRunSpecs.taskServiceAccountName` | `pipelineRun.spec.taskRunSpecs.serviceAccountName` |
26+
| `pipelineRun.spec.taskRunSpecs.taskPodTemplate` | `pipelineRun.spec.taskRunSpecs.podTemplate` |
27+
| `taskRun.status.taskResults` | `taskRun.status.results` |
28+
| `pipelineRun.status.pipelineResults` | `pipelineRun.status.results` |
29+
| `taskRun.spec.taskRef.bundle` | `taskRun.spec.taskRef.resolver` |
30+
| `pipelineRun.spec.pipelineRef.bundle` | `pipelineRun.spec.pipelineRef.resolver` |
31+
| `task.spec.resources` | removed from `Task` |
32+
| `taskrun.spec.resources` | removed from `TaskRun` |
33+
| `pipeline.spec.resources` | removed from `Pipeline` |
34+
| `pipelineRun.spec.resources` | removed from `PipelineRun` |
35+
36+
## Deprecating `resources` from Task, TaskRun, Pipeline and PipelineRun
37+
`PipelineResources` are deprecated, and the `resources` fields of Task, TaskRun, Pipeline and PipelineRun has been removed. Please use `Tasks` instead. For more information, see [Replacing PipelineResources](https://github.com/tektoncd/pipeline/blob/main/docs/pipelineresources.md)
38+
39+
## Replacing `taskRef.bundle` and `pipelineRef.bundle` with Bundle Resolver
40+
Bundle resolver in remote resolution should be used instead of `taskRun.spec.taskRef.bundle` and `pipelineRun.spec.pipelineRef.bundle`.
41+
42+
The [`enable-bundles-resolver`](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#customizing-the-pipelines-controller-behavior) feature flag must be enabled to use this feature.
43+
44+
```yaml
45+
apiVersion: tekton.dev/v1beta1
46+
kind: Taskrun
47+
spec:
48+
taskRef:
49+
name: example-task
50+
bundle: docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828
51+
---
52+
apiVersion: tekton.dev/v1beta1
53+
kind: Taskrun
54+
spec:
55+
taskRef:
56+
resolver: bundles
57+
params:
58+
- name: bundle
59+
value: docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828
60+
- name: name
61+
value: taskName
62+
- name: kind
63+
value: Task
64+
```
65+
66+
## Replacing ClusterTask with Remote Resolution
67+
`ClusterTask` is deprecated. Please use the `cluster` resolver instead, for example: ....
68+
# TODO add example after #5404 is merged
69+
70+
For more information, see [Remote resolution](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resource-resolution.md).

‎docs/pipelineresources.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
## Replacing `PipelineResources` with `Tasks`
2+
3+
`PipelineResources` remained in alpha while the other resource kinds were promoted to beta.
4+
Since then, **`PipelineResources` have been deprecated**. We encourage users to use `Tasks` and other replacement
5+
features instead of `PipelineResources`. Read more about the deprecation in [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
6+
7+
_More on the reasoning and what's left to do in
8+
[Why aren't PipelineResources in Beta?](resources.md#why-aren-t-pipelineresources-in-beta)._
9+
10+
To ease migration away from `PipelineResources`
11+
[some types have an equivalent `Task` in the Catalog](#replacing-pipelineresources-with-tasks).
12+
To use these replacement `Tasks` you will need to combine them with your existing `Tasks` via a `Pipeline`.
13+
14+
For example, if you were using this `Task` which was fetching from `git` and building with
15+
`Kaniko`:
16+
17+
```yaml
18+
apiVersion: tekton.dev/v1alpha1
19+
kind: Task
20+
metadata:
21+
name: build-push-kaniko
22+
spec:
23+
inputs:
24+
resources:
25+
- name: workspace
26+
type: git
27+
params:
28+
- name: pathToDockerFile
29+
description: The path to the dockerfile to build
30+
default: /workspace/workspace/Dockerfile
31+
- name: pathToContext
32+
description: The build context used by Kaniko
33+
default: /workspace/workspace
34+
outputs:
35+
resources:
36+
- name: builtImage
37+
type: image
38+
steps:
39+
- name: build-and-push
40+
image: gcr.io/kaniko-project/executor:v0.17.1
41+
env:
42+
- name: "DOCKER_CONFIG"
43+
value: "/tekton/home/.docker/"
44+
args:
45+
- --dockerfile=$(inputs.params.pathToDockerFile)
46+
- --destination=$(outputs.resources.builtImage.url)
47+
- --context=$(inputs.params.pathToContext)
48+
- --oci-layout-path=$(inputs.resources.builtImage.path)
49+
securityContext:
50+
runAsUser: 0
51+
```
52+
53+
To do the same thing with the `git` catalog `Task` and the kaniko `Task` you will need to combine them in a
54+
`Pipeline`.
55+
56+
For example this Pipeline uses the Kaniko and `git` catalog Tasks:
57+
58+
```yaml
59+
apiVersion: tekton.dev/v1beta1
60+
kind: Pipeline
61+
metadata:
62+
name: kaniko-pipeline
63+
spec:
64+
params:
65+
- name: git-url
66+
- name: git-revision
67+
- name: image-name
68+
- name: path-to-image-context
69+
- name: path-to-dockerfile
70+
workspaces:
71+
- name: git-source
72+
tasks:
73+
- name: fetch-from-git
74+
taskRef:
75+
name: git-clone
76+
params:
77+
- name: url
78+
value: $(params.git-url)
79+
- name: revision
80+
value: $(params.git-revision)
81+
workspaces:
82+
- name: output
83+
workspace: git-source
84+
- name: build-image
85+
taskRef:
86+
name: kaniko
87+
params:
88+
- name: IMAGE
89+
value: $(params.image-name)
90+
- name: CONTEXT
91+
value: $(params.path-to-image-context)
92+
- name: DOCKERFILE
93+
value: $(params.path-to-dockerfile)
94+
workspaces:
95+
- name: source
96+
workspace: git-source
97+
# If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
98+
# via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
99+
# able to fully deliver with the Image PipelineResource!
100+
```
101+
102+
_Note that [the `image` `PipelineResource` is gone in this example](#replacing-an-image-resource) (replaced with
103+
a [`result`](tasks.md#emitting-results)), and also that now the `Task` doesn't need to know anything
104+
about where the files come from that it builds from._
105+
106+
### Replacing a `git` resource
107+
108+
You can replace a `git` resource with the [`git-clone` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/git-clone).
109+
110+
### Replacing a `pullrequest` resource
111+
112+
You can replace a `pullrequest` resource with the [`pullrequest` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/pull-request).
113+
114+
### Replacing a `gcs` resource
115+
116+
You can replace a `gcs` resource with the [`gcs` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/gcs-generic).
117+
118+
### Replacing an `image` resource
119+
120+
Since the `image` resource is simply a way to share the digest of a built image with subsequent
121+
`Tasks` in your `Pipeline`, you can use [`Task` results](tasks.md#emitting-results) to
122+
achieve equivalent functionality.
123+
124+
For examples of replacing an `image` resource, see the following Catalog `Tasks`:
125+
126+
- The [Kaniko Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
127+
illustrates how to write the digest of an image to a result.
128+
- The [Buildah Catalog `Task`](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
129+
illustrates how to accept an image digest as a parameter.
130+
131+
### Replacing a `cluster` resource
132+
133+
You can replace a `cluster` resource with the [`kubeconfig-creator` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/kubeconfig-creator).
134+
135+
### Replacing a `cloudEvent` resource
136+
137+
You can replace a `cloudEvent` resource with the [`CloudEvent` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/cloudevent).

0 commit comments

Comments
 (0)