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:
-
Runs a fresh topology model validation.
-
If there is no raw node/port divergence, finishes as
convergedwithout invoking a repair. -
If the mode is
dry_run, returns the divergence report without changing the model. -
If divergence exists in
applymode, invokes the non-restart fabric resync once. -
Waits until the full-fabric model apply completes.
-
Runs a fresh validation.
-
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 |
|
|
|
GET |
|
|
|
GET |
|
|
|
GET |
|
|
|
GET |
|
|
|
POST |
|
|
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 |
|
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 |
|
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 |
|---|---|
|
|
|
|
|
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 |
|---|---|
|
|
Identifier of the reconciliation run; use it with GET /<run_id> |
|
|
Identifier of the job executing the run |
|
|
Locations of the run record and of its job |
|
|
|
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 |
|---|---|---|
|
|
GET |
Whether a run is currently active, and the identifier of the last run |
|
|
GET |
The newest retained run record, or HTTP 404 if no run has been retained yet |
|
|
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 |
|---|---|
|
|
The initial or post-action validation found zero divergence |
|
|
A dry run found divergence and changed nothing |
|
|
The repair completed, but a fresh validation still found divergence |
|
|
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 |
|---|---|---|---|
|
|
integer, 1–86400 |
|
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 /startis 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.
Related Documentation
Last updated: