[TEP-0135] Update Affinity Assistant documentation

Part of [#6740][#6740]. This commit updates the Affinity Assistant related documentation to reflect recent changes in the Affinity Assistant modes. This commit also adds a chart summarizing how to configure the Affinity Assistant modes using `coschedule` and `disabled-affinity-assistant` feature flags. /kind documentation [#6740]: #6740
tektoncd · Jun 30, 2023 · ccd6bb0 · ccd6bb0
1 parent d2cb90d
commit ccd6bb0
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 6 deletions.
diff --git 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
@@ -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.
+
+<table>
+    <thead>
+        <tr>
+            <th>disable-affinity-assistant</th>
+            <th>coschedule</th>
+            <th>behavior during migration</th>
+            <th>behavior after migration</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>false (default)</td>
+            <td>disabled</td>
+            <td>N/A: invalid</td>
+            <td>disabled</td>
+        </tr>
+        <tr>
+            <td>false (default)</td>
+            <td>workspaces (default)</td>
+            <td>coschedule workspaces</td>
+            <td>coschedule workspaces</td>
+        </tr>
+        <tr>
+            <td>false (default)</td>
+            <td>pipelineruns</td>
+            <td>N/A: invalid</td>
+            <td>coschedule pipelineruns</td>
+        </tr>
+        <tr>
+            <td>false (default)</td>
+            <td>isolate-pipelinerun</td>
+            <td>N/A: invalid</td>
+            <td>isolate pipelineruns</td>
+        </tr>
+        <tr>
+            <td>true</td>
+            <td>disabled</td>
+            <td>disabled</td>
+            <td>disabled</td>
+        </tr>
+        <tr>
+            <td>true</td>
+            <td>workspaces (default)</td>
+            <td>disabled</td>
+            <td>coschedule workspaces</td>
+        </tr>
+        <tr>
+            <td>true</td>
+            <td>pipelineruns</td>
+            <td>coschedule pipelineruns</td>
+            <td>coschedule pipelineruns</td>
+        </tr>
+        <tr>
+            <td>true</td>
+            <td>isolate-pipelinerun</td>
+            <td>isolate pipelineruns</td>
+            <td>isolate pipelineruns</td>
+        </tr>
+    </tbody>
+</table>
 
 **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