diff --git a/config/config-feature-flags.yaml b/config/config-feature-flags.yaml index 8056ae23b69..f53b20b42d3 100644 --- a/config/config-feature-flags.yaml +++ b/config/config-feature-flags.yaml @@ -39,7 +39,8 @@ data: # and only allows one pipelinerun to run on a node at a time. # Setting it to "disabled" will not apply any coschedule policy. # - # TODO: add links to documentation and migration strategy + # See more in the workspace documentation about Affinity Assistant + # https://github.com/tektoncd/pipeline/blob/main/docs/workspaces.md#affinity-assistant-and-specifying-workspace-order-in-a-pipeline # NOTE: this feature is still under development and not yet functional. coschedule: "workspaces" # Setting this flag to "true" will prevent Tekton scanning attached diff --git a/docs/workspaces.md b/docs/workspaces.md index 15b4619ed1e..49492226a40 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -364,14 +364,98 @@ write to or read from that `Workspace`. Use the `runAfter` field in your `Pipeli to define when a `Task` should be executed. For more information, see the [`runAfter` documentation](pipelines.md#using-the-runafter-parameter). When a `PersistentVolumeClaim` is used as volume source for a `Workspace` in a `PipelineRun`, -an Affinity Assistant will be created. The Affinity Assistant acts as a placeholder for `TaskRun` pods +an Affinity Assistant will be created. Available Affinity Assistant Modes are **coschedule workspace**, **coschedule pipelineruns**, +**isolate pipelineruns** and **disabled**. + +* **coschedule workspace** - The Affinity Assistant acts as a placeholder for `TaskRun` pods sharing the same `Workspace`. All `TaskRun` pods within the `PipelineRun` that share the `Workspace` -will be scheduled to the same Node as the Affinity Assistant pod. This means that Affinity Assistant is incompatible -with e.g. other affinity rules configured for the `TaskRun` pods. If the `PipelineRun` has a custom +will be scheduled to the same Node as the Affinity Assistant pod. + +* **coschedule pipelineruns (WIP)** - The Affinity Assistant acts as a placeholder for the whole pipelinerun. +All `TaskRun` pods within the `PipelineRun` will be scheduled to the same Node as the Affinity Assistant pod. + +* **coschedule pipelineruns (WIP)** - The Affinity Assistant acts as a placeholder for the whole pipelinerun. +All `TaskRun` pods within the `PipelineRun` will be scheduled to the same Node as the Affinity Assistant pod, +and only one PipelineRun is allowed to run on a node at a time. + +* **disabled** - The Affinity Assistant is disabled. No pod coscheduling behavior. + +**Note:** **coschedule pipelineruns** and **coschedule pipelineruns** modes are still under development and not yet functional. + +This means that Affinity Assistant is incompatible with e.g. other affinity rules + configured for the `TaskRun` pods. If the `PipelineRun` has a custom [PodTemplate](pipelineruns.md#specifying-a-pod-template) configured, the `NodeSelector` and `Tolerations` fields will also be set on the Affinity Assistant pod. The Affinity Assistant -is deleted when the `PipelineRun` is completed. The Affinity Assistant can be disabled by setting the -[disable-affinity-assistant](install.md#customizing-basic-execution-parameters) feature gate to `true`. +is deleted when the `PipelineRun` is completed. + +Currently, the Affinity Assistant Modes can be configured by the `disable-affinity-assistant` and `coschedule` feature flags. +In the future, the `disabled-affinity-assistant` feature flag will be deprecated, and the Affinity Assistant Modes will be only determined by +the `coschedule` feature flag. + +The following chart summarizes the Affinity Assistant Modes with different combinations of the `disable-affinity-assistant` and `coschedule` feature flags during migration (when both feature flags are present) and after the migration (when only the `coschedule` flag is present): + +**Note:** **DO NOT** change the default value of the `coschedule` feature flag since the feature is work in progress and not yet functional. Please **ONLY** toggle the `disabled-affinity-assistant` feature flag to switch between **"disabled"** and **"coschedule workspace"** modes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
disable-affinity-assistantcoschedulebehavior during migrationbehavior after migration
false (default)disabledN/A: invaliddisabled
false (default)workspaces (default)coschedule workspacescoschedule workspaces
false (default)pipelinerunsN/A: invalidcoschedule pipelineruns
false (default)isolate-pipelinerunN/A: invalidisolate pipelineruns
truedisableddisableddisabled
trueworkspaces (default)disabledcoschedule workspaces
truepipelinerunscoschedule pipelinerunscoschedule pipelineruns
trueisolate-pipelinerunisolate pipelinerunsisolate pipelineruns
**Note:** Affinity Assistant use [Inter-pod affinity and anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity) that require substantial amount of processing which can slow down scheduling in large clusters