HYPERFLEET-1138 - docs: add condition mapping configuration guide

[rafabene]

Summary

• Add docs/condition-mapping.md — comprehensive operator guide for the CEL-based condition mapping feature (PR HYPERFLEET-538 - feat: CEL-based condition mapping engine #329)
• Covers config schema, CEL evaluation context, usage examples, security (sensitive data masking), migration guide, safe navigation patterns, DSL keyword consistency, and CI validation guidance

Acceptance Criteria Coverage

Criteria	Section
Config file format + schema reference	Configuration Schema, Rule Structure
CEL evaluation context	CEL Evaluation Context (statuses, resource, custom functions)
Usage examples (1-to-1, cross-adapter, data field)	Usage Examples
Security (data exposure risks, operator responsibilities)	Security
Migration guide (hardcoded → config-driven)	Migration Guide
Safe navigation pattern	Safe Navigation Pattern
Keyword consistency + cross-references	DSL Keyword Consistency
CI validation guidance	CI Validation Guidance

Dependencies

• Documents the implementation from HYPERFLEET-538 - feat: CEL-based condition mapping engine #329 (CEL-based condition mapping engine)
• Can be merged before or after HYPERFLEET-538 - feat: CEL-based condition mapping engine #329 — the doc describes the feature independently

Test plan

• All code blocks have language identifiers (no MD040)
• All code blocks properly paired (38 markers)
• Doc claims verified against PR HYPERFLEET-538 - feat: CEL-based condition mapping engine #329 implementation code (8/8 checks passed)
• make verify passes
• No code changes — documentation only

[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 ldornele 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

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guide for configuring condition mappings.
  • Documented rule structure, evaluation variables, custom functions, safe navigation, examples, and error handling.
  • Included guidance on migration, validation, field limits, masking, and exposure considerations.

Walkthrough

Added docs/condition-mapping.md. The guide defines CEL rules for mapping adapter conditions to public Cluster and NodePool conditions. It documents evaluation context, custom functions, safe navigation, aggregation examples, sensitive-data masking, migration from hardcoded conditions, validation, testing, field limits, error handling, and related documentation. No exported or public entities changed.

Estimated code review effort: 1 (Trivial) | ~3 minutes

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
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	Eligible Go scans found no slog/logr/zap/fmt.Print* call with a sensitive field or interpolated secret; headers and connection strings are masked. CWE-532 is not triggered.
No Hardcoded Secrets	✅ Passed	Only docs/condition-mapping.md changed; scans found no credential URLs, private keys, or secret assignments. The sole secret-like value is the documented placeholder “secret-12345” (CWE-798 not tri...
No Weak Cryptography	✅ Passed	The PR adds only documentation. No banned primitives, ECB, custom cryptography, or secret comparisons occur in the changed file; no CWE-327/CWE-208 issue is introduced.
No Injection Vectors	✅ Passed	The PR adds only docs/condition-mapping.md; the added-line scan found no SQL construction, exec.Command, template.HTML, yaml.Unmarshal, or equivalent injection sink.
No Privileged Containers	✅ Passed	The patch adds only docs/condition-mapping.md; it adds no Kubernetes/OpenShift manifest, Helm template, Dockerfile, or prohibited privileged-container setting.
No Pii Or Sensitive Data In Logs	✅ Passed	The PR adds only docs/condition-mapping.md; it contains no slog/logr/zap/log/fmt.Print* calls and no concrete PII, session IDs, raw-body logs, or credentialed hostnames.
Title check	✅ Passed	The title clearly identifies the issue, documentation scope, and condition mapping guide added by this pull request.
Description check	✅ Passed	The description directly explains the documentation changes, covered topics, dependencies, validation, and test plan.

✨ 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.}

[hyperfleet-ci-bot]

Risk Score: 2 — risk/medium

Signal	Detail	Points
PR size	636 lines (>500)	+2
Sensitive paths	none	+0

_{Computed by hyperfleet-risk-scorer}

[coderabbitai]

Actionable comments posted: 3

🤖 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/condition-mapping.md`:
- Around line 172-190: Remove the “Custom CEL Functions” section and its
toJson/dig examples from condition-mapping.md, since these functions are
Adapter-only and not API capabilities. Do not add API registrations or
implementation changes; keep the documentation limited to functions supported by
the API.
- Line 377: Update the documentation near the CEL mapping result to remove the
claim that sensitive fields are automatically masked before CEL evaluation.
State that adapter status data is exposed to CEL through data and filtering is
the operator’s responsibility; only document masking if mapper-level masking and
corresponding tests are implemented.
- Around line 60-99: Update the condition-mapping documentation to match the
implemented EntityDescriptor and UnmarshalExact configuration contract: remove
deployment/integration claims and the unsupported entities[].conditions
structure, or implement the mapper and document its actual contract. Align the
guide with the architecture’s adapters.<resource>.conditions map, retain the
100-character limit for generated resource condition type values, use 128
characters for adapter condition inputs, and change message-truncation logging
from info to warning.

🪄 Autofix

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: 056ff684-3413-4473-8113-4a881892be1c

📥 Commits

Reviewing files that changed from the base of the PR and between d9cb9a9 and 66232aa.

📒 Files selected for processing (1)

• docs/condition-mapping.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)

[tirthct]

Tip

nit — non-blocking suggestion

Category: JIRA

The JIRA AC calls out env in the CEL evaluation context, but it's only mentioned down in the DSL Keyword Consistency section (line 542). Operators coming from the adapter framework or sentinel might look for env.* here and be confused when it's absent.

Consider adding a brief note after the Variables table, e.g.:

> **Note**: Unlike the Adapter Framework and Sentinel, condition mapping does not expose an `env` variable. Use the `resource` variable for resource-level context instead.

[tirthct]

Are we missing LastUpdatedTime here?