From e5a8584061c2ec7a720fbf4976d87188e752586a Mon Sep 17 00:00:00 2001 From: Lee Bernick Date: Fri, 10 Jun 2022 20:43:56 +0000 Subject: [PATCH] Cut PipelineResources from some examples This commit replaces PipelineResources with workspaces in documentation examples not related to those features. PipelineResources are deprecated, so our documentation shouldn't be using them as examples unless it is necessary. It also cuts the example related to reusing a Task with different PipelineResources (as the recommended way to do this would be with params). Lastly, it encourages users to reference the community catalog, rather than examples tests, for examples of Tasks, because many examples tests either make use of PipelineResources or aren't realistic. --- docs/pipelines.md | 32 +++----- docs/taskruns.md | 197 ++++++++-------------------------------------- docs/tasks.md | 39 ++++----- 3 files changed, 59 insertions(+), 209 deletions(-) diff --git a/docs/pipelines.md b/docs/pipelines.md index 86d1f7aa5eb..841465b26de 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -83,7 +83,7 @@ A `Pipeline` definition supports the following fields: - [`tasks`](#adding-tasks-to-the-pipeline) - Specifies the `Tasks` that comprise the `Pipeline` and the details of their execution. - Optional: - - [`resources`](#specifying-resources) - **alpha only** Specifies + - [`resources`](#specifying-resources) - **deprecated** Specifies [`PipelineResources`](resources.md) needed or created by the `Tasks` comprising the `Pipeline`. - [`params`](#specifying-parameters) - Specifies the `Parameters` that the `Pipeline` requires. - [`workspaces`](#specifying-workspaces) - Specifies a set of Workspaces that the `Pipeline` requires. @@ -492,22 +492,23 @@ to indicate that `test-app` must run before it, regardless of the order in which they are referenced in the `Pipeline` definition. ```yaml +workspaces: +- name: source +tasks: - name: test-app taskRef: name: make-test - resources: - inputs: - - name: workspace - resource: my-repo + workspaces: + - name: source + workspace: source - name: build-app taskRef: name: kaniko-build runAfter: - test-app - resources: - inputs: - - name: workspace - resource: my-repo + workspaces: + - name: source + workspace: source ``` > :warning: **`PipelineResources` are [deprecated](deprecations.md#deprecation-table).** @@ -1004,6 +1005,7 @@ This is done using: For example, the `Pipeline` defined as follows ```yaml +tasks: - name: lint-repo taskRef: name: pylint @@ -1119,9 +1121,6 @@ e.g. a mount point for credentials held in Secrets. To support that requirement, ```yaml spec: - resources: - - name: app-git - type: git workspaces: - name: shared-workspace tasks: @@ -1131,10 +1130,6 @@ spec: workspaces: - name: shared-workspace workspace: shared-workspace - resources: - inputs: - - name: app-git - resource: app-git finally: - name: cleanup-workspace taskRef: @@ -1144,11 +1139,6 @@ spec: workspace: shared-workspace ``` -> :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). - ### Specifying `Parameters` in `finally` tasks Similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters) in `finally` tasks: diff --git a/docs/taskruns.md b/docs/taskruns.md index 5da4f98a1af..724c9e1ee43 100644 --- a/docs/taskruns.md +++ b/docs/taskruns.md @@ -96,14 +96,13 @@ You can also embed the desired `Task` definition directly in the `TaskRun` using ```yaml spec: taskSpec: - resources: - inputs: - - name: workspace - type: git + workspaces: + - name: source steps: - name: build-and-push image: gcr.io/kaniko-project/executor:v0.17.1 # specifying DOCKER_CONFIG is required to allow kaniko to detect docker credential + workingDir: $(workspaces.source.path) env: - name: "DOCKER_CONFIG" value: "/tekton/home/.docker/" @@ -685,33 +684,21 @@ To better understand `TaskRuns`, study the following code examples: ### Example `TaskRun` with a referenced `Task` In this example, a `TaskRun` named `read-repo-run` invokes and executes an existing -`Task` named `read-task`. This `Task` uses a git input resource that the `TaskRun` -references as `go-example-git`. +`Task` named `read-task`. This `Task` reads the repository from the +"input" `workspace`. ```yaml -apiVersion: tekton.dev/v1alpha1 -kind: PipelineResource -metadata: - name: go-example-git -spec: - type: git - params: - - name: url - value: https://github.com/pivotal-nader-ziada/gohelloworld ---- apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: read-task spec: - resources: - inputs: - - name: workspace - type: git + workspaces: + - name: input steps: - name: readme image: ubuntu - script: cat workspace/README.md + script: cat $(workspaces.input.path)/README.md --- apiVersion: tekton.dev/v1beta1 kind: TaskRun @@ -720,11 +707,11 @@ metadata: spec: taskRef: name: read-task - resources: - inputs: - - name: workspace - resourceRef: - name: go-example-git + workspaces: + - name: input + persistentVolumeClaim: + claimName: mypvc + subPath: my-subdir ``` ### Example `TaskRun` with an embedded `Task` @@ -733,34 +720,22 @@ In this example, a `TaskRun` named `build-push-task-run-2` directly executes a `Task` from its definition embedded in the `TaskRun's` `taskSpec` field: ```yaml -apiVersion: tekton.dev/v1alpha1 -kind: PipelineResource -metadata: - name: go-example-git -spec: - type: git - params: - - name: url - value: https://github.com/pivotal-nader-ziada/gohelloworld ---- apiVersion: tekton.dev/v1beta1 kind: TaskRun metadata: name: build-push-task-run-2 spec: - resources: - inputs: - - name: workspace - resourceRef: - name: go-example-git + workspaces: + - name: source + persistentVolumeClaim: + claimName: my-pvc taskSpec: - resources: - inputs: - - name: workspace - type: git + workspaces: + - name: source steps: - name: build-and-push image: gcr.io/kaniko-project/executor:v0.17.1 + workingDir: $(workspaces.source.path) # specifying DOCKER_CONFIG is required to allow kaniko to detect docker credential env: - name: "DOCKER_CONFIG" @@ -792,106 +767,6 @@ spec: value: https://github.com/pivotal-nader-ziada/gohelloworld ``` -### Example of Reusing a `Task` - -The following example illustrates the reuse of the same `Task`. Below, you can see -several `TaskRuns` that instantiate a `Task` named `dockerfile-build-and-push`. The -`TaskRuns` reference different `Resources` as their inputs. -See [Building and pushing a Docker image](tasks.md#building-and-pushing-a-docker-image) -for the full definition of this example `Task.` - -This `TaskRun` builds `mchmarny/rester-tester`: - -```yaml -# This is the referenced PipelineResource -metadata: - name: mchmarny-repo -spec: - type: git - params: - - name: url - value: https://github.com/mchmarny/rester-tester.git -``` - -```yaml -# This is the TaskRun -spec: - taskRef: - name: dockerfile-build-and-push - params: - - name: IMAGE - value: gcr.io/my-project/rester-tester - resources: - inputs: - - name: workspace - resourceRef: - name: mchmarny-repo -``` - -This `TaskRun` builds the `wget` builder from `googlecloudplatform/cloud-builder`: - -```yaml -# This is the referenced PipelineResource -metadata: - name: cloud-builder-repo -spec: - type: git - params: - - name: url - value: https://github.com/googlecloudplatform/cloud-builders.git -``` - -```yaml -# This is the TaskRun -spec: - taskRef: - name: dockerfile-build-and-push - params: - - name: IMAGE - value: gcr.io/my-project/wget - # Optional override to specify the subdirectory containing the Dockerfile - - name: DIRECTORY - value: /workspace/wget - resources: - inputs: - - name: workspace - resourceRef: - name: cloud-builder-repo -``` - -This `TaskRun` builds the `docker` builder from `googlecloudplatform/cloud-builder` with `17.06.1`: - -```yaml -# This is the referenced PipelineResource -metadata: - name: cloud-builder-repo -spec: - type: git - params: - - name: url - value: https://github.com/googlecloudplatform/cloud-builders.git -``` - -```yaml -# This is the TaskRun -spec: - taskRef: - name: dockerfile-build-and-push - params: - - name: IMAGE - value: gcr.io/my-project/docker - # Optional overrides - - name: DIRECTORY - value: /workspace/docker - - name: DOCKERFILE_NAME - value: Dockerfile-17.06.1 - resources: - inputs: - - name: workspace - resourceRef: - name: cloud-builder-repo -``` - ### Example of Using custom `ServiceAccount` credentials The example below illustrates how to specify a `ServiceAccount` to access a private `git` repository: @@ -903,24 +778,18 @@ metadata: name: test-task-with-serviceaccount-git-ssh spec: serviceAccountName: test-task-robot-git-ssh - resources: - inputs: - - name: workspace - resourceSpec: - type: git - params: - - name: url - value: https://github.com/tektoncd/pipeline.git - taskSpec: - resources: - inputs: - - name: workspace - type: git - steps: - - name: config - image: ubuntu - command: ["/bin/bash"] - args: ["-c", "cat README.md"] + workspaces: + - name: source + persistentVolumeClaim: + claimName: repo-pvc + - name: ssh-creds + secret: + secretName: test-git-ssh + params: + - name: url + value: https://github.com/tektoncd/pipeline.git + taskRef: + name: git-clone ``` In the above code snippet, `serviceAccountName: test-build-robot-git-ssh` references the following @@ -935,7 +804,7 @@ secrets: - name: test-git-ssh ``` -And `name: test-git-ssh` references the following `Secret`: +And `secretName: test-git-ssh` references the following `Secret`: ```yaml apiVersion: v1 diff --git a/docs/tasks.md b/docs/tasks.md index 4b6d106e4f5..be18975f445 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -980,9 +980,9 @@ Study the following code examples to better understand how to configure your `Ta - [Using a `Secret` as an environment source](#using-a-secret-as-an-environment-source) - [Using a `Sidecar` in a `Task`](#using-a-sidecar-in-a-task) -_Tip: See the collection of simple -[examples](https://github.com/tektoncd/pipeline/tree/main/examples) for -additional code samples._ +_Tip: See the collection of Tasks in the +[Tekton community catalog](https://github.com/tektoncd/catalog) for +more examples. ### Building and pushing a Docker image @@ -994,32 +994,26 @@ unsafe** and is shown here only as a demonstration. Use [kaniko](https://github. ```yaml spec: params: - # These may be overridden, but provide sensible defaults. - - name: directory - type: string - description: The directory containing the build context. - default: /workspace + # This may be overridden, but is a sensible default. - name: dockerfileName type: string description: The name of the Dockerfile default: Dockerfile - resources: - inputs: - - name: workspace - type: git - outputs: - - name: builtImage - type: image + - name: image + type: string + description: The image to build and push + workspaces: + - name: source steps: - name: dockerfile-build image: gcr.io/cloud-builders/docker - workingDir: "$(params.directory)" + workingDir: "$(workspaces.source.path)" args: [ "build", "--no-cache", "--tag", - "$(resources.outputs.image.url)", + "$(params.image)", "--file", "$(params.dockerfileName)", ".", @@ -1030,7 +1024,7 @@ spec: - name: dockerfile-push image: gcr.io/cloud-builders/docker - args: ["push", "$(resources.outputs.image.url)"] + args: ["push", "$(params.image)"] volumeMounts: - name: docker-socket mountPath: /var/run/docker.sock @@ -1117,15 +1111,12 @@ spec: type: string description: name of the secret holding the github-token default: github-token - resources: - inputs: - - name: source - type: git - targetPath: src/$(params.package) + workspaces: + - name: source steps: - name: release image: goreleaser/goreleaser - workingDir: /workspace/src/$(params.package) + workingDir: $(workspaces.source.path)/$(params.package) command: - goreleaser args: