Revision as of 21:43, 16 February 2013

Operational status for Quantum resources

• Launchpad Entry: api-operational-status
• Created: Salvatore Orlando
• Contributors: Salvatore Orlando & everybody else who wants to join!

At the Essex design summit it was agreed to augment Quantum resources with the concept of "Operational Status". This wiki page discusses the syntax and the semantics for this concept.

The need for the "Operational Status" concept

The Operational status reflects the current state of the resources managed by the plugin.

For instance, if the plugin asynchronously perform all the actions required for creating or updating a network or a port, there will be a lag of time in which the resource will not be operative. Examples of situations in which a resource might not be operative include faults, insufficient capabilities in the physical or virtual switching layer, or simply, in the case of ports, the fact that there's no attachment plugged into it (i.e.: link down).

By introducing this concept Quantum clients will become aware of the actual state of the resources managed by Quantum. In particular, this concept will help Quantum client deal with:

• Asynchronous behaviour of Quantum Plugins
• Failures in physical/virtual network infrastructure implementing Quantum Networks

The operational status will be added to network and port resources.; there's no need to add an operational status to attachments.

Operational Status semantics

The operational status simply describes the current availability state of a particular Quantum resource. It is quite different from the concept of administrative status which has already been introduced for ports in v1.0 of the Quantum API.

While the administrative status is controlled by the client which can programmatically activate or deactivate a port, the operational status is a read-only attribute that the client need to consume in order to understand whether a specific resource is actually working or not.

It is important to keep in mind that the operational status is an attribute of the API layer object, which is something different from the elements that actually provide the networking resources in the virtual/physical switching layer, as depicted in the picture below; the API layer object exists regardless of the status of the resources in the virtual/physical switching layer.

Therefore, when a resource is not operational, the Quantum API will still accept operations on that resource and dispatch them to the plugin. Should that resource be operationally unavailable, the behavior of the operation is then plugin specific. Nevertheless, the plugin accepts and performs any legal modification to the logical model. When such changes are propagated to the physical/virtual network infrastructure, there might be errors, which cause the ‘running’ configuration to be different from the ‘logical’ one. The operational status is the only way in which this situation is exposed to Quantum users.

Nevertheless, by exposing a consistent operational state for a resource, the Quantum API will guarantee a consistent behaviour for client regardless of the particular plugin.

Changes into Quantum API

The set of operations exposed by the Quantum API will not change for taking into account the operational status. The only difference will be an extra attribute returned in responses.

The operational status attribute will be an enumerative type, which can assume the following values:

• UP: the resource is operationally available;
• PROVISIONING: the plugin is creating/updating the components for the resource;
• DOWN: the resource is not operational; note: this status will be used also when a failure in the underlying infrastructure prevents
• UNKNOWN: the operational status is unavailable as the plugin does not support it. This state has a "transitional" purpose for allowing for progressive support from plugins, and is likely to be removed for the Essex release.

This implies that responses for GET operations on networks and ports will change as follows.

Network - XML

    <network
           id="8bec1293-16bd-4568-ba75-1f58bec0b4c3"
           name="test_network"
           op-status="UP" />

Network - JSON

{
   "network":
       {
           "id": "8bec1293-16bd-4568-ba75-1f58bec0b4c3",
           "name": "test_network",
           "op-status": "UP"
       }
}

Port - XML

<port
    id="98017ddc-efc8-4c25-a915-774b2a633855"
    state="DOWN"
    op-status="PROVISIONING"/>

Port - JSON

{
    "port":
        {
            "state": "DOWN",
            "id": "98017ddc-efc8-4c25-a915-774b2a633855",
            "op-status": "PROVISIONING"
        }
}

NOTE: The operational status attribute will be visible only to client explicitly using Quantum API v1.1. Also note that

the administrative state attribute will still be called just state in order to avoid backward-incompatible changes into the API.

Detailed description of unavailability causes

When a resource is operationally unavailable, it is perfectly reasonable for clients to query the API layer for an explanation, as the enum value for the operational status might not be enough.

In this case, a descriptive, plugin-specific, text attribute for the current status of the resource might be returned by the detail action, which is already available for both networks and ports. op-status-desc is the candidate name for such attribute. However, please bear in mind that this descriptive field will not be available in the first implementation proposal for the Quantum API, as its semantics need to be discussed better.