neutron_lib.plugins.ml2 package¶

Submodules¶

neutron_lib.plugins.ml2.api module¶

class neutron_lib.plugins.ml2.api.ExtensionDriver¶

Bases: object

Define stable abstract interface for ML2 extension drivers.

An extension driver extends the core resources implemented by the ML2 plugin with additional attributes. Methods that process create and update operations for these resources validate and persist values for extended attributes supplied through the API. Other methods extend the resource dictionaries returned from the API operations with the values of the extended attributes.

extend_network_dict(session, base_model, result)¶

Add extended attributes to network dictionary.

Parameters:	session – database session base_model – network model data result – network dictionary to extend

Called inside transaction context on session to add any extended attributes defined by this driver to a network dictionary to be used for mechanism driver calls and/or returned as the result of a network operation.

extend_port_dict(session, base_model, result)¶

Add extended attributes to port dictionary.

Parameters:	session – database session base_model – port model data result – port dictionary to extend

Called inside transaction context on session to add any extended attributes defined by this driver to a port dictionary to be used for mechanism driver calls and/or returned as the result of a port operation.

extend_subnet_dict(session, base_model, result)¶

Add extended attributes to subnet dictionary.

Parameters:	session – database session base_model – subnet model data result – subnet dictionary to extend

Called inside transaction context on session to add any extended attributes defined by this driver to a subnet dictionary to be used for mechanism driver calls and/or returned as the result of a subnet operation.

extension_alias¶

Supported extension alias.

Return the alias identifying the core API extension supported by this driver. Do not declare if API extension handling will be left to a service plugin, and we just need to provide core resource extension and updates.

extension_aliases¶

List of extension aliases supported by the driver.

Return a list of aliases identifying the core API extensions supported by the driver. By default this just returns the extension_alias property for backwards compatibility.

initialize()¶

Perform driver initialization.

Called after all drivers have been loaded and the database has been initialized. No abstract methods defined below will be called prior to this method being called.

process_create_network(plugin_context, data, result)¶

Process extended attributes for create network.

Parameters:	plugin_context – plugin request context data – dictionary of incoming network data result – network dictionary to extend

Called inside transaction context on plugin_context.session to validate and persist any extended network attributes defined by this driver. Extended attribute values must also be added to result.

process_create_port(plugin_context, data, result)¶

Process extended attributes for create port.

Parameters:	plugin_context – plugin request context data – dictionary of incoming port data result – port dictionary to extend

Called inside transaction context on plugin_context.session to validate and persist any extended port attributes defined by this driver. Extended attribute values must also be added to result.

process_create_subnet(plugin_context, data, result)¶

Process extended attributes for create subnet.

Parameters:	plugin_context – plugin request context data – dictionary of incoming subnet data result – subnet dictionary to extend

Called inside transaction context on plugin_context.session to validate and persist any extended subnet attributes defined by this driver. Extended attribute values must also be added to result.

process_update_network(plugin_context, data, result)¶

Process extended attributes for update network.

Parameters:	plugin_context – plugin request context data – dictionary of incoming network data result – network dictionary to extend

Called inside transaction context on plugin_context.session to validate and update any extended network attributes defined by this driver. Extended attribute values, whether updated or not, must also be added to result.

process_update_port(plugin_context, data, result)¶

Process extended attributes for update port.

Parameters:	plugin_context – plugin request context data – dictionary of incoming port data result – port dictionary to extend

Called inside transaction context on plugin_context.session to validate and update any extended port attributes defined by this driver. Extended attribute values, whether updated or not, must also be added to result.

process_update_subnet(plugin_context, data, result)¶

Process extended attributes for update subnet.

Parameters:	plugin_context – plugin request context data – dictionary of incoming subnet data result – subnet dictionary to extend

Called inside transaction context on plugin_context.session to validate and update any extended subnet attributes defined by this driver. Extended attribute values, whether updated or not, must also be added to result.

class neutron_lib.plugins.ml2.api.ML2TypeDriver¶

Bases: neutron_lib.plugins.ml2.api._TypeDriverBase

Define abstract interface for ML2 type drivers.

ML2 type drivers each support a specific network_type for provider and/or tenant network segments. Type drivers must implement this abstract interface, which defines the API by which the plugin uses the driver to manage the persistent type-specific resource allocation state associated with network segments of that type.

Network segments are represented by segment dictionaries using the NETWORK_TYPE, PHYSICAL_NETWORK, and SEGMENTATION_ID keys defined above, corresponding to the provider attributes. Future revisions of the TypeDriver API may add additional segment dictionary keys. Attributes not applicable for a particular network_type may either be excluded or stored as None.

ML2TypeDriver passes context as argument for: - reserve_provider_segment - allocate_tenant_segment - release_segment - get_allocation

allocate_tenant_segment(context)¶

Allocate resource for a new tenant network segment.

Parameters:	context – instance of neutron context with DB session
Returns:	segment dictionary using keys defined above

Called inside transaction context on session to allocate a new tenant network, typically from a type-specific resource pool. If successful, return a segment dictionary describing the segment. If tenant network segment cannot be allocated (i.e. tenant networks not supported or resource pool is exhausted), return None.

release_segment(context, segment)¶

Release network segment.

Parameters:	context – instance of neutron context with DB session segment – segment dictionary using keys defined above

Called inside transaction context on session to release a tenant or provider network’s type-specific resource. Runtime errors are not expected, but raising an exception will result in rollback of the transaction.

reserve_provider_segment(context, segment)¶

Reserve resource associated with a provider network segment.

Parameters:	context – instance of neutron context with DB session segment – segment dictionary
Returns:	segment dictionary

Called inside transaction context on session to reserve the type-specific resource for a provider network segment. The segment dictionary passed in was returned by a previous validate_provider_segment() call.

class neutron_lib.plugins.ml2.api.MechanismDriver¶

Bases: object

Define stable abstract interface for ML2 mechanism drivers.

A mechanism driver is called on the creation, update, and deletion of networks and ports. For every event, there are two methods that get called - one within the database transaction (method suffix of _precommit), one right afterwards (method suffix of _postcommit).

Exceptions raised by methods called inside the transaction can rollback, but should not make any blocking calls (for example, REST requests to an outside controller). Methods called after transaction commits can make blocking external calls, though these will block the entire process. Exceptions raised in calls after the transaction commits may cause the associated resource to be deleted.

Because rollback outside of the transaction is not done in the update network/port case, all data validation must be done within methods that are part of the database transaction.

bind_port(context)¶

Attempt to bind a port.

Parameters:	context – PortContext instance describing the port

This method is called outside any transaction to attempt to establish a port binding using this mechanism driver. Bindings may be created at each of multiple levels of a hierarchical network, and are established from the top level downward. At each level, the mechanism driver determines whether it can bind to any of the network segments in the context.segments_to_bind property, based on the value of the context.host property, any relevant port or network attributes, and its own knowledge of the network topology. At the top level, context.segments_to_bind contains the static segments of the port’s network. At each lower level of binding, it contains static or dynamic segments supplied by the driver that bound at the level above. If the driver is able to complete the binding of the port to any segment in context.segments_to_bind, it must call context.set_binding with the binding details. If it can partially bind the port, it must call context.continue_binding with the network segments to be used to bind at the next lower level.

If the binding results are committed after bind_port returns, they will be seen by all mechanism drivers as update_port_precommit and update_port_postcommit calls. But if some other thread or process concurrently binds or updates the port, these binding results will not be committed, and update_port_precommit and update_port_postcommit will not be called on the mechanism drivers with these results. Because binding results can be discarded rather than committed, drivers should avoid making persistent state changes in bind_port, or else must ensure that such state changes are eventually cleaned up.

Implementing this method explicitly declares the mechanism driver as having the intention to bind ports. This is inspected by the QoS service to identify the available QoS rules you can use with ports.

