Provide Port Binding Information for Nova Live Migration¶

List Bindings¶

GET /v2.0/ports/{port_id}/bindings

{
    "bindings": [
        {
            "host_id": "source-host_id",
            "vif_type": "ovs",
            "vif_details": {
                "port_filter": true,
                "ovs_hybrid_plug": true
                },
            "profile": {},
            "vnic_type": "normal",
            "status": "active"
        },
        {
            "host_id": "target-host_id",
            "vif_type": "bridge",
            "vif_details": {
                "port_filter": true,
                },
            "profile": {},
            "vnic_type": "normal",
            "status": "inactive"
        },
    ]
}

More parameters see Show Binding

Important key features of list bindings:

• Compute bindings will currently be listed and a request for unsupported bindings will return ‘NotImplemented’ until the capability is introduced.
• All bindings will be listed and pagination will be used when many bindings are returned.

Show Binding¶

GET /v2.0/ports/{port_id}/bindings/{host_id}

{
    "binding": {
         "host_id": "target-host_id",
         "vif_type": "target-vif-type",
         "vif_details": {
             "port_filter": true,
             },
         "vnic_type": 'NORMAL',
         "profile": {},
         "status": "active"
     }
}

Important key features of show binding:

• DVR ports exposed in this resource will show the real vif_type of ‘distributed’ ports as they are stored in DistributedPortBindings, i.e. ovs.

Create Binding¶

POST /v2.0/ports/{port_id}/bindings

{
    "binding": {
        "host_id": "target-host_id"
    }
}

Response parameters

see List Bindings

{
    "binding": {
        "host_id": "target-host_id",
        "vif_type": "ovs",
        "vif_details": {
            "port_filter": true,
            "ovs_hybrid_plug": true
            },
         "vnic_type": 'NORMAL',
         "profile": {},
         "status": "active"
    }
}

If the binding fails, a new return code of 4xx or 5xx should be returned. This differs from today where a failed binding returns a 2xx response code and the vif_type is set to “binding_failed”.

Important key features of update/create binding:

• By default, the status will be active when creating a port binding. If a binding is created, doesn’t exist already, and an existing binding is already active, the binding will default to inactive, requiring the operator to activate the new binding.
• If a binding being added already exists, a 4xx will be returned.
• A compute port can only have 1 active binding at a time. This is not an enforcement by Neutron, but a result of the operation surrounding PortBinding. This feature expands the capability of having multiple bindings, but will only allow for 1 active binding for compute ports.
• At this time, creation of a binding will be limited to compute ports.
• The existing API is not touched, which will return host_id:{host_id} as the current active binding.
• Activating an inactive compute binding will deactivate the current active binding.

Update Binding¶

PUT /v2.0/ports/{port_id}/bindings/{host_id}

All create parameters are valid for update as well. See Create Binding.

{
    "binding": {
        "vnic_type": 'NORMAL',
        "profile": {}
    }
}

Response parameters

see Show Binding

{
    "binding": {
        "host_id": "target-host_id",
        "vif_type": "ovs",
        "vif_details": {
            "port_filter": true,
            "ovs_hybrid_plug": true
            },
        "vnic_type": 'NORMAL',
        "profile": {"foo": "bar"},
        "status": "active"
    }
}

On failed binding, a 4xx or 5xx return code should be returned.

Activating an Inactive Binding¶

PUT /v2.0/ports/{port_id}/bindings/{host_id}/activate

Response parameters

see Show Binding

{
    "binding": {
        "host_id": "target-host_id",
        "vif_type": "ovs",
        "vif_details": {
            "port_filter": true,
            "ovs_hybrid_plug": true
            },
        "vnic_type": 'NORMAL',
        "profile": {"foo":"bar"},
        "status": "active"
    }
}

Important key features of activate binding:

• Activating a compute binding that is inactive will deactivate the existing active binding, as a compute port can only have 1 binding active at a time.
• Operation will be limited to compute ports.
• Attempting to activate an existing active binding will return a 4xx.
• Returns 5xx if activating the binding fails.

Delete Binding¶

DELETE /v2.0/ports/{port_id}/bindings/{host_id}

This operation does not accept a request body and does not return a response body.

Important key features of delete binding:

• Active/Inactive bindings can be removed.
• Deleting an active compute port binding, where an inactive binding exists does not activate the binding. The operator will be required to explicitly activate the binding.

Overlap Between Existing vs New APIs¶

All the functionality of the existing API will be covered by the new API as well. This section describes the overlap.

Effects on Existing APIs¶

Slight adjustment to existing APIs:

• Show Port will still just show the binding like today. For compute ports, it would only show the active binding.
• Create Port will create an unbound binding as before, but with the status of active.
• Update Port with host_id will still re-trigger port binding for a host. The difference will be update_port() will only action on the active binding.
• vif_type is set to “binding_failed” and http code 2xx is still used on failed port binding when binding is triggered via the existing port binding extension.

API Visibility¶

A normal user should not be able to trigger any create/update/delete/activate actions. This should only be possible via some special service user or the admin role.

Status Usage¶

The status column in PortBinding will store an additional state ‘inactive’ where the current states are ‘active’ and ‘down’. Neutron-lib will only require the addition of PORT_BINDING_STATUS_ACTIVE and PORT_BINDING_STATUS_INACTIVE.

from neutron_lib import constants as const

const.PORT_BINDING_STATUS_ACTIVE
const.PORT_BINDING_STATUS_INACTIVE

Create/Update/Delete Port¶

New methods will be introduced in support of the new sub resource under ports, but the current create_port(), update_port() and delete_port() will be modified to only act on active bindings in the PortBinding table.

Today, create_port() adds an empty unbound binding in PortBinding and the following changes will be made in support of this spec:

• Create an unbound binding with status active in the PortBinding table.

In addition, update_port() will be adjusted for active status with the following changes:

• Update will only change binding information on the active binding in the PortBinding table.

Finally, delete_port() will be adjusted for active status with the following changes:

• Delete will only act on the active binding in the PortBinding table.

Activate RPC Port Update/Delete¶

The existing port_update and port_delete RPC message will be adjusted to send, when the agent retrieves device information with get_devices_details_list_and_failed_devices, specific binding information for the host regardless of binding state. This will allow the addition of additional plumbing to occur as follows:

• Activate will result in a port_update, which will pass the relative binding information for the host and dictate the transition from inactive to active in the get_devices_details_list_and_failed_devices response. This will allow for a GARP to be sent out, updating the topology to a change in status.
• Activate will result in a port_delete rpc call to the source host, removing the source VIF. This will need to be accomplished due to Nova not being able to issue a delete port, as the port still exists on a different host. The binding will remain in an inactive state where binding information has been populated, but the port, from an agent perspective, will not exist. In addition, the transition from active to inactive will be indicated in the rpc call, influencing the update_device_list to not update the port state.

In the case where push-notifications are implemented for ports under Blueprint [10] the get_devices_details_list_and_failed_devices would not be adjusted for transition state. Instead, the binding transition state would be sent to the agent as part of the port object. The remaining actions are the same.