From 431b5cbaad1c654a826d7231c4b503c0dc40d7cb Mon Sep 17 00:00:00 2001 From: Jay Zhu Date: Thu, 16 Jul 2026 18:53:03 -0600 Subject: [PATCH 1/2] docs(nvl-domain-health): document NVL domain health report Signed-off-by: Jay Zhu --- docs/index.yml | 2 + .../nvlink-domain-health-reports.md | 86 +++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 docs/operations/nvlink-domain-health-reports.md diff --git a/docs/index.yml b/docs/index.yml index 11555d4c89..e4ed4c1291 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -158,6 +158,8 @@ navigation: path: operations/firmware-updates.md - page: Monitoring and Health path: operations/monitoring-health.md + - page: NVLink Domain Health Reports + path: operations/nvlink-domain-health-reports.md - page: Tenant Lifecycle Cleanup path: operations/tenant-lifecycle-cleanup.md - page: Network Isolation diff --git a/docs/operations/nvlink-domain-health-reports.md b/docs/operations/nvlink-domain-health-reports.md new file mode 100644 index 0000000000..01e3580818 --- /dev/null +++ b/docs/operations/nvlink-domain-health-reports.md @@ -0,0 +1,86 @@ +# NVLink Domain Health Reports (Day 2) + +Operator guide for managing **NVLink domain health reports**: health information +submitted by external tools or operators against an NVLink domain. + +Each report is keyed by a **source** identifier. Multiple merge-mode sources +coexist and contribute to the domain's aggregate health. A replace-mode source +overrides that aggregate. Reports are persisted in the +`nvlink_domain_health_reports` table. See +[health report overrides](../architecture/health_aggregation.md#health-report-overrides) +for the same source-keyed model applied to hosts. + +Management surfaces: + +- **API:** `ListNVLinkDomainHealthReports`, `InsertNVLinkDomainHealthReport`, + `RemoveNVLinkDomainHealthReport`. +- **Admin CLI:** `nico-admin-cli nvl-domain health-report` (below). +- **Admin web UI:** NVLink domain health pages, linked from machine detail. + +API and CLI RPC calls require the `Health` or `ForgeAdminCLI` RBAC permission +scope. Admin web UI access is controlled by its deployment authentication and +network policy. + +Background: [Health Aggregation](../architecture/health_aggregation.md) and +[Monitoring and Health](./monitoring-health.md). + +--- + +## Report sources + +A **report source** is the identifier of the system or user that submitted a +report (the `HealthReport::source` field, for example, `overrides.sre-team`). Keeping +each external system or operator on a distinct source lets their merge-mode +reports coexist. Submitting a report with an existing source replaces that +source's prior report. `show` lists sources and modes applied to a domain; +`remove` deletes one source's report. + +## CLI commands + +### List report sources for a domain + +```sh +nico-admin-cli nvl-domain health-report show +``` + +Lists health report entries applied to the NVLink domain, including +source, mode, observation time, and alert count. + +### Remove a report source + +```sh +nico-admin-cli nvl-domain health-report remove +``` + +Removes the report submitted under `` from the domain. + +### Print an empty report template + +```sh +nico-admin-cli nvl-domain health-report print-empty-template +``` + +Prints an empty health report template. Fill it in and submit it through +`InsertNVLinkDomainHealthReport`. Insertion is an API operation with no CLI +subcommand. + +## Examples + +```sh +# See which sources are reporting on a domain +nico-admin-cli nvl-domain health-report show 12345678-1234-5678-90ab-cdef01234567 + +# Clear a stale report submitted for maintenance +nico-admin-cli nvl-domain health-report remove 12345678-1234-5678-90ab-cdef01234567 internal-maintenance + +# Get a template to build an insert payload +nico-admin-cli nvl-domain health-report print-empty-template +``` + +## Report format + +NVLink domain health reports use the same `HealthReport` / `HealthProbeAlert` +schema as the rest of NICo health. Insertion wraps a report in a +`HealthReportEntry` that selects `Merge` or `Replace` mode. See +[Health Report format](../architecture/health_aggregation.md#health-report-format) +for the field-by-field definition. From 929c2a3b8b2886bb4b0453745fe674a84f20eae7 Mon Sep 17 00:00:00 2001 From: Jay Zhu Date: Fri, 17 Jul 2026 18:06:54 -0600 Subject: [PATCH 2/2] docs(nvl-domain-health-reports): remove RPC references Signed-off-by: Jay Zhu --- docs/operations/nvlink-domain-health-reports.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/operations/nvlink-domain-health-reports.md b/docs/operations/nvlink-domain-health-reports.md index 01e3580818..c876e183ff 100644 --- a/docs/operations/nvlink-domain-health-reports.md +++ b/docs/operations/nvlink-domain-health-reports.md @@ -12,12 +12,10 @@ for the same source-keyed model applied to hosts. Management surfaces: -- **API:** `ListNVLinkDomainHealthReports`, `InsertNVLinkDomainHealthReport`, - `RemoveNVLinkDomainHealthReport`. - **Admin CLI:** `nico-admin-cli nvl-domain health-report` (below). - **Admin web UI:** NVLink domain health pages, linked from machine detail. -API and CLI RPC calls require the `Health` or `ForgeAdminCLI` RBAC permission +CLI RPC calls require the `Health` or `ForgeAdminCLI` RBAC permission scope. Admin web UI access is controlled by its deployment authentication and network policy. @@ -60,9 +58,7 @@ Removes the report submitted under `` from the domain. nico-admin-cli nvl-domain health-report print-empty-template ``` -Prints an empty health report template. Fill it in and submit it through -`InsertNVLinkDomainHealthReport`. Insertion is an API operation with no CLI -subcommand. +Prints an empty health report template. ## Examples