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: