[TASK] Document stable labels for pod anti-affinity

[bkenez]

Description

The Helm chart already supports upgrade-stable Web Modeler and Camunda Hub pod anti-affinity selectors by pairing a user-owned podLabels entry with the same selector under affinity. This pattern is not documented in the canonical Camunda documentation.

Issue #5876 describes the resulting maintenance problem: users inspect a first deployment and hard-code chart-managed labels that can change during upgrades.

Motivation / Use Case

Documenting the existing composition removes the install-inspect-hardcode workflow without adding a new values API, templating affinity values, or coupling users to internal chart helpers.

Acceptance Criteria

• The current Helm pod-scheduling page documents the pattern with camundaHub.restapi and identifies camundaHub.websockets as equivalent.
• The 8.9 and 8.8 versioned pod-scheduling pages document the corresponding webModeler.* paths.
• The 8.7 production guide documents the same pattern under reliability guidance.
• The guidance covers namespace scope, topology labels, preferred versus required anti-affinity, and scheduler cost.
• The documentation links to the 8.9-to-8.10 Web Modeler-to-Camunda Hub migration guidance.
• The guidance states that the same podLabels and affinity pairing applies to every affinity-capable component (SUPPORT-25387 targeted Connectors; SUPPORT-24532 asked for all components).
• The guidance warns against selecting on chart-managed labels such as app.kubernetes.io/component, whose values have changed between chart versions, and notes that overriding the Orchestration Cluster (8.7: Zeebe) affinity replaces the default hard podAntiAffinity rule.

Additional Context

This is documentation for existing non-breaking behavior. No chart template, default, or rendered manifest change is required.

References

• Original feature request: Improve labels handling in affinity conf #5876
• Chart contract and generated values-reference coverage: docs: document stable pod labels for Web Modeler anti-affinity rules #6931
• Canonical documentation PR: docs(helm): document stable pod labels for Web Modeler anti-affinity rules camunda-docs#9666

[distro-ci]

🧭 Triage Assessment

Field	Value
Work type	TASK
Kind	docs
Severity	⚠️ Mid
Likelihood	🔶 Mid
Confidence	0.95

📝 Rationale

This is within SM Platform Distribution scope because the team boundaries assign Helm Charts, Self-Managed documentation, and issues concerning Self-Managed Helm configurations to Distribution. It is a TASK, not TOIL, because it is a discrete documentation deliverable; it is not a BUG because the existing behavior works as intended, and the requested change adds no runtime or chart behavior. The referenced chart and documentation changes explicitly preserve templates, defaults, and rendered manifests while documenting an existing pattern. The appropriate kind is docs because the acceptance criteria exclusively target public and versioned documentation, including scheduling guidance and migration links. Severity is mid: the work provides a clear customer-facing reliability and upgrade-maintenance improvement, matching the task guideline's medium-impact definition, but the chart is not broken and users have a workaround by hard-coding labels. Likelihood is mid because the problem can recur for users configuring custom anti-affinity, including across supported chart upgrades, but it affects a subset of deployments rather than all Helm users. The issue is sufficiently specified: it states the limitation, affected users, desired outcome, version scope, and acceptance criteria. Similar issues are #5876, the originating affinity-label request; #6308, a broader Helm documentation/test coverage umbrella that identifies scheduling guidance gaps; and #1994, a related topology and pod-distribution request. None is a strict duplicate of this documentation-only task.

🔍 Similar Issues

#5876, #6308, #1994

---

🤖 This issue was automatically triaged by an AI-based system.
✋ If you believe this assessment is incorrect, update the labels or add the triage:manual label for human review.