Networking NVIDIA UFM Enterprise REST API Guide

Topology Model Reconciliation REST API

Topology model reconciliation closes the loop around Topology Model Validation. A single request detects raw node and port divergence between UFM's in-memory fabric model and OpenSM's subnet database, repairs it with one full-fabric resync, and then proves with a fresh validation whether the model converged.

One reconciliation run performs the following:

  1. Runs a fresh topology model validation.

  2. If there is no raw node/port divergence, finishes as converged without invoking a repair.

  3. If the mode is dry_run, returns the divergence report without changing the model.

  4. If divergence exists in apply mode, invokes the non-restart fabric resync once.

  5. Waits until the full-fabric model apply completes.

  6. Runs a fresh validation.

  7. Reports whether the model converged.

Acceptance of the repair action is not success on its own. Convergence is proven only when all six fresh node/port divergence counts are zero: nodes_missing, nodes_stale, nodes_mismatched, ports_missing, ports_stale and ports_mismatched.

License: this feature requires the Advanced license.

Routes and Required Roles

All routes are mounted at /ufmRest/app/topology_model_reconciliation. For role definitions, refer to Roles Access Control.

Method

Route

Minimum Role

POST

/start

Fabric_Operator

GET

/status

Monitoring_Only

GET

/last_run

Monitoring_Only

GET

/<run_id>

Monitoring_Only

GET

/configure

Monitoring_Only

POST

/configure

Fabric_Operator

Common Response Codes

HTTP Status

Meaning

202 – Accepted

Run accepted, or an idempotent replay of an existing run

400 – Bad Request

Invalid request body, idempotency key, query argument or configuration value

404 – Not Found

Unknown run_id, or /last_run before any run exists

409 – Conflict

Another reconciliation run is active, or an idempotency key was reused with different input

500 – Internal Server Error

Retained run storage is unusable

501 – Not Implemented

POST /start is not supported on a multisubnet consumer

REST APIs to Manage Topology Model Reconciliation

The examples below use the following shell variables:

BASE=https://<ufm-host>/ufmRest
RECON=$BASE/app/topology_model_reconciliation

Start a Reconciliation Run

Starts one reconciliation run as a background job. Only one run can be active at a time.

Request URL: /ufmRest/app/topology_model_reconciliation/start

Method: POST

Status Codes: 202 – Accepted; 400 – Bad Request; 409 – Conflict (a run is already active, or the idempotency key was reused with different input); 501 – Not Implemented (multisubnet consumer)

An absent request body is valid and defaults to apply. The supported request body is:

{
  "mode": "apply",
  "reason": "Optional audit reason"
}

Field

Description

mode

apply (default) repairs divergence and revalidates. dry_run reports divergence without invoking the repair action.

reason

Optional free-text reason stored with the run for auditing (up to 1024 characters).

An Idempotency-Key request header is optional. Repeating the same request with the same key returns the original run and does not repeat the repair.

Default apply:

curl -sk -u '<user>:<password>' \
  -X POST "$RECON/start" | jq .

Explicit apply with audit and idempotency information:

curl -sk -u '<user>:<password>' \
  -X POST "$RECON/start" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: incident-123-resync-1' \
  -d '{"mode":"apply","reason":"Reconcile after incident 123"}' | jq .

Dry run:

curl -sk -u '<user>:<password>' \
  -X POST "$RECON/start" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"dry_run","reason":"Pre-change drift check"}' | jq .

A successful start returns HTTP 202 with the identity of the new run:

{
  "run_id": "666a1979bc1148ec8d20da5112bc87a7",
  "job_id": "9",
  "uri": "/app/topology_model_reconciliation/666a1979bc1148ec8d20da5112bc87a7",
  "job_uri": "/jobs/9",
  "idempotent_replay": false
}

Field

Description

run_id

Identifier of the reconciliation run; use it with GET /<run_id>

job_id

Identifier of the job executing the run

uri / job_uri

Locations of the run record and of its job

idempotent_replay

true when the request repeated an earlier one with the same Idempotency-Key, in which case the original run is returned and no new action is invoked

Monitor and Retrieve a Run

curl -sk -u '<user>:<password>' "$RECON/status"   | jq .
curl -sk -u '<user>:<password>' "$RECON/last_run" | jq .
curl -sk -u '<user>:<password>' "$RECON/<run_id>" | jq .

Request URL

Method

Description

/status

GET

Whether a run is currently active, and the identifier of the last run

/last_run

GET

The newest retained run record, or HTTP 404 if no run has been retained yet

/<run_id>

GET

One retained run record, or HTTP 404 if the identifier is unknown

Poll the run record or the job result to learn the outcome (refer to Jobs REST API). Do not rely on a fixed sleep: rebuilding and applying the full fabric model can take several minutes on a large fabric.

Terminal Results

Result

Meaning

converged

The initial or post-action validation found zero divergence

diverged

A dry run found divergence and changed nothing

not_converged

The repair completed, but a fresh validation still found divergence

failed

The action, validation, persistence, timeout or process-continuity check failed

Get Reconciliation Configuration

Request URL: /ufmRest/app/topology_model_reconciliation/configure

Method: GET

Status Codes: 200 – OK

curl -sk -u '<user>:<password>' "$RECON/configure" | jq .

Update Reconciliation Configuration

Request URL: /ufmRest/app/topology_model_reconciliation/configure

Method: POST

Status Codes: 202 – Accepted; 400 – Bad Request (invalid value, or the change could not be persisted)

curl -sk -u '<user>:<password>' \
  -X POST "$RECON/configure" \
  -H 'Content-Type: application/json' \
  -d '{"timeout_seconds":1800}' | jq .

The configuration is persisted in gv.cfg:

[TopologyModelReconciliation]
timeout_seconds = 600

Field

Type

Default

Description

timeout_seconds

integer, 1–86400

600

Whole-run budget, covering both validations, the resync trigger and the wait for the full-fabric model apply. Raise it for a large fabric. Each run captures the value in effect when it was submitted, so a change affects later runs only.

On Kubernetes deployments, gv.cfg is managed by Helm and is read-only. Change timeout_seconds through helm upgrade rather than through this endpoint.

Safety and Limitations

  • Only one reconciliation run can be active at a time.

  • One run invokes the resync action at most once, and the action is not retried automatically.

  • Each run is persisted for auditing and recovery.

  • An idempotent replay returns the original run and cannot invoke a duplicate action.

  • Reconciliation never restarts Model Main.

  • It does not mutate individual nodes or ports.

  • It does not rebuild the derived multi-HCA host projection.

  • Automatic UFM Health-driven or scheduled reconciliation is not included.

  • POST /start is not supported on a multisubnet consumer and returns HTTP 501. The read endpoints still serve locally retained runs.

The POST /ufmRest/app/fabric_resync action is a low-level primitive that requires the System_Admin role and performs no detection, no verification and no auditing. Use the reconciliation API for the complete validate, repair and verify workflow.

Last updated: