From 3a0caba1f5b2d635b3cae6dd9410f5aba192aad3 Mon Sep 17 00:00:00 2001 From: Tiger Kaovilai Date: Fri, 1 Aug 2025 13:14:32 -0400 Subject: [PATCH] docs: Clarify that only first loadAffinity array element is used MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses #9133 by adding clear documentation about the current limitation where only the first element in the loadAffinity array is processed. Changes: - Added prominent warning at the beginning of loadAffinity section - Updated misleading examples that showed multiple array elements - Added warnings to each multi-element example explaining the limitation - Clarified that the recommended approach is to combine all conditions into a single loadAffinity element using both matchLabels and matchExpressions This provides the "bare minimum" documentation clarification requested in the issue until a code fix can be implemented. 🤖 Generated with [Claude Code](https://claude.ai/code) Signed-off-by: Tiger Kaovilai Apply suggestion from @kaovilai Signed-off-by: Tiger Kaovilai Signed-off-by: Tiger Kaovilai Apply suggestion from @kaovilai Signed-off-by: Tiger Kaovilai Signed-off-by: Tiger Kaovilai Apply suggestion from @kaovilai Signed-off-by: Tiger Kaovilai Signed-off-by: Tiger Kaovilai Co-Authored-By: Claude --- .../docs/main/data-movement-node-selection.md | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/site/content/docs/main/data-movement-node-selection.md b/site/content/docs/main/data-movement-node-selection.md index 0eb17704f..f89b9a778 100644 --- a/site/content/docs/main/data-movement-node-selection.md +++ b/site/content/docs/main/data-movement-node-selection.md @@ -13,6 +13,54 @@ Velero data movement backup and restore support to constrain the nodes where it Velero introduces a new section in the node-agent ConfigMap, called ```loadAffinity```, through which users can specify the nodes to/not to run data movement, in the affinity and anti-affinity flavors. +**Important**: Currently, only the first element in the `loadAffinity` array is used. Any additional elements after the first one will be ignored. If you need to specify multiple conditions, combine them within a single `loadAffinity` element using both `matchLabels` and `matchExpressions`. + +### Example of Incorrect Usage (Multiple Array Elements) + +The following configuration will NOT work as intended: + +```json +{ + "loadAffinity": [ + { + "nodeSelector": { + "matchLabels": { + "environment": "production" + } + } + }, + { + "nodeSelector": { + "matchLabels": { + "disk-type": "ssd" + } + } + } + ] +} +``` + +In this example, you might expect data movement to run only on nodes that are BOTH in production AND have SSD disks. However, **only the first condition (environment=production) will be applied**. The second array element will be completely ignored. + +### Correct Usage (Combined Conditions) + +To achieve the intended behavior, combine all conditions into a single array element: + +```json +{ + "loadAffinity": [ + { + "nodeSelector": { + "matchLabels": { + "environment": "production", + "disk-type": "ssd" + } + } + } + ] +} +``` + If it is not there, a ConfigMap should be created manually. The ConfigMap should be in the same namespace where Velero is installed. If multiple Velero instances are installed in different namespaces, there should be one ConfigMap in each namespace which applies to node-agent in that namespace only. The name of the ConfigMap should be specified in the node-agent server parameter ```--node-agent-configmap```. The node-agent server checks these configurations at startup time. Therefore, users could edit this ConfigMap any time, but in order to make the changes effective, node-agent server needs to be restarted. @@ -87,7 +135,7 @@ Here is a sample of the ConfigMap with ```loadAffinity```: This example demonstrates how to use both `matchLabels` and `matchExpressions` in the same single LoadAffinity element. -### LoadAffinity interacts with LoadAffinityPerStorageClass +### LoadAffinity with StorageClass (Note: Only First Element Used) ``` json {