From 3c3308ec477d760a024adaa6439fa1eaab3df159 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Thu, 17 Jan 2019 15:16:07 +0100 Subject: [PATCH] =?UTF-8?q?Update=20docs/*=20files=20to=20incorporate=20k8?= =?UTF-8?q?s=20document=20style=20guidelines=20=F0=9F=93=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Guidelines are available here : https://kubernetes.io/docs/contribute/style/style-guide/ Guidelines applied here: - Use present tense. - Use active voice. - Use simple and direct language - Use camel case for API objects - Avoid using "we" Signed-off-by: Vincent Demeester --- docs/developers/README.md | 30 +++++++++++++++--------------- docs/task-parameters.md | 6 +++--- docs/tutorial.md | 34 +++++++++++++++++----------------- docs/using.md | 38 +++++++++++++++++++------------------- 4 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/developers/README.md b/docs/developers/README.md index 056f235b37c..ff40a2ffa11 100644 --- a/docs/developers/README.md +++ b/docs/developers/README.md @@ -5,34 +5,34 @@ the complexity. ### How are resources shared between tasks? -Pipelineruns uses PVC to share resources between tasks. PVC volume is mounted on -path `/pvc` by Pipelinerun. +`PipelineRun` uses PVC to share resources between tasks. PVC volume is mounted on +path `/pvc` by PipelineRun. -- If resource in a task is declared as output then taskun controllers add step - to copy each output resource to directory path `/pvc/task_name/resource_name`. +- If a resource in a task is declared as output then the `TaskRun` controller adds a step + to copy each output resource to the directory path `/pvc/task_name/resource_name`. -- If input resource includes `providedBy` condition then container definition to - copy from PVC to directory from `/pvc/previous_task/resource_name`. +- If an input resource includes `providedBy` condition then the `TaskRun` controller adds + a step to copy from PVC to directory path `/pvc/previous_task/resource_name`. ### How are inputs handled? -Input resources like source code(git) or artifacts are dumped at path +Input resources, like source code (git) or artifacts, are dumped at path `/workspace/task_resource_name`. Resource definition in task can have custom target directory. If -`targetPath` is mentioned in task input then controllers have to be responsible for adding -container definitions to create directories and also to fetch versioned +`targetPath` is mentioned in task input then the controllers are responsible for adding +container definitions to create directories and also to fetch the versioned artifacts into that directory. ### How are outputs handled? -Output resources like source code(git) or artifacts(storage resource) are +Output resources, like source code (git) or artifacts (storage resource), are expected in directory path `/workspace/output/resource_name`. -- If resource has output "action" like upload to blob storage, then container +- If resource has an output "action" like upload to blob storage, then the container step is added for this action. -- If there is PVC volume present(taskrun holds owner reference to pipelinerun) +- If there is PVC volume present (TaskRun holds owner reference to PipelineRun) then copy step is added as well. - - If resource is declared only in output but not in input for task then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/output/resource_name` like the following example. +- If the resource is declared only in output but not in input for task then the copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/output/resource_name` like the following example. ```yaml kind: Task @@ -46,7 +46,7 @@ expected in directory path `/workspace/output/resource_name`. type: storage ``` - - If resource is declared both in input and output for task then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/random-space/` if input resource has custom target directory(`random-space`) declared like the following example. +- If the resource is declared both in input and output for task the then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/random-space/` if input resource has custom target directory (`random-space`) declared like the following example. ```yaml kind: Task @@ -82,4 +82,4 @@ expected in directory path `/workspace/output/resource_name`. resources: - name: gcs-workspace type: storage - ``` \ No newline at end of file + ``` diff --git a/docs/task-parameters.md b/docs/task-parameters.md index b19297db06e..e5681c1ef0d 100644 --- a/docs/task-parameters.md +++ b/docs/task-parameters.md @@ -3,10 +3,10 @@ Tasks can declare input parameters that must be supplied to the task during a TaskRun. Some example use-cases of this include: -- A task that needs to know what compilation flags to use when building an +- A Task that needs to know what compilation flags to use when building an application. -- A task that needs to know what to name a built artifact. -- A task that supports several different strategies, and leaves the choice up to +- A Task that needs to know what to name a built artifact. +- A Task that supports several different strategies, and leaves the choice up to the other. ### Usage diff --git a/docs/tutorial.md b/docs/tutorial.md index 41b1aad885a..fed76e038ce 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,7 +1,7 @@ # Hello World Task -The main objective of the Pipeline CRD is to run your task individually or as a -part of a pipeline. Every task runs as a Pod on your Kubernetes cluster with +The main objective of the Pipeline CRDs is to run your Task individually or as a +part of a Pipeline. Every task runs as a Pod on your Kubernetes cluster with each step as its own container. ## Tasks @@ -106,8 +106,8 @@ The status of type `Succeeded = True` shows the task ran successfully. # Task Inputs and Outputs -In more common scenarios, your task needs multiple steps with input and output -resources to process. For example a task could fetch source code from a GitHub +In more common scenarios, a Task needs multiple steps with input and output +resources to process. For example a Task could fetch source code from a GitHub repository and build a Docker image from it. `PipelinesResources` are used to define the artifacts that can be passed in and @@ -144,9 +144,9 @@ spec: value: gcr.io//leeroy-web ``` -The following is a task with inputs and outputs. The input resource is a GitHub +The following is a Task with inputs and outputs. The input resource is a GitHub repository and the output is the Docker image produced from that source. The -args of the task command support templating so that the definition of task is +args of the Task command support templating so that the definition of Task is constant and the value of parameters can change in runtime. ```yaml @@ -214,14 +214,14 @@ spec: name: skaffold-image-leeroy-web ``` -To apply the yaml files use the following command, you will need to apply the +To apply the yaml files use the following command, you need to apply the two resources, the task and taskrun. ```bash kubectl apply -f ``` -To see all the resource created so far as part of the pipeline-crd, run the +To see all the resource created so far as part of the Pipeline CRD, run the command: ```bash @@ -242,7 +242,7 @@ NAME AGE tasks/build-docker-image-from-git-source 7m ``` -To see the output of the taskRun, use the following command: +To see the output of the TaskRun, use the following command: ```bash kubectl get taskruns/echo-hello-world-task-run -o yaml @@ -315,14 +315,14 @@ status: startedAt: 2018-12-11T18:14:48Z ``` -The status of type `Succeeded = True` shows the task ran successfully and you +The status of type `Succeeded = True` shows the Task ran successfully and you can also validate the Docker image is created in the location specified in the resource definition. # Pipeline Pipeline defines a graph of tasks to execute in a specific order, while also -indicating if any outputs should be used as inputs of a following task by using +indicating if any outputs should be used as inputs of a following Task by using the `providedBy` field. The same templating you used in tasks is also available in pipeline: @@ -357,7 +357,7 @@ spec: value: "spec.template.spec.containers[0].image" ``` -This pipeline is referencing a task to `deploy-using-kubectl` which can be found +The above Pipeline is referencing a task to `deploy-using-kubectl` which can be found here: ```yaml @@ -402,7 +402,7 @@ spec: - "${inputs.params.path}" ``` -To run the pipeline, create a pipelineRun as follows: +To run the Pipeline, create a PipelineRun as follows: ```yaml apiVersion: pipeline.knative.dev/v1alpha1 @@ -434,17 +434,17 @@ spec: name: skaffold-image-leeroy-web ``` -The pipelineRun will create the taskRuns corresponding to each task and collect +The PipelineRun will create the TaskRuns corresponding to each Task and collect the results. To apply the yaml files use the following command, you will need to apply the -`deploy-task` if you want to run the pipeline. +`deploy-task` if you want to run the Pipeline. ```bash kubectl apply -f ``` -To see the output of the pipelineRun, use the following command: +To see the output of the PipelineRun, use the following command: ```bash kubectl get pipelineruns/tutorial-pipeline-run-1 -o yaml @@ -558,4 +558,4 @@ status: ``` The status of type `Succeeded = True` shows the pipeline ran successfully, also -the status of individual task runs are shown. +the status of individual Task runs are shown. diff --git a/docs/using.md b/docs/using.md index 022b2d6dfa7..408108201fd 100644 --- a/docs/using.md +++ b/docs/using.md @@ -23,7 +23,7 @@ See [the example Pipeline](../examples/pipeline.yaml). ### ProvidedBy When you need to execute `Tasks` in a particular order, it will likely be -because they are operating over the same `Resources` (e.g. your unit test task +because they are operating over the same `Resources` (e.g. your unit test Task must run first against your git repo, then you build an image from that repo, then you run integration tests against that image). @@ -31,13 +31,13 @@ We express this ordering by adding `providedBy` on `Resources` that our `Tasks` need. - The (optional) `providedBy` key on an `input source` defines a set of previous - task names. + Task names. - When the `providedBy` key is specified on an input source, only the version of the resource that is provided by the defined list of tasks is used. -- The `providedBy` allows for `Tasks` to fan in and fan out, and ordering can be - expressed explicitly using this key since a task needing a resource from a - another task would have to run after. -- The name used in the `providedBy` is the name of `PipelineTask` +- The `providedBy` allows for `Task`s to fan in and fan out, and ordering can be + expressed explicitly using this key since a Task needing a resource from a + another Task would have to run after. +- The name used in the `providedBy` is the name of `PipelineTask`. - The name of the `PipelineResource` must correspond to a `PipelineResource` from the `Task` that the referenced `PipelineTask` provides as an output @@ -89,7 +89,7 @@ the `skaffold-image-leeroy-app` `PipelineResource`, and the same This controls two things: -1. The order the `Tasks` are executed in: `deploy-app` must come after +1. The order the `Task`s are executed in: `deploy-app` must come after `build-skaffold-app` 2. The state of the `PipelineResources`: the image provided to `deploy-app` may be changed by `build-skaffold-app` (WIP, see @@ -112,7 +112,7 @@ To create a Task, you must: Each container image used as a step in a [`Task`](#task) must comply with a specific contract. -When containers are run in a `Task`, the `entrypoint` of the container will be +When containers are run in a `Task`, the `entrypoint` of the container is overwritten with a custom binary that redirects the logs to a separate location for aggregating the log output. As such, it is always recommended to explicitly specify a command. @@ -175,7 +175,7 @@ mounted under path `/pvc`. `Task` definition can include inputs and outputs resource declaration. If specific set of resources are only declared in output then a copy of resource to -be uploaded or shared for next task is expected to be present under the path +be uploaded or shared for next Task is expected to be present under the path `/workspace/output/resource_name/`. ```yaml @@ -192,7 +192,7 @@ steps: value: "world" ``` -**Note**: If task is relying on output resource functionality then they cannot +**Note**: If the Task is relying on output resource functionality then they cannot mount anything in file path `/workspace/output`. If resource is declared in both input and output then input resource, then @@ -204,7 +204,7 @@ output so input resource is downloaded into directory `customworkspace`(as specified in `targetPath`). Step `untar` extracts tar file into `tar-scratch-space` directory , `edit-tar` adds a new file and last step `tar-it-up` creates new tar file and places in `/workspace/customworkspace/` -directory. After execution of task steps, (new) tar file in directory +directory. After execution of the Task steps, (new) tar file in directory `/workspace/customworkspace` will be uploaded to the bucket defined in `tar-artifact` resource definition. @@ -445,7 +445,7 @@ secrets: ## Creating Resources -We current support these `PipelineResources`: +The following `PipelineResources` are currently supported: - [Git resource](#git-resource) - [Image resource](#image-resource) @@ -453,13 +453,13 @@ We current support these `PipelineResources`: - [Storage resource](#storage-resource) When used as inputs, these resources will be made available in a mounted -directory called `/workspace` at the path /workspace/`. +directory called `/workspace` at the path `/workspace/`. ### Git Resource Git resource represents a [git](https://git-scm.com/) repository, that contains the source code to be built by the pipeline. Adding the git resource as an input -to a task will clone this repository and allow the task to perform the required +to a Task will clone this repository and allow the Task to perform the required actions on the contents of the repo. To create a git resource using the `PipelineResource` CRD: @@ -571,9 +571,9 @@ your application/function on different clusters. The resource will use the provided parameters to create a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) -file that can be used by other steps in the pipeline task to access the target +file that can be used by other steps in the pipeline Task to access the target cluster. The kubeconfig will be placed in -`/workspace//kubeconfig` on your task container +`/workspace//kubeconfig` on your Task container The Cluster resource has the following parameters: @@ -650,7 +650,7 @@ spec: secretName: target-cluster-secrets ``` -Example usage of the cluster resource in a task: +Example usage of the cluster resource in a Task: ```yaml apiVersion: pipeline.knative.dev/v1alpha1 @@ -681,8 +681,8 @@ spec: ### Storage Resource Storage resource represents blob storage, that contains either an object or -directory. Adding the storage resource as an input to a task will download the -blob and allow the task to perform the required actions on the contents of the +directory. Adding the storage resource as an input to a Task will download the +blob and allow the Task to perform the required actions on the contents of the blob. Blob storage type [Google Cloud Storage](https://cloud.google.com/storage/)(gcs) is supported as of now.