check_vlan_transparency(context)¶

Check if the network supports vlan transparency.

Parameters:	context – NetworkContext instance describing the network.

Check if the network supports vlan transparency or not.

create_network_postcommit(context)¶

Create a network.

Parameters:	context – NetworkContext instance describing the new network.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will cause the deletion of the resource.

create_network_precommit(context)¶

Allocate resources for a new network.

Parameters:	context – NetworkContext instance describing the new network.

Create a new network, allocating resources as necessary in the database. Called inside transaction context on session. Call cannot block. Raising an exception will result in a rollback of the current transaction.

create_port_postcommit(context)¶

Create a port.

Parameters:	context – PortContext instance describing the port.

Called after the transaction completes. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will result in the deletion of the resource.

create_port_precommit(context)¶

Allocate resources for a new port.

Parameters:	context – PortContext instance describing the port.

Create a new port, allocating resources as necessary in the database. Called inside transaction context on session. Call cannot block. Raising an exception will result in a rollback of the current transaction.

create_subnet_postcommit(context)¶

Create a subnet.

Parameters:	context – SubnetContext instance describing the new subnet.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will cause the deletion of the resource.

create_subnet_precommit(context)¶

Allocate resources for a new subnet.

Parameters:	context – SubnetContext instance describing the new subnet.

Create a new subnet, allocating resources as necessary in the database. Called inside transaction context on session. Call cannot block. Raising an exception will result in a rollback of the current transaction.

delete_network_postcommit(context)¶

Delete a network.

Parameters:	context – NetworkContext instance describing the current state of the network, prior to the call to delete it.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Runtime errors are not expected, and will not prevent the resource from being deleted.

delete_network_precommit(context)¶

Delete resources for a network.

Parameters:	context – NetworkContext instance describing the current state of the network, prior to the call to delete it.

Delete network resources previously allocated by this mechanism driver for a network. Called inside transaction context on session. Runtime errors are not expected, but raising an exception will result in rollback of the transaction.

delete_port_postcommit(context)¶

Delete a port.

Parameters:	context – PortContext instance describing the current state of the port, prior to the call to delete it.

Called after the transaction completes. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Runtime errors are not expected, and will not prevent the resource from being deleted.

delete_port_precommit(context)¶

Delete resources of a port.

Parameters:	context – PortContext instance describing the current state of the port, prior to the call to delete it.

Called inside transaction context on session. Runtime errors are not expected, but raising an exception will result in rollback of the transaction.

delete_subnet_postcommit(context)¶

Delete a subnet.

Parameters:	context – SubnetContext instance describing the current state of the subnet, prior to the call to delete it.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Runtime errors are not expected, and will not prevent the resource from being deleted.

delete_subnet_precommit(context)¶

Delete resources for a subnet.

Parameters:	context – SubnetContext instance describing the current state of the subnet, prior to the call to delete it.

Delete subnet resources previously allocated by this mechanism driver for a subnet. Called inside transaction context on session. Runtime errors are not expected, but raising an exception will result in rollback of the transaction.

filter_hosts_with_segment_access(context, segments, candidate_hosts, agent_getter)¶

Filter hosts with access to at least one segment.

Returns:	a set with a subset of candidate_hosts.

A driver can overload this method to return a subset of candidate_hosts with the ones with access to at least one segment.

Default implementation returns all hosts to disable filtering (backward compatibility).

get_workers()¶

Get any NeutronWorker instances that should have their own process

Any driver that needs to run processes separate from the API or RPC workers, can return a sequence of NeutronWorker instances.

initialize()¶

Perform driver initialization.

Called after all drivers have been loaded and the database has been initialized. No abstract methods defined below will be called prior to this method being called.

classmethod is_host_filtering_supported()¶

update_network_postcommit(context)¶

Update a network.

Parameters:	context – NetworkContext instance describing the new state of the network, as well as the original state prior to the update_network call.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will cause the deletion of the resource.

