Repository navigation
[Networks API] The network lifecycle is described with three different sets of transitions #157
Description
Problem description
The lifecycle of a Dedicated Network appears in three places, and no two agree on the transitions.
NetworkStatus (code/API_definitions/dedicated-network.yaml:405-411):
REQUESTED- The DN is requested, but not approved. Possible transitions to RESERVED, ACTIVATED and TERMINATED statesRESERVED- Request is accepted by the CSP (CSP has committed the requested resources), but the Network cannot be used (outside of requested time-window)ACTIVATED- Network turns from reserved into Activated. Now, devices with access can use the network. Possible transitions to RESERVED or TERMINATED statesTERMINATED- The Network resource is used and up for deletion. The API does not allow any action (except delete).
The lifecycle diagram (documentation/API_documentation/DedicatedNetworks_GeneralDescription.md:190-197):
stateDiagram-v2
[*] --> REQUESTED: POST /networks
REQUESTED --> RESERVED: Use is confirmed (Service Time not reached)
RESERVED --> ACTIVATED: Service Time reached
ACTIVATED --> TERMINATED: Service Time expires
REQUESTED --> ACTIVATED: Use is confirmed (Service Time already reached)
RESERVED --> TERMINATED: Failed to reserve resources
And the prose beneath it (GeneralDescription.md:200-212), which includes:
The network may enter the TERMINATED state directly after the REQUESTED state if the API Provider could not complete the resource reservation.
Three disagreements:
| Transition | NetworkStatus enum |
Diagram | Prose |
|---|---|---|---|
ACTIVATED → RESERVED |
states it ("Possible transitions to RESERVED or TERMINATED") | not present | not present |
Reservation failure → TERMINATED |
not attributed to a source state | from RESERVED |
from REQUESTED |
RESERVED's own transitions |
none stated (unlike the REQUESTED and ACTIVATED bullets, which each name theirs) |
RESERVED → ACTIVATED, RESERVED → TERMINATED |
not stated |
So a reader cannot tell whether a network can return from ACTIVATED to RESERVED, and cannot tell
whether "the reservation could not be completed" is something that happens to a REQUESTED network or
a RESERVED one.
Separately, info.description:36 reads:
Find a detailed description of the network states here.
The link is empty. Its evident target is the section quoted above.
Possible evolution
One authoritative statement of the transitions, with the enum description, the diagram and the prose
all matching it — and the empty link filled in to point at it, the way the Accesses API's row in the
same document already links the anchor (:49).
We are not proposing which edges are real — that is implementation knowledge — only that the three
places need to agree once it is decided.
Additional context
None.
Activity