Doc about migrating from v1beta1 to v1

docs/migrating-v1alpha1-to-v1beta1.md

@@ -74,142 +74,7 @@ spec:
 ```
 
 ## Replacing `PipelineResources` with `Tasks`
-
-`PipelineResources` remained in alpha while the other resource kinds were promoted to beta.
-Since then, **`PipelineResources` have been deprecated**. We encourage users to use `Tasks` and other replacement 
-features instead of `PipelineResources`. Read more about the deprecation in [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
-
-_More on the reasoning and what's left to do in
-[Why aren't PipelineResources in Beta?](resources.md#why-aren-t-pipelineresources-in-beta)._
-
-To ease migration away from `PipelineResources`
-[some types have an equivalent `Task` in the Catalog](#replacing-pipelineresources-with-tasks).
-To use these replacement `Tasks` you will need to combine them with your existing `Tasks` via a `Pipeline`.
-
-For example, if you were using this `Task` which was fetching from `git` and building with
-`Kaniko`:
-
-```yaml
-apiVersion: tekton.dev/v1alpha1
-kind: Task
-metadata:
-  name: build-push-kaniko
-spec:
-  inputs:
-    resources:
-      - name: workspace
-        type: git
-    params:
-      - name: pathToDockerFile
-        description: The path to the dockerfile to build
-        default: /workspace/workspace/Dockerfile
-      - name: pathToContext
-        description: The build context used by Kaniko
-        default: /workspace/workspace
-  outputs:
-    resources:
-      - name: builtImage
-        type: image
-  steps:
-    - name: build-and-push
-      image: gcr.io/kaniko-project/executor:v0.17.1
-      env:
-        - name: "DOCKER_CONFIG"
-          value: "/tekton/home/.docker/"
-      args:
-        - --dockerfile=$(inputs.params.pathToDockerFile)
-        - --destination=$(outputs.resources.builtImage.url)
-        - --context=$(inputs.params.pathToContext)
-        - --oci-layout-path=$(inputs.resources.builtImage.path)
-      securityContext:
-        runAsUser: 0
-```
-
-To do the same thing with the `git` catalog `Task` and the kaniko `Task` you will need to combine them in a
-`Pipeline`.
-
-For example this Pipeline uses the Kaniko and `git` catalog Tasks:
-
-```yaml
-apiVersion: tekton.dev/v1beta1
-kind: Pipeline
-metadata:
-  name: kaniko-pipeline
-spec:
-  params:
-    - name: git-url
-    - name: git-revision
-    - name: image-name
-    - name: path-to-image-context
-    - name: path-to-dockerfile
-  workspaces:
-    - name: git-source
-  tasks:
-    - name: fetch-from-git
-      taskRef:
-        name: git-clone
-      params:
-        - name: url
-          value: $(params.git-url)
-        - name: revision
-          value: $(params.git-revision)
-      workspaces:
-        - name: output
-          workspace: git-source
-    - name: build-image
-      taskRef:
-        name: kaniko
-      params:
-        - name: IMAGE
-          value: $(params.image-name)
-        - name: CONTEXT
-          value: $(params.path-to-image-context)
-        - name: DOCKERFILE
-          value: $(params.path-to-dockerfile)
-      workspaces:
-        - name: source
-          workspace: git-source
-  # If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
-  # via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
-  # able to fully deliver with the Image PipelineResource!
-```
-
-_Note that [the `image` `PipelineResource` is gone in this example](#replacing-an-image-resource) (replaced with
-a [`result`](tasks.md#emitting-results)), and also that now the `Task` doesn't need to know anything
-about where the files come from that it builds from._
-
-### Replacing a `git` resource
-
-You can replace a `git` resource with the [`git-clone` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/git-clone).
-
-### Replacing a `pullrequest` resource
-
-You can replace a `pullrequest` resource with the [`pullrequest` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/pull-request).
-
-### Replacing a `gcs` resource
-
-You can replace a `gcs` resource with the [`gcs` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/gcs-generic).
-
-### Replacing an `image` resource
-
-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#emitting-results) to
-achieve equivalent functionality.
-
-For examples of replacing an `image` resource, see the following Catalog `Tasks`:
-
-- 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.
-
-### Replacing a `cluster` resource
-
-You can replace a `cluster` resource with the [`kubeconfig-creator` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/kubeconfig-creator).
-
-### Replacing a `cloudEvent` resource
-
-You can replace a `cloudEvent` resource with the [`CloudEvent` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/cloudevent).
+You can replace the `PipelineResources` with `Tasks` following the [reference](https://github.com/tektoncd/pipeline/blob/main/docs/pipelineresources.md)
 
 ## Changes to PipelineResources
 

docs/migrating-v1beta1-to-v1.md

@@ -0,0 +1,70 @@
+<!--
+---
+linkTitle: "Migrating from Tekton v1beta1"
+weight: 4000
+---
+-->
+
+# Migrating From Tekton `v1beta1` to Tekton `v1`
+
+- [Changes to fields](#changes-to-fields)
+- [Upgrading `PipelineRun.Timeout` to `PipelineRun.Timeouts`](#upgrading-pipelinerun.timeout-to-pipelinerun.timeouts)
+- [Deprecating Resources from Task, TaskRun, Pipeline and PipelineRun](#deprecating-resources-from-task,-taskrun,-pipeline-and-pipelinerun)
+- [Replacing `taskRef.bundle` and `pipelineRef.bundle` with Bundle Resolver](#replacing-taskRef.bundle-and-pipelineRef.bundle-with-bundle-resolver)
+
+
+This document describes the differences between `v1beta1` Tekton entities and their
+`v1` counterparts. It also describes the changed fields and the deprecated fields into v1.
+## Changes to fields
+
+In Tekton `v1`, the following fields have been changed:
+
+| Old field | Replacement |
+| --------- | ----------|
+| `pipelineRun.spec.Timeout`| `pipelineRun.spec.timeouts.pipeline` |
+| `pipelineRun.spec.taskRunSpecs.taskServiceAccountName` | `pipelineRun.spec.taskRunSpecs.serviceAccountName` |
+| `pipelineRun.spec.taskRunSpecs.taskPodTemplate` | `pipelineRun.spec.taskRunSpecs.podTemplate` |
+| `taskRun.status.taskResults` | `taskRun.status.results` |
+| `pipelineRun.status.pipelineResults` | `pipelineRun.status.results` |
+| `taskRun.spec.taskRef.bundle` | `taskRun.spec.taskRef.resolver` |
+| `pipelineRun.spec.pipelineRef.bundle` | `pipelineRun.spec.pipelineRef.resolver` |
+| `task.spec.resources` | removed from `Task` |
+| `taskrun.spec.resources` | removed from `TaskRun` |
+| `pipeline.spec.resources` | removed from `Pipeline` |
+| `pipelineRun.spec.resources` | removed from `PipelineRun` |
+
+## Deprecating `resources` from Task, TaskRun, Pipeline and PipelineRun
+`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)
+
+## Replacing `taskRef.bundle` and `pipelineRef.bundle` with Bundle Resolver
+Bundle resolver in remote resolution should be used instead of `taskRun.spec.taskRef.bundle` and `pipelineRun.spec.pipelineRef.bundle`.
+
+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.
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: Taskrun
+spec:
+  taskRef:
+    name: example-task
+    bundle: python:3-alpine
+---
+apiVersion: tekton.dev/v1beta1
+kind: Taskrun
+spec:
+  taskRef:
+    resolver: bundles
+    params:
+    - name: bundle
+      value: python:3-alpine
+    - name: name
+      value: taskName
+    - name: kind
+      value: Task
+```
+
+## Replacing ClusterTask with Remote Resolution
+`ClusterTask` is deprecated. Please use the `cluster` resolver instead, for example: .... 
+# TODO add example after #5404 is merged
+
+For more information, see [Remote resolution](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resource-resolution.md).

docs/pipelineresources.md

@@ -0,0 +1,137 @@
+## Replacing `PipelineResources` with `Tasks`
+
+`PipelineResources` remained in alpha while the other resource kinds were promoted to beta.
+Since then, **`PipelineResources` have been deprecated**. We encourage users to use `Tasks` and other replacement 
+features instead of `PipelineResources`. Read more about the deprecation in [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
+_More on the reasoning and what's left to do in
+[Why aren't PipelineResources in Beta?](resources.md#why-aren-t-pipelineresources-in-beta)._
+
+To ease migration away from `PipelineResources`
+[some types have an equivalent `Task` in the Catalog](#replacing-pipelineresources-with-tasks).
+To use these replacement `Tasks` you will need to combine them with your existing `Tasks` via a `Pipeline`.
+
+For example, if you were using this `Task` which was fetching from `git` and building with
+`Kaniko`:
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: build-push-kaniko
+spec:
+  inputs:
+    resources:
+      - name: workspace
+        type: git
+    params:
+      - name: pathToDockerFile
+        description: The path to the dockerfile to build
+        default: /workspace/workspace/Dockerfile
+      - name: pathToContext
+        description: The build context used by Kaniko
+        default: /workspace/workspace
+  outputs:
+    resources:
+      - name: builtImage
+        type: image
+  steps:
+    - name: build-and-push
+      image: gcr.io/kaniko-project/executor:v0.17.1
+      env:
+        - name: "DOCKER_CONFIG"
+          value: "/tekton/home/.docker/"
+      args:
+        - --dockerfile=$(inputs.params.pathToDockerFile)
+        - --destination=$(outputs.resources.builtImage.url)
+        - --context=$(inputs.params.pathToContext)
+        - --oci-layout-path=$(inputs.resources.builtImage.path)
+      securityContext:
+        runAsUser: 0
+```
+
+To do the same thing with the `git` catalog `Task` and the kaniko `Task` you will need to combine them in a
+`Pipeline`.
+
+For example this Pipeline uses the Kaniko and `git` catalog Tasks:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: Pipeline
+metadata:
+  name: kaniko-pipeline
+spec:
+  params:
+    - name: git-url
+    - name: git-revision
+    - name: image-name
+    - name: path-to-image-context
+    - name: path-to-dockerfile
+  workspaces:
+    - name: git-source
+  tasks:
+    - name: fetch-from-git
+      taskRef:
+        name: git-clone
+      params:
+        - name: url
+          value: $(params.git-url)
+        - name: revision
+          value: $(params.git-revision)
+      workspaces:
+        - name: output
+          workspace: git-source
+    - name: build-image
+      taskRef:
+        name: kaniko
+      params:
+        - name: IMAGE
+          value: $(params.image-name)
+        - name: CONTEXT
+          value: $(params.path-to-image-context)
+        - name: DOCKERFILE
+          value: $(params.path-to-dockerfile)
+      workspaces:
+        - name: source
+          workspace: git-source
+  # If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
+  # via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
+  # able to fully deliver with the Image PipelineResource!
+```
+
+_Note that [the `image` `PipelineResource` is gone in this example](#replacing-an-image-resource) (replaced with
+a [`result`](tasks.md#emitting-results)), and also that now the `Task` doesn't need to know anything
+about where the files come from that it builds from._
+
+### Replacing a `git` resource
+
+You can replace a `git` resource with the [`git-clone` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/git-clone).
+
+### Replacing a `pullrequest` resource
+
+You can replace a `pullrequest` resource with the [`pullrequest` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/pull-request).
+
+### Replacing a `gcs` resource
+
+You can replace a `gcs` resource with the [`gcs` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/gcs-generic).
+
+### Replacing an `image` resource
+
+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#emitting-results) to
+achieve equivalent functionality.
+
+For examples of replacing an `image` resource, see the following Catalog `Tasks`:
+
+- 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.
+
+### Replacing a `cluster` resource
+
+You can replace a `cluster` resource with the [`kubeconfig-creator` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/kubeconfig-creator).
+
+### Replacing a `cloudEvent` resource
+
+You can replace a `cloudEvent` resource with the [`CloudEvent` Catalog `Task`](https://github.com/tektoncd/catalog/tree/main/task/cloudevent).