update_network_postcommit is called for all changes to the network state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

update_network_precommit(context)¶

Update resources of a network.

Parameters:	context – NetworkContext instance describing the new state of the network, as well as the original state prior to the update_network call.

Update values of a network, updating the associated resources in the database. Called inside transaction context on session. Raising an exception will result in rollback of the transaction.

update_network_precommit is called for all changes to the network state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

update_port_postcommit(context)¶

Update a port.

Parameters:	context – PortContext instance describing the new state of the port, as well as the original state prior to the update_port call.

Called after the transaction completes. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will result in the deletion of the resource.

update_port_postcommit is called for all changes to the port state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

update_port_precommit(context)¶

Update resources of a port.

Parameters:	context – PortContext instance describing the new state of the port, as well as the original state prior to the update_port call.

Called inside transaction context on session to complete a port update as defined by this mechanism driver. Raising an exception will result in rollback of the transaction.

update_port_precommit is called for all changes to the port state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

update_subnet_postcommit(context)¶

Update a subnet.

Parameters:	context – SubnetContext instance describing the new state of the subnet, as well as the original state prior to the update_subnet call.

Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not drastically affect performance. Raising an exception will cause the deletion of the resource.

update_subnet_postcommit is called for all changes to the subnet state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

update_subnet_precommit(context)¶

Update resources of a subnet.

Parameters:	context – SubnetContext instance describing the new state of the subnet, as well as the original state prior to the update_subnet call.

Update values of a subnet, updating the associated resources in the database. Called inside transaction context on session. Raising an exception will result in rollback of the transaction.

update_subnet_precommit is called for all changes to the subnet state. It is up to the mechanism driver to ignore state or state changes that it does not know or care about.

class neutron_lib.plugins.ml2.api.NetworkContext¶

Bases: object

Context passed to MechanismDrivers for changes to network resources.

A NetworkContext instance wraps a network resource. It provides helper methods for accessing other relevant information. Results from expensive operations are cached so that other MechanismDrivers can freely access the same information.

current¶

Return the network in its current configuration.

Return the network, as defined by NeutronPluginBaseV2. create_network and all extensions in the ml2 plugin, with all its properties ‘current’ at the time the context was established.

network_segments¶

Return the segments associated with this network resource.

original¶

Return the network in its original configuration.

Return the network, with all its properties set to their original values prior to a call to update_network. Method is only valid within calls to update_network_precommit and update_network_postcommit.

class neutron_lib.plugins.ml2.api.PortContext¶

Bases: object

Context passed to MechanismDrivers for changes to port resources.

A PortContext instance wraps a port resource. It provides helper methods for accessing other relevant information. Results from expensive operations are cached so that other MechanismDrivers can freely access the same information.

allocate_dynamic_segment(segment)¶

Allocate a dynamic segment.

Parameters:	segment – A partially or fully specified segment dictionary

Called by the MechanismDriver.bind_port, create_port or update_port to dynamically allocate a segment for the port using the partial segment specified. The segment dictionary can be a fully or partially specified segment. At a minimum it needs the network_type populated to call on the appropriate type driver.

binding_levels¶

Return dictionaries describing the current binding levels.

This property returns a list of dictionaries describing each binding level if the port is bound or partially bound, or None if the port is unbound. Each returned dictionary contains the name of the bound driver under the BOUND_DRIVER key, and the bound segment dictionary under the BOUND_SEGMENT key.

The first entry (index 0) describes the top-level binding, which always involves one of the port’s network’s static segments. In the case of a hierarchical binding, subsequent entries describe the lower-level bindings in descending order, which may involve dynamic segments. Adjacent levels where different drivers bind the same static or dynamic segment are possible. The last entry (index -1) describes the bottom-level binding that supplied the port’s binding:vif_type and binding:vif_details attribute values.

Within calls to MechanismDriver.bind_port, descriptions of the levels above the level currently being bound are returned.

bottom_bound_segment¶

