When a NetBox is busy

Designs keeps its own copy of what it manages in each NetBox, and plans against that copy. One operation at a time works on a NetBox: an apply, the reading-back that follows it, or a refresh. Anything else that reaches for the same NetBox meanwhile is told it is busy, with what it is doing and how far it has got, rather than waiting in silence:

The target is still syncing after an apply, 120 of 271

Try again when it is free. GET /api/v1/services/{name}/activity answers at once with the same, and the NetBox's page carries it while it lasts.

What happens after an apply

An apply returns as soon as NetBox has the objects. Reading back what the apply changed, including the objects NetBox created on its own such as a device's interfaces from its type, runs behind the response, so the next plan sees them. For a large design that reading-back takes a while, and the NetBox is busy for as long as it does.

When the copy is behind

If that reading-back fails, say NetBox stopped answering midway, Designs does not pretend it finished. The NetBox is marked as possibly behind, with the reason, and a plan made against it says so in its notes:

Designs' copy of 'netbox-prod' may be behind NetBox: reading back what the apply changed failed (...). Refresh everything from NetBox on the target, then plan again.

Refresh from NetBox normally replays only what NetBox's changelog says changed since the last read, which is quick. When the copy is marked behind, read everything again instead:

nbd service refresh netbox-prod --full

or POST /api/v1/services/{name}/refresh?full=true. The mark is cleared when the refresh completes.