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..c876e183ff --- /dev/null +++ b/docs/operations/nvlink-domain-health-reports.md @@ -0,0 +1,82 @@ +# 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: + +- **Admin CLI:** `nico-admin-cli nvl-domain health-report` (below). +- **Admin web UI:** NVLink domain health pages, linked from machine detail. + +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. + +## 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.