Return the current bottom-level bound segment dictionary.

This property returns the current bottom-level bound segment dictionary, or None if the port is unbound. For a bound port, bottom_bound_segment is equivalent to binding_levels[-1][BOUND_SEGMENT], and returns the segment whose binding supplied the port’s binding:vif_type and binding:vif_details attribute values.

continue_binding(segment_id, next_segments_to_bind)¶

Continue binding the port with different segments.

Parameters:	segment_id – Network segment partially bound for the port. next_segments_to_bind – Segments to continue binding with.

This method is called by MechanismDriver.bind_port to indicate it was able to partially bind the port, but that one or more additional mechanism drivers are required to complete the binding. The segment_id must identify an item in the current value of the segments_to_bind property. The list of segments IDs passed as next_segments_to_bind identify dynamic (or static) segments of the port’s network that will be used to populate segments_to_bind for the next lower level of a hierarchical binding.

current¶

Return the port in its current configuration.

Return the port, as defined by NeutronPluginBaseV2. create_port and all extensions in the ml2 plugin, with all its properties ‘current’ at the time the context was established.

host¶

Return the host with which the port is associated.

In the context of a host-specific operation on a distributed port, the host property indicates the host for which the port operation is being performed. Otherwise, it is the same value as current[‘binding:host_id’].

host_agents(agent_type)¶

Get agents of the specified type on port’s host.

Parameters:	agent_type – Agent type identifier
Returns:	List of neutron.db.models.agent.Agent records

network¶

Return the NetworkContext associated with this port.

original¶

Return the port in its original configuration.

Return the port, with all its properties set to their original values prior to a call to update_port. Method is only valid within calls to update_port_precommit and update_port_postcommit.

original_binding_levels¶

Return dictionaries describing the original binding levels.

This property returns a list of dictionaries describing each original binding level if the port was previously bound, or None if the port was unbound. The content is as described for the binding_levels property.

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

original_bottom_bound_segment¶

Return the original bottom-level bound segment dictionary.

This property returns the original bottom-level bound segment dictionary, or None if the port was previously unbound. For a previously bound port, original_bottom_bound_segment is equivalent to original_binding_levels[-1][BOUND_SEGMENT], and returns the segment whose binding supplied the port’s previous binding:vif_type and binding:vif_details attribute values.

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

original_host¶

Return the original host with which the port was associated.

In the context of a host-specific operation on a distributed port, the original_host property indicates the host for which the port operation is being performed. Otherwise, it is the same value as original[‘binding:host_id’].

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

original_status¶

Return the status of the original port.

The method is only valid within calls to update_port_precommit and update_port_postcommit.

original_top_bound_segment¶

Return the original top-level bound segment dictionary.

This property returns the original top-level bound segment dictionary, or None if the port was previously unbound. For a previously bound port, original_top_bound_segment is equivalent to original_binding_levels[0][BOUND_SEGMENT], and returns one of the port’s network’s static segments.

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

original_vif_details¶

Return the original vif_details of the port.

In the context of a host-specific operation on a distributed port, the original_vif_details property describes the original binding for the host for which the port operation is being performed. Otherwise, it is the same value as original[‘binding:vif_details’].

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

original_vif_type¶

Return the original vif_type of the port.

In the context of a host-specific operation on a distributed port, the original_vif_type property indicates original binding state for the host for which the port operation is being performed. Otherwise, it is the same value as original[‘binding:vif_type’].

This property is only valid within calls to update_port_precommit and update_port_postcommit. It returns None otherwise.

release_dynamic_segment(segment_id)¶

Release an allocated dynamic segment.

Parameters:	segment_id – UUID of the dynamic network segment.

Called by the MechanismDriver.delete_port or update_port to release the dynamic segment allocated for this port.

segments_to_bind¶

Return the list of segments with which to bind the port.

This property returns the list of segment dictionaries with which the mechanism driver may bind the port. When establishing a top-level binding, these will be the port’s network’s static segments. For each subsequent level, these will be the segments passed to continue_binding by the mechanism driver that bound the level above.

