From 523c029f36b88eff89b46863cabcd029082bb999 Mon Sep 17 00:00:00 2001 From: Aiden De Loryn Date: Wed, 4 Aug 2021 13:27:22 +1000 Subject: [PATCH 1/2] Add documentation for Windows A new markdown file has been added to document Windows usage in Tekton. --- docs/windows.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/windows.md diff --git a/docs/windows.md b/docs/windows.md new file mode 100644 index 00000000000..6321e6ae4e2 --- /dev/null +++ b/docs/windows.md @@ -0,0 +1,102 @@ +# Windows + +- [Overview](#overview) +- [Scheduling Tasks on Windows Nodes](#scheduling-tasks-on-windows-nodes) + - [Node Selectors](#node-selectors) + - [Node Affinity](#node-affinity) + +## Overview + +If you need a Windows environment as part of a Tekton Task or Pipeline, you can include Windows container images in your Task steps. Because Windows containers can only run on a Windows host, you will need to have Windows nodes available in your Kubernetes cluster. You should read [Windows support in Kubernetes](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/) to understand the functionality and limitations of Kubernetes on Windows. + +Some important things to note about **Windows containers and Kubernetes**: + +- Windows containers cannot run on a Linux host. +- Kubernetes does not support *Windows only* clusters. The Kubernetes control plane components can only run on Linux. +- Kubernetes currently only supports process isolated containers, which means a container's base image OS version **must** match that of the host OS. See [Windows container version compatibility](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-20H2%2Cwindows-10-20H2) for more information. +- A Kubernetes Pod cannot contain both Windows and Linux containers. + +Some important things to note about **Windows support in Tekton**: + +- A Task can only have Windows or Linux containers, but not both. +- A Pipeline can contain both Windows and Linux Tasks. +- In a mixed-OS cluster, TaskRuns and PipelineRuns will need to be scheduled to the correct node using one of the methods [described below](#scheduling-tasks-on-windows-nodes). +- Tekton's controller components can only run on Linux nodes. + +## Scheduling Tasks on Windows Nodes + +In order to ensure that Tasks are scheduled to a node with the correct host OS, you will need to update the TaskRun or PipelineRun spec with rules to define this behaviour. This can be done in a couple of different ways, but the simplest option is to specify a node selector. + +### Node Selectors + +Node selectors are the simplest way to schedule pods to a Windows or Linux node. By default, Kubernetes nodes include a label `kubernetes.io/os` to identify the host OS. The Kubelet populates this with `runtime.GOOS` as defined by Go. Use `spec.podTemplate.nodeSelector` (or `spec.taskRunSpecs[i].taskPodTemplate.nodeSelector` in a PipelineRun) to schedule Tasks to a node with a specific label and value. + +For example: + +``` yaml +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: windows-taskrun +spec: + taskRef: + name: windows-task + podTemplate: + nodeSelector: + kubernetes.io/os: windows +--- +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: linux-taskrun +spec: + taskRef: + name: linux-task + podTemplate: + nodeSelector: + kubernetes.io/os: linux +``` + +### Node Affinity + +Node affinity can be used as an alternative method of defining the OS requirement of a Task. These rules can be set under `spec.podTemplate.affinity.nodeAffinity` in a TaskRun definition. The example below produces the same result as the previous example which used node selectors. + +For example: + +```yaml +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: windows-taskrun +spec: + taskRef: + name: windows-task + podTemplate: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - windows +--- +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: linux-taskrun +spec: + taskRef: + name: linux-task + podTemplate: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - linux +``` \ No newline at end of file From b9eca1331654a2fdd9d0f3715eba72e513f4a2b1 Mon Sep 17 00:00:00 2001 From: Aiden De Loryn Date: Wed, 4 Aug 2021 14:56:52 +1000 Subject: [PATCH 2/2] Add examples for scheduling runs to a Windows node Some examples have been added to demonstrate how to schedule TaskRuns and PipelineRuns on a Windows node using node selectors and node affinity constraints. --- .../no-ci/windows-node-affinity.yaml | 43 +++++++++++++++++++ .../no-ci/windows-node-selectors.yaml | 36 ++++++++++++++++ .../taskruns/no-ci/windows-node-affinity.yaml | 31 +++++++++++++ .../no-ci/windows-node-selectors.yaml | 24 +++++++++++ 4 files changed, 134 insertions(+) create mode 100644 examples/v1beta1/pipelineruns/no-ci/windows-node-affinity.yaml create mode 100644 examples/v1beta1/pipelineruns/no-ci/windows-node-selectors.yaml create mode 100644 examples/v1beta1/taskruns/no-ci/windows-node-affinity.yaml create mode 100644 examples/v1beta1/taskruns/no-ci/windows-node-selectors.yaml diff --git a/examples/v1beta1/pipelineruns/no-ci/windows-node-affinity.yaml b/examples/v1beta1/pipelineruns/no-ci/windows-node-affinity.yaml new file mode 100644 index 00000000000..3d36bbc2761 --- /dev/null +++ b/examples/v1beta1/pipelineruns/no-ci/windows-node-affinity.yaml @@ -0,0 +1,43 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: windows-task-na +spec: + steps: + - name: ping-localhost + image: mcr.microsoft.com/windows/nanoserver:1809 + command: ["cmd.exe"] + args: + - "/S" + - "/C" + - "echo Hello from Windows" +--- +apiVersion: tekton.dev/v1beta1 +kind: Pipeline +metadata: + name: windows-pipeline-na +spec: + tasks: + - name: windows-task-na + taskRef: + name: windows-task-na +--- +apiVersion: tekton.dev/v1beta1 +kind: PipelineRun +metadata: + name: windows-pipeline-na-run +spec: + pipelineRef: + name: windows-pipeline-na + taskRunSpecs: + - pipelineTaskName: windows-task-na + taskPodTemplate: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - windows diff --git a/examples/v1beta1/pipelineruns/no-ci/windows-node-selectors.yaml b/examples/v1beta1/pipelineruns/no-ci/windows-node-selectors.yaml new file mode 100644 index 00000000000..590d85a6780 --- /dev/null +++ b/examples/v1beta1/pipelineruns/no-ci/windows-node-selectors.yaml @@ -0,0 +1,36 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: windows-task-ns +spec: + steps: + - name: ping-localhost + image: mcr.microsoft.com/windows/nanoserver:1809 + command: ["cmd.exe"] + args: + - "/S" + - "/C" + - "echo Hello from Windows" +--- +apiVersion: tekton.dev/v1beta1 +kind: Pipeline +metadata: + name: windows-pipeline-ns +spec: + tasks: + - name: windows-task-ns + taskRef: + name: windows-task-ns +--- +apiVersion: tekton.dev/v1beta1 +kind: PipelineRun +metadata: + name: windows-pipeline-ns-run +spec: + pipelineRef: + name: windows-pipeline-ns + taskRunSpecs: + - pipelineTaskName: windows-task-ns + taskPodTemplate: + nodeSelector: + kubernetes.io/os: windows diff --git a/examples/v1beta1/taskruns/no-ci/windows-node-affinity.yaml b/examples/v1beta1/taskruns/no-ci/windows-node-affinity.yaml new file mode 100644 index 00000000000..b316620d733 --- /dev/null +++ b/examples/v1beta1/taskruns/no-ci/windows-node-affinity.yaml @@ -0,0 +1,31 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: windows-task-na +spec: + steps: + - name: ping-localhost + image: mcr.microsoft.com/windows/nanoserver:1809 + command: ["cmd.exe"] + args: + - "/S" + - "/C" + - "echo Hello from Windows" +--- +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: windows-task-na-run +spec: + taskRef: + name: windows-task-na + podTemplate: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - windows diff --git a/examples/v1beta1/taskruns/no-ci/windows-node-selectors.yaml b/examples/v1beta1/taskruns/no-ci/windows-node-selectors.yaml new file mode 100644 index 00000000000..2845f05ec03 --- /dev/null +++ b/examples/v1beta1/taskruns/no-ci/windows-node-selectors.yaml @@ -0,0 +1,24 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: windows-task-ns +spec: + steps: + - name: ping-localhost + image: mcr.microsoft.com/windows/nanoserver:1809 + command: ["cmd.exe"] + args: + - "/S" + - "/C" + - "echo Hello from Windows" +--- +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: windows-task-ns-run +spec: + taskRef: + name: windows-task-ns + podTemplate: + nodeSelector: + kubernetes.io/os: windows