From 3554a30d98889f6d6560df064b15023a2cb52630 Mon Sep 17 00:00:00 2001 From: Jonas Pettersson Date: Sat, 16 May 2020 22:26:49 +0200 Subject: [PATCH] Improve Pod template documentation The `hostNetwork` field was added to Pod template in #2325 but not documented in the [Pod template](https://github.com/tektoncd/pipeline/blob/master/docs/podtemplates.md) documentation. It is added in this commit. Also: - Clarify that the Pod template is for both `TaskRun` and `PipelineRun`. - Fixing broken links in the documentation - Removing `hostNetwork` from the `TaskRun` documentation, since it is a special case, but document it in the Pod template documentation. /kind documentation --- docs/pipelineruns.md | 2 +- docs/podtemplates.md | 17 ++++++++++------- docs/taskruns.md | 3 +-- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md index 33f0460e2e1..e93d17bdbb1 100644 --- a/docs/pipelineruns.md +++ b/docs/pipelineruns.md @@ -243,7 +243,7 @@ then `test-task` will execute using the `sa-1` account while `build-task` will e You can specify a [`Pod` template](podtemplates.md) configuration that will serve as the configuration starting point for the `Pod` in which the container images specified in your `Tasks` will execute. This allows you to -customize the `Pod` confguration specifically for each `TaskRun`. +customize the `Pod` configuration specifically for each `TaskRun`. In the following example, the `Task` defines a `volumeMount` object named `my-cache`. The `PipelineRun` provisions this object for the `Task` using a `persistentVolumeClaim` and executes it as user 1001. diff --git a/docs/podtemplates.md b/docs/podtemplates.md index 95ad12a4047..7faaa5877f1 100644 --- a/docs/podtemplates.md +++ b/docs/podtemplates.md @@ -1,18 +1,18 @@ -# PodTemplates +# Pod templates A pod template specifies a subset of [`PodSpec`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/#pod-v1-core) configuration that will be used as the basis for the `Task` pod. -This allows to customize some Pod specific field per `Task` execution, aka `TaskRun`. +This allows for customizing some `Pod` specific field per `Task` execution, `TaskRun` or for all `Task` executions part of a `PipelineRun`. -Alternatively, you can also define a default pod template in tekton config, see [here](https://github.com/tektoncd/pipeline/blob/master/docs/install.md) +Alternatively, you can also define a default pod template in Tekton config, see [Customizing basic execution parameters](./install.md#customizing-basic-execution-parameters) When a pod template is specified for a `PipelineRun` or `TaskRun`, the default pod template is ignored, i.e. both templates are **NOT** merged, it's always one or the other. @@ -21,7 +21,7 @@ both templates are **NOT** merged, it's always one or the other. The current fields supported are: - `nodeSelector`: a selector which must be true for the pod to fit on - a node, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/). + a node, see [Assigning pods to Nodes](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/). - `tolerations`: allow (but do not require) the pods to schedule onto nodes with matching taints. - `affinity`: allow to constrain which nodes your pod is eligible to @@ -57,10 +57,13 @@ The current fields supported are: to use when dispatching the Pod. This can be used when workloads of specific types need specific schedulers, e.g.: If you are using volcano.sh for Machine Learning Workloads, you can pass the schedulerName and have Tasks be dispatched by the volcano.sh scheduler. +- `hostNetwork`: set this to `true` if the host network namespace should be used. + Defaults to `false`. -A pod template can be specified for `TaskRun` or `PipelineRun` resources. -See [here](./taskruns.md#pod-template) or [here](./pipelineruns.md#pod-template) for examples using pod templates. +A `Pod` template can be specified for `TaskRun` or `PipelineRun` resources. +See [Specifying a Pod template](./taskruns.md#specifying-a-pod-template) for a `TaskRun` example or +[Specifying a Pod template](./pipelineruns.md#specifying-a-pod-template) for a `PipelineRun` example using Pod templates. --- diff --git a/docs/taskruns.md b/docs/taskruns.md index fa564c222eb..bdf083987e4 100644 --- a/docs/taskruns.md +++ b/docs/taskruns.md @@ -152,7 +152,7 @@ spec: You can specify a [`Pod` template](podtemplates.md) configuration that will serve as the configuration starting point for the `Pod` in which the container images specified in your `Task` will execute. This allows you to -customize the `Pod` confguration specifically for that `TaskRun`. +customize the `Pod` configuration specifically for that `TaskRun`. In the following example, the `Task` specifies a `volumeMount` (`my-cache`) object, also provided by the `TaskRun`, using a `PersistentVolumeClaim` volume. A specific scheduler is also configured in the `SchedulerName` field. @@ -184,7 +184,6 @@ spec: name: mytask podTemplate: schedulerName: volcano - hostNetwork: true securityContext: runAsNonRoot: true runAsUser: 1001