This property is only valid within calls to MechanismDriver.bind_port. It returns None otherwise.

set_binding(segment_id, vif_type, vif_details, status=None)¶

Set the bottom-level binding for the port.

Parameters:	segment_id – Network segment bound for the port. vif_type – The VIF type for the bound port. vif_details – Dictionary with details for VIF driver. status – Port status to set if not None.

This method is called by MechanismDriver.bind_port to indicate success and specify binding details to use for port. The segment_id must identify an item in the current value of the segments_to_bind property.

status¶

Return the status of the current port.

top_bound_segment¶

Return the current top-level bound segment dictionary.

This property returns the current top-level bound segment dictionary, or None if the port is unbound. For a bound port, top_bound_segment is equivalent to binding_levels[0][BOUND_SEGMENT], and returns one of the port’s network’s static segments.

vif_details¶

Return the vif_details describing the binding of the port.

In the context of a host-specific operation on a distributed port, the vif_details property describes the binding for the host for which the port operation is being performed. Otherwise, it is the same value as current[‘binding:vif_details’].

vif_type¶

Return the vif_type indicating the binding state of the port.

In the context of a host-specific operation on a distributed port, the vif_type property indicates the binding state for the host for which the port operation is being performed. Otherwise, it is the same value as current[‘binding:vif_type’].

class neutron_lib.plugins.ml2.api.SubnetContext¶

Bases: object

Context passed to MechanismDrivers for changes to subnet resources.

A SubnetContext instance wraps a subnet resource. It provides helper methods for accessing other relevant information. Results from expensive operations are cached so that other MechanismDrivers can freely access the same information.

current¶

Return the subnet in its current configuration.

Return the subnet, as defined by NeutronPluginBaseV2. create_subnet and all extensions in the ml2 plugin, with all its properties ‘current’ at the time the context was established.

original¶

Return the subnet in its original configuration.

Return the subnet, with all its properties set to their original values prior to a call to update_subnet. Method is only valid within calls to update_subnet_precommit and update_subnet_postcommit.

class neutron_lib.plugins.ml2.api.TypeDriver¶

Bases: neutron_lib.plugins.ml2.api._TypeDriverBase

Define abstract interface for ML2 type drivers.

ML2 type drivers each support a specific network_type for provider and/or tenant network segments. Type drivers must implement this abstract interface, which defines the API by which the plugin uses the driver to manage the persistent type-specific resource allocation state associated with network segments of that type.

Network segments are represented by segment dictionaries using the NETWORK_TYPE, PHYSICAL_NETWORK, and SEGMENTATION_ID keys defined above, corresponding to the provider attributes. Future revisions of the TypeDriver API may add additional segment dictionary keys. Attributes not applicable for a particular network_type may either be excluded or stored as None.

TypeDriver passes session as argument for: - reserve_provider_segment - allocate_tenant_segment - release_segment - get_allocation

allocate_tenant_segment(session)¶

Allocate resource for a new tenant network segment.

Parameters:	session – database session
Returns:	segment dictionary using keys defined above

Called inside transaction context on session to allocate a new tenant network, typically from a type-specific resource pool. If successful, return a segment dictionary describing the segment. If tenant network segment cannot be allocated (i.e. tenant networks not supported or resource pool is exhausted), return None.

release_segment(session, segment)¶

Release network segment.

Parameters:	session – database session segment – segment dictionary using keys defined above

Called inside transaction context on session to release a tenant or provider network’s type-specific resource. Runtime errors are not expected, but raising an exception will result in rollback of the transaction.

reserve_provider_segment(session, segment)¶

Reserve resource associated with a provider network segment.

Parameters:	session – database session segment – segment dictionary
Returns:	segment dictionary

Called inside transaction context on session to reserve the type-specific resource for a provider network segment. The segment dictionary passed in was returned by a previous validate_provider_segment() call.

Module contents¶