Deprecate of PipelineResources

When we [released Tekton Pipelines Beta in March 2020](https://github.com/tektoncd/pipeline/releases/tag/v0.11.0), we [decided not to make `PipelineResources` Beta](https://github.com/tektoncd/pipeline/blob/e76d4132ab2ecfbedc45a964f08a01022e2d4c14/docs/resources.md#why-arent-pipelineresources-in-beta). In [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md), we decided to officially deprecate `PipelineResources`. This change announces, documents and warns about the deprecation of `PipelineResources`. Follow-on work includes: - Replace `PipelineResources` from the tutorial - #3705 - Replace `PipelineResources` from the examples and documentation - #4375 - Continue updating the documentation as work progresses on [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md) and features replacing `PipelineResources` become available Closes #4344.
tektoncd · Nov 16, 2021 · 5997596 · 5997596
1 parent 46d332c
commit 5997596
Show file tree

Hide file tree

Showing 31 changed files with 190 additions and 39 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -43,7 +43,7 @@ Tekton Pipelines defines the following entities:
     <td>Instantiates a <code>Pipeline</code> for execution with specific inputs, outputs, and execution parameters.</td>
   </tr>
   <tr>
-    <td><code>PipelineResource</code></td>
+    <td><code>PipelineResource (Deprecated)</code></td>
     <td>Defines locations for inputs ingested and outputs produced by the steps in <code>Tasks</code>.</td>
   </tr>
   <tr>

diff --git a/docs/auth.md b/docs/auth.md
@@ -162,6 +162,11 @@ before executing any `Steps` in the `Run`, Tekton creates a `~/.gitconfig` file
 specified in the `Secret`. When the `Steps` execute, Tekton uses those credentials to retrieve
 `PipelineResources` specified in the `Run`.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 Note: Github deprecated basic authentication with username and password. You can still use basic authentication, but you wil need to use a personal access token instead of the cleartext password in the following example. You can find out how to create such a token on the [Github documentation site](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
 
 1. In `secret.yaml`, define a `Secret` that specifies the username and password that you want Tekton
@@ -235,6 +240,11 @@ before executing any `Steps` in the `Run`, Tekton creates a `~/.ssh/config` file
 specified in the `Secret`. When the `Steps` execute, Tekton uses this key to retrieve `PipelineResources`
 specified in the `Run`.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 1. In `secret.yaml`, define a `Secret` that specifies your SSH private key:
 
    ```yaml
@@ -314,6 +324,11 @@ You can specify a custom SSH port in your `Secret`. In the example below,
 any `PipelineResource` referencing a repository at `example.com` will connect
 to it on port 2222.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 ```
 apiVersion: v1
 kind: Secret
@@ -354,6 +369,11 @@ In the example below, before executing any `Steps` in the `Run`, Tekton creates
 the credentials specified in the `Secret`. When the `Steps` execute, Tekton uses those credentials when retrieving
 `PipelineResources` specified in the `Run`.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 1. In `secret.yaml`, define a `Secret` that specifies the username and password that you want Tekton
    to use to access the target Docker registry:
 

diff --git a/docs/conditions.md b/docs/conditions.md
@@ -80,6 +80,11 @@ branch name doesn't collide with any of the specified protected branch names.
 
 ### Specifying `Resources`
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 You can specify input [`PipelineResources`](resources.md) in your `Condition` definition to 
 provide the `Condition's` container step with data or context necessary to run the evaluation logic.
 

diff --git a/docs/deprecations.md b/docs/deprecations.md
@@ -17,13 +17,14 @@ being deprecated.
 
 ## Deprecation Table
 
-| Feature Being Deprecated                                                                                                                      | Deprecation Announcement                                                     | [API Compatibility Policy](https://github.com/tektoncd/pipeline/tree/main/api_compatibility_policy.md) | Earliest Date or Release of Removal |
-| ------------------------                                                                                                                      | ------------------------                                                     | -------------------------------------------------------------------------------------------------------- | ------------------------            |
-| [`tekton.dev/task` label on ClusterTasks](https://github.com/tektoncd/pipeline/issues/2533)                                                   | [v0.12.0](https://github.com/tektoncd/pipeline/releases/tag/v0.12.0)         | Beta                                                                                                     | January 30 2021                     |
-| [The `TaskRun.Status.ResourceResults.ResourceRef` field is deprecated and will be removed.](https://github.com/tektoncd/pipeline/issues/2694) | [v0.14.0](https://github.com/tektoncd/pipeline/releases/tag/v0.14.0)         | Beta                                                                                                     | April 30 2021                       |
-| [The `PipelineRun.Spec.ServiceAccountNames` field is deprecated and will be removed.](https://github.com/tektoncd/pipeline/issues/2614)       | [v0.15.0](https://github.com/tektoncd/pipeline/releases/tag/v0.15.0)         | Beta                                                                                                     | May 15 2021                         |
-| [`Conditions` CRD is deprecated and will be removed. Use `when` expressions instead.](https://github.com/tektoncd/community/blob/main/teps/0007-conditions-beta.md)       | [v0.16.0](https://github.com/tektoncd/pipeline/releases/tag/v0.16.0)         | Alpha                                                                                                     | Nov 02 2020                         |
-| [The `disable-home-env-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/2013)                                     | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0)         | Beta                                                                                                     | February 10 2022                    |
-| [The `disable-working-dir-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/1836)                                  | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0)         | Beta                                                                                                     | February 10 2022                    |
-| [The `scope-when-expressions-to-task` flag will be flipped from "false" to "true"](https://github.com/tektoncd/pipeline/issues/1836)          | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0)         | Beta                                                                                                     | February 10 2022                    |
-| [The `scope-when-expressions-to-task` flag will be removed](https://github.com/tektoncd/pipeline/issues/1836)                                 | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0)         | Beta                                                                                                     | March 10 2022                       |
+| Feature Being Deprecated                                                                                                                                            | Deprecation Announcement                                             | [API Compatibility Policy](https://github.com/tektoncd/pipeline/tree/main/api_compatibility_policy.md) | Earliest Date or Release of Removal |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
+| [`tekton.dev/task` label on ClusterTasks](https://github.com/tektoncd/pipeline/issues/2533)                                                                         | [v0.12.0](https://github.com/tektoncd/pipeline/releases/tag/v0.12.0) | Beta                                                                                                   | January 30 2021                     |
+| [The `TaskRun.Status.ResourceResults.ResourceRef` field is deprecated and will be removed.](https://github.com/tektoncd/pipeline/issues/2694)                       | [v0.14.0](https://github.com/tektoncd/pipeline/releases/tag/v0.14.0) | Beta                                                                                                   | April 30 2021                       |
+| [The `PipelineRun.Spec.ServiceAccountNames` field is deprecated and will be removed.](https://github.com/tektoncd/pipeline/issues/2614)                             | [v0.15.0](https://github.com/tektoncd/pipeline/releases/tag/v0.15.0) | Beta                                                                                                   | May 15 2021                         |
+| [`Conditions` CRD is deprecated and will be removed. Use `when` expressions instead.](https://github.com/tektoncd/community/blob/main/teps/0007-conditions-beta.md) | [v0.16.0](https://github.com/tektoncd/pipeline/releases/tag/v0.16.0) | Alpha                                                                                                  | Nov 02 2020                         |
+| [The `disable-home-env-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/2013)                                                           | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | Beta                                                                                                   | February 10 2022                    |
+| [The `disable-working-dir-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/1836)                                                        | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | Beta                                                                                                   | February 10 2022                    |
+| [The `scope-when-expressions-to-task` flag will be flipped from "false" to "true"](https://github.com/tektoncd/pipeline/issues/1836)                                | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0) | Beta                                                                                                   | February 10 2022                    |
+| [The `scope-when-expressions-to-task` flag will be removed](https://github.com/tektoncd/pipeline/issues/1836)                                                       | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0) | Beta                                                                                                   | March 10 2022                       |
+| [`PipelineResources` are deprecated.](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md)                                     | [v0.30.0](https://github.com/tektoncd/pipeline/releases/tag/v0.30.0) | Alpha                                                                                                  | Dec 20 2021                         |
diff --git a/docs/developers/README.md b/docs/developers/README.md
@@ -9,6 +9,11 @@ channel for training and tutorials on Tekton!
 
 ## How are resources shared between tasks
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 `PipelineRun` uses PVC to share `PipelineResources` between tasks. PVC volume is
 mounted on path `/pvc` by PipelineRun.
 

diff --git a/docs/developers/local-setup.md b/docs/developers/local-setup.md
@@ -36,6 +36,11 @@ You must reconfigure any `image` resource definitions in your `PipelineResources
 - Set your applications (such as deployment definitions) to push to
   `localhost:5000/myregistry/<image name>`.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 ### Reconfigure logging
 
 - You can keep your logs in memory only without sending them to a logging service
@@ -69,6 +74,11 @@ The `registry-aliases` addon will create several aliases for the minikube regist
 
 If you wish to use a different image URL, you can add the appropriate line to minikube's `/etc/hosts`.
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 ### Reconfigure logging
 
 See the information in the "Docker for Desktop" section
diff --git a/docs/install.md b/docs/install.md
@@ -147,16 +147,15 @@ should take a look at [Red Hat CodeReady Containers](https://github.com/code-rea
 
 ## Configuring PipelineResource storage
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> For storage, consider using [`Workspaces`](workspaces.md) with [`VolumeClaimTemplates`](https://github.com/tektoncd/pipeline/blob/main/docs/workspaces.md#volumeclaimtemplate)
+> to automatically provision and manage Persistent Volume Claims (PVCs). Read more in [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 PipelineResources are one of the ways that Tekton passes data between Tasks. If you intend to
 use PipelineResources in your Pipelines then you'll need to configure a storage location
 for that data to be put so that it can be shared between Tasks in the Pipeline.
 
-**Note:** Pipeline Resources are in alpha and are currently undergoing considerable redesign. Therefore
-this storage configuration is possibly going to change in future. Writing Tasks and Pipelines today that rely
-on this feature may mean you'll need to rewrite those Tasks and Pipelines when the redesign is complete. See
-the [explanation for the redesign in the PipelineResources doc](./resources.md#why-arent-pipelineresources-in-beta)
-and [issue 1673](https://github.com/tektoncd/pipeline/issues/1673) to follow along with the redesign work.
-
 The storage options available for sharing PipelineResources between Tasks in a Pipeline are:
 
   * [A persistent volume](#configuring-a-persistent-volume)

diff --git a/docs/migrating-from-knative-build.md b/docs/migrating-from-knative-build.md
@@ -41,6 +41,11 @@ Follow the guidelines below when converting your Knative Build entities to Tekto
   can do so either by referencing an existing `PipelineResource` using the `resourceRef` field or by embedding
   a complete `PipelineResource` definition using the [`resourceSpec`](taskruns.md#specifying-resources) field.
 
+  > :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+  >
+  > Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+  > and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 * Containers that execute the `Steps` in your `Tasks` must now abide by Tekton's [container contract](container-contract.md)
   and are now serialized without relying on init containers. Because of this, we highly recommend
   that for each `Step` within your `Task` you specify a `command` value instead of an `entrypoint` and `args` pair.

diff --git a/docs/migrating-v1alpha1-to-v1beta1.md b/docs/migrating-v1alpha1-to-v1beta1.md
@@ -73,14 +73,11 @@ spec:
       value: https://example.com/foo.json
 ```
 
-## Replacing `PipelineResources` with Tasks
+## Replacing `PipelineResources` with `Tasks`
 
-`PipelineResources` are remaining in alpha while the other resource kinds are
-promoted to beta.
-
-At some point this feature in its current form could be redesigned, replaced, deprecated or
-removed entirely, and until this has been resolved, we encourage people to use `Tasks` instead of
-`PipelineResources` when they can.
+`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-arent-pipelineresources-in-beta)._

diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md
@@ -167,6 +167,11 @@ so long as the artifact adheres to the [contract](tekton-bundle-contracts.md).
 
 ### Specifying `Resources`
 
+> :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).**
+>
+> Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
+> and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
+
 A `Pipeline` requires [`PipelineResources`](resources.md) to provide inputs and store outputs
 for the `Tasks` that comprise it. You must provision those resources in the `resources` field
 in the `spec` section of the `PipelineRun` definition.