HYPERFLEET-1250 - docs: document single-instance limitation

[kuudori]

Summary

Documents Sentinel's single-instance deployment limitation (AC2 of HYPERFLEET-1250). Running multiple replicas with overlapping resource_selector values causes proportional duplicate events — confirmed during Ignition Day Q2 2026 testing.

Changes:

• Added ## Known Limitations section to docs/multi-instance-deployment.md with subsections: No Built-In Deduplication or Leader Election, Recommended Deployment Configuration, Future: Automated Partitioning
• Fixed misleading "can overlap if needed" language to warn overlapping selectors will cause duplicate events
• Strengthened overlap warning in docs/sentinel-operator-guide.md from buried list item to > **Important**: callout
• Added replicaCount duplicate-event warning to charts/values.yaml (propagated to charts/README.md via make helm-docs)
• Updated CHANGELOG

Out of scope (separate tickets):

• AC1: Partitioning design + implementation (~13 pts) — future Epic combining HYPERFLEET-1250 + HYPERFLEET-1248
• Automated shard coverage validation

AC Coverage

AC	Status
Design for sentinel partitioning	Deferred — separate Epic
Documented limitation with recommended deployment config	Done

Gate Results

• make test-helm: all 10 scenarios passed (lint, template rendering, kubeconform validation)
• Pre-commit hooks: all passed (leaktk, commitlint, trailing whitespace, end-of-file)

Test plan

• Verify docs/multi-instance-deployment.md renders correctly on GitHub with Known Limitations section
• Verify anchor link #known-limitations resolves from the callout at the top of the doc
• Verify charts/README.md replicaCount row shows the duplicate-event warning
• Verify cross-reference link from operator guide to multi-instance-deployment.md resolves

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified deployment guidance for running multiple instances, including the need for non-overlapping resource selection and full coverage across resources.
  • Expanded scaling recommendations to discourage increasing replicas for horizontal scaling and point to safer multi-instance deployment patterns.
  • Added clearer warnings about duplicate events and operational load when overlapping configurations are used.
  • Updated the changelog and Helm chart documentation to reflect the supported deployment approach.

Walkthrough

Documentation-only update. The replicaCount comment in charts/values.yaml and the corresponding charts/README.md table row now state that replicas above 1 duplicate events and direct operators to use separate Helm releases with non-overlapping resourceSelector values. docs/multi-instance-deployment.md expands the Known Limitations section with rationale for the lack of inter-instance coordination, an explicit warning against increasing replicaCount, and an expanded future automated-partitioning note. docs/sentinel-operator-guide.md removes the prior "Overlap Allowed" bullet and adds a note block enforcing non-overlapping selectors. CHANGELOG.md records the limitation under Unreleased/Changed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR's main change: documenting Sentinel's single-instance deployment limitation.
Description check	✅ Passed	The description is clearly related and summarizes the same documentation and Helm warning updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Sec-02: Secrets In Log Output	✅ Passed	No non-test/example log calls contain token/password/credential/secret; only mock data literals match. No CWE-532 exposure.
No Hardcoded Secrets	✅ Passed	No hardcoded secrets in touched files; only placeholder/example credentials in docs/helm docs, which are exempt.
No Weak Cryptography	✅ Passed	Docs-only PR; no banned primitives, ECB, SHA1-for-security, or secret comparisons found in modified files (no CWE-327/CWE-328 issue).
No Injection Vectors	✅ Passed	Diff is docs/charts-only; scans found no SQL concat/fmt.Sprintf queries, exec.Command, template.HTML, or yaml.Unmarshal in changed files (CWE-89/78/79/502).
No Privileged Containers	✅ Passed	PR only changes docs/changelog/values comments; deployment template still sets runAsNonRoot=true and allowPrivilegeEscalation=false.
No Pii Or Sensitive Data In Logs	✅ Passed	No CWE-532 exposure: runtime logs only report IDs/counts; debug config is default-off and mock publisher is unused outside tests/docs.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

_{Comment @coderabbitai help to get the list of available commands.}

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign mbrudnoy for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hyperfleet-ci-bot]

Risk Score: 0 — risk/low

Signal	Detail	Points
PR size	58 lines	+0
Sensitive paths	none	+0

_{Computed by hyperfleet-risk-scorer}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/multi-instance-deployment.md`:
- Line 154: The availability guidance in the Sentinel deployment section is
overstated and should be softened in the text around the “do not run multiple
replicas” recommendation. Update the wording to make clear that Kubernetes
restart policies and PodDisruptionBudget only reduce voluntary-eviction downtime
for a single partition and do not provide true high availability or failover;
keep the guidance tied to the Sentinel deployment advice so operators are not
misled about replica scaling behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: d1f07a18-8616-4ea9-8c89-abdc7790edfa

📥 Commits

Reviewing files that changed from the base of the PR and between 3ffc587 and 8dffec6.

📒 Files selected for processing (5)

• CHANGELOG.md
• charts/README.md
• charts/values.yaml
• docs/multi-instance-deployment.md
• docs/sentinel-operator-guide.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• openshift-hyperfleet/architecture (manual)
• openshift-hyperfleet/hyperfleet-api (manual)
• openshift-hyperfleet/hyperfleet-sentinel (manual)
• openshift-hyperfleet/hyperfleet-adapter (manual)
• openshift-hyperfleet/hyperfleet-broker (manual)