From 2330ff1280d4bb8a823efc7718d52c904396a7fb Mon Sep 17 00:00:00 2001 From: Christie Wilson Date: Wed, 24 Oct 2018 11:39:41 -0400 Subject: [PATCH] Update docs about Builder image The Builder image contract is actually the opposite of what we now support - it specifies that users should define an `entrypoint` and rely on that, however the new behaviour in #167 will completely ignore this `entrypoint`. These docs are a copy of the Builder image docs at https://github.com/knative/docs/blob/master/build/builder-contract.md but modified to describe the contract required by Task. This is for #143 --- Concepts.md | 65 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/Concepts.md b/Concepts.md index 7324609e111..a21d0f498ae 100644 --- a/Concepts.md +++ b/Concepts.md @@ -3,26 +3,22 @@ Pipeline CRDs is an open source implementation to configure and run CI/CD style Pipeline CRDs creates [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) as building blocks to declare pipelines. -A custom resource is an extension of Kubernetes API which can create a custom [Kubernetest Object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects). +A custom resource is an extension of Kubernetes API which can create a custom [Kubernetes Object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects). Once a custom resource is installed, users can create and access its objects with kubectl, just as they do for built-in resources like pods, deployments etc. These resources run on-cluster and are implemeted by [Kubernetes Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions). -# Building Blocks of Pipeline CRDs +## Building Blocks of Pipeline CRDs Below diagram lists the main custom resources created by Pipeline CRDs ![Building Blocks](./docs/images/building-blocks.png) -## Task +### Task A Task is a collection of sequential steps you would want to run as part of your continous integration flow. A task will run inside a container on your cluster. A Task declares, 1. Inputs the task needs. 1. Outputs the task will produce. -1. Sequence of steps to execute. - - Each step defines an container image. This image is of type [Builder Image](https://github.com/knative/docs/blob/master/build/builder-contract.md). A Builder Image is an image whose `command` performs some action and exits with a zero status on success. - - NOTE: Currently to get the logs out of a Builder Image, entrypoint overrides are used. This means that each step in `steps:` must have a container with a `command:` specified. +1. Sequence of steps to execute. Each step is [a container image](#image-contract). Here is an example simple Task definition which echoes "hello world". The `hello-world` task does not define any inputs or outputs. @@ -46,7 +42,13 @@ spec: ``` Examples of `Task` definitions with inputs and outputs are [here](./examples) -## Pipeline +### Step Entrypoint + +To get the logs out of a [step](#task), we provide our own executable that wraps +the `command` and `args` values specified in the `step`. This means that every +`Task` must use `command`, and cannot rely on the image's `entrypoint`. + +### Pipeline `Pipeline` describes a graph of [Tasks](#Task) to execute. Below, is a simple pipeline which runs `hello-world-task` twice one after the other. @@ -75,17 +77,56 @@ _TODO: Consider specifying task dependency_ Examples of pipelines with complex DAGs are [here](./examples/pipelines) -## PipelineResources +### PipelineResources `PipelinesResources` in a pipeline are the set of objects that are going to be used as inputs to a [`Task`](#Task) and can be output of [`Task`](#Task) . For e.g.: A task's input could be a github source which contains your application code. A task's output can be your application container image which can be then deployed in a cluster. Read more on PipelineResources and their types [here](./docs/pipeline-resources.md) - -## PipelineParams +### PipelineParams _TODO add text here_ +### Image Contract + +Each container image used as a step in a [`Task`](#task) must comply with a specific +contract. + +* [The `entrypoint` of the image will be ignored](#step-entrypoint) + +For example, in the following Task the images, `gcr.io/cloud-builders/gcloud` +and `gcr.io/cloud-builders/docker` run as steps: +```yaml +spec: + buildSpec: + steps: + - image: gcr.io/cloud-builders/gcloud + command: ['gcloud'] + ... + - image: gcr.io/cloud-builders/docker + command: ['docker'] + ... +``` + +You can also provide `args` to the image's `command`: + +```yaml +steps: +- image: ubuntu + command: ['/bin/bash'] + args: ['-c', 'echo hello $FOO'] + env: + - name: 'FOO' + value: 'world' +``` +### Images Conventions + * `/workspace`: If an input is provided, the default working directory will be + `/workspace` and this will be shared across `steps` (note that in + [#123](https://github.com/knative/build-pipeline/issues/123) we will add supprots for multiple input workspaces) + * `/builder/home`: This volume is exposed to steps via `$HOME`. + * Credentials attached to the Build's service account may be exposed as Git or + Docker credentials as outlined + [in the auth docs](https://github.com/knative/docs/blob/master/build/auth.md#authentication). \ No newline at end of file