design doc: Add tenant-visible instance health design#3301
Open
sunilkumar-nvidia wants to merge 1 commit into
Open
design doc: Add tenant-visible instance health design#3301sunilkumar-nvidia wants to merge 1 commit into
sunilkumar-nvidia wants to merge 1 commit into
Conversation
Contributor
Summary by CodeRabbit
WalkthroughAdds a new design document specifying a tenant-safe instance health projection derived from Core’s aggregate Machine health, including the data model, visibility filtering, derivation rules, exposure paths, compatibility, security, alternatives, and final decisions. ChangesTenant-Visible Instance Health Design Document
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Signed-off-by: Sunil Kumar <sunilkumar@nvidia.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/design/instance-health/tenant-visible-instance-health-sdd.md`:
- Around line 274-315: Normalize the health enum casing across the tenant health
examples so implementers do not infer different wire formats. Update the
Instance response example for tenantHealth and the IMDS /meta-data/health
example to use one explicit convention, and align the surrounding text in the
tenant-visible instance health SDD so the serialization rule is clear. Reference
the tenantHealth REST example and the IMDS health example when making the
change.
- Around line 167-180: The tenant-visible alert gate in the instance-health
design should require a validated, non-blank HealthProbeAlert.tenant_message
rather than just non-empty text, so tighten the wording around tenant disclosure
to exclude whitespace-only or placeholder values. Update the tenant-facing rule
in the tenant-visible instance health spec to make tenant_message the explicit
opt-in only when it contains meaningful content, and keep the rest of the
redaction guidance aligned with the alert contract.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 101c86b6-2bac-46f8-a2b2-5665f917a03b
📒 Files selected for processing (1)
docs/design/instance-health/tenant-visible-instance-health-sdd.md
Comment on lines
+167
to
+180
| An alert is tenant-visible only when `HealthProbeAlert.tenant_message` is non-empty. | ||
|
|
||
| The tenant-facing alert message must be copied from `tenant_message`. It must not use the raw Machine health `message`. | ||
|
|
||
| The following Machine health fields must not be exposed to tenants: | ||
|
|
||
| * raw `message` | ||
| * `target` | ||
| * raw classifications | ||
| * health report source internals | ||
| * repair metadata | ||
| * hardware or operator-only diagnostic details | ||
|
|
||
| Setting `tenant_message` is an explicit tenant-disclosure decision. Probe owners should only set it for alerts that are safe and actionable for tenants. |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
Tighten the tenant disclosure gate.
non-empty is still too weak for a tenant-facing boundary; a whitespace-only or placeholder tenant_message would satisfy it. Define the gate as a validated, non-blank message so probe owners cannot accidentally opt in with unusable text.
🤖 Prompt for 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.
In `@docs/design/instance-health/tenant-visible-instance-health-sdd.md` around
lines 167 - 180, The tenant-visible alert gate in the instance-health design
should require a validated, non-blank HealthProbeAlert.tenant_message rather
than just non-empty text, so tighten the wording around tenant disclosure to
exclude whitespace-only or placeholder values. Update the tenant-facing rule in
the tenant-visible instance health spec to make tenant_message the explicit
opt-in only when it contains meaningful content, and keep the rest of the
redaction guidance aligned with the alert contract.
Comment on lines
+274
to
+315
| NICo REST exposes tenant health as an optional `tenantHealth` field on Instance responses. | ||
|
|
||
| ```json | ||
| { | ||
| "tenantHealth": { | ||
| "state": "Unhealthy", | ||
| "alerts": [ | ||
| { | ||
| "id": "IbPortDown", | ||
| "message": "Host networking health issue detected", | ||
| "severity": "Critical", | ||
| "inAlertSince": "2026-07-09T12:00:00Z" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| REST should consume the tenant-safe projection from Core when available. REST should not independently expose raw Machine health to tenants. | ||
|
|
||
| ### **3.5.3 Instance Metadata Service** | ||
|
|
||
| IMDS exposes tenant health at: | ||
|
|
||
| ```text | ||
| /meta-data/health | ||
| ``` | ||
|
|
||
| Example response: | ||
|
|
||
| ```json | ||
| { | ||
| "state": "unhealthy", | ||
| "alerts": [ | ||
| { | ||
| "id": "IbPortDown", | ||
| "message": "Host networking health issue detected", | ||
| "severity": "critical" | ||
| } | ||
| ] | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Normalize the JSON enum casing.
The REST example uses Critical/Unhealthy, while the IMDS example uses lowercase critical/unhealthy. Please make the wire convention explicit, or standardize the samples, so implementers do not infer two different serializations.
🤖 Prompt for 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.
In `@docs/design/instance-health/tenant-visible-instance-health-sdd.md` around
lines 274 - 315, Normalize the health enum casing across the tenant health
examples so implementers do not infer different wire formats. Update the
Instance response example for tenantHealth and the IMDS /meta-data/health
example to use one explicit convention, and align the surrounding text in the
tenant-visible instance health SDD so the serialization rule is clear. Reference
the tenantHealth REST example and the IMDS health example when making the
change.
Source: Path instructions
sunilkumar-nvidia
force-pushed
the
tenant-health-projection
branch
from
f7f105b to
4ec85e6
Compare
Contributor
There was a problem hiding this comment.
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/design/instance-health/tenant-visible-instance-health-sdd.md`:
- Around line 192-200: Clarify the precedence in the tenant health state
derivation table so stale or malformed aggregate health does not leave behavior
ambiguous when tenant-visible alerts are present. Update the health-state rules
to explicitly state whether freshness issues always force Unknown, or whether
the alert-based states in the tenant health derivation still take priority when
alerts exist; reference the table in the tenant-visible instance health design
section.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 14a6e25b-c3ab-4783-9dfe-972882fb296a
📒 Files selected for processing (1)
docs/design/instance-health/tenant-visible-instance-health-sdd.md
Comment on lines
+192
to
+200
| Tenant health state is derived from the tenant-visible alert set and aggregate health freshness. | ||
|
|
||
| | State | Derivation | | ||
| | :---- | :---- | | ||
| | `Unknown` | Aggregate health is missing, stale, or malformed, and there are no tenant-visible alerts | | ||
| | `Healthy` | Aggregate health is available and there are no tenant-visible alerts | | ||
| | `Degraded` | One or more tenant-visible alerts exist, but none are critical | | ||
| | `Unhealthy` | At least one tenant-visible critical alert exists | | ||
|
|
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map the document structure first.
ast-grep outline docs/design/instance-health/tenant-visible-instance-health-sdd.md || true
# Read the relevant section with line numbers.
sed -n '160,230p' docs/design/instance-health/tenant-visible-instance-health-sdd.md
# Search for related precedence language in this document.
rg -n "stale|malformed|Unknown|Healthy|Degraded|Unhealthy|precedence|tenant-visible alerts|aggregate health" docs/design/instance-health/tenant-visible-instance-health-sdd.mdRepository: NVIDIA/infra-controller
Length of output: 6289
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '232,262p' docs/design/instance-health/tenant-visible-instance-health-sdd.md
printf '\n---\n'
sed -n '344,386p' docs/design/instance-health/tenant-visible-instance-health-sdd.mdRepository: NVIDIA/infra-controller
Length of output: 4335
Define precedence for stale aggregate health. At docs/design/instance-health/tenant-visible-instance-health-sdd.md:192-200, the table says Unknown applies when aggregate health is missing, stale, or malformed and there are no tenant-visible alerts, but it never states what happens when alerts do exist. Spell out whether freshness overrides alert severity, or whether Degraded/Unhealthy still apply in that case.
🤖 Prompt for 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.
In `@docs/design/instance-health/tenant-visible-instance-health-sdd.md` around
lines 192 - 200, Clarify the precedence in the tenant health state derivation
table so stale or malformed aggregate health does not leave behavior ambiguous
when tenant-visible alerts are present. Update the health-state rules to
explicitly state whether freshness issues always force Unknown, or whether the
alert-based states in the tenant health derivation still take priority when
alerts exist; reference the table in the tenant-visible instance health design
section.
🔍 Container Scan SummaryNo Grype artifacts were found to aggregate. |
|
🌿 Preview your docs: https://nvidia-preview-pull-request-3301.docs.buildwithfern.com/infra-controller |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an SDD for exposing tenant-visible Instance health across Core, gRPC, REST, and IMDS.
The design defines:
InstanceStatus.tenant_healthHealthProbeAlert.tenant_message/meta-data/healthNotes
This is a design-only PR. No implementation changes are included.
Related issues
Related to #214
Type of Change
Breaking Changes
Testing
Additional Notes
This is a design-only PR. No implementation changes are included.