OpenStack Neutron VMware NSX REST API Extension Refence Now Available

Forward

The OpenStack neutron team has done a fantastic job consolidating the neutron REST API reference source into the neutron-lib tree (note that this is an ongoing effort). Once built, the resulting documentation is published to the docs site and is what you see when viewing the neutron api-ref. While stadium projects can contribute their api-ref to the neutron-lib tree, non-stadium projects (such as the numerous neutron plugins including the VMware NSX plugin) must publish/maintain their own API reference documentation.

VMware NSX Neutron Plugin REST API Reference

We recently decided the most straight forward place to publish the OpenStack neutron VMware NSX plugin REST api-ref was right alongside the plugin source code. This document is in markdown format and can be found at vmware-nsx/api-ref/rest.md.

OpenStack neutron VMware NSX api-ref rendered in markdown

Moving forward, our goal is to keep the VMware NSX plugin api-ref in sync with the plugin source code so consumers can always find the api-ref for the release of the plugin they are using. Consumers using the VMware NSX neutron plugin for release REL can access the following URL to view its api-ref:

https://github.com/openstack/vmware-nsx/tree/stable/REL/api-ref/rest.md

However since we just committed this documentation, consumers will only be able to access the api-ref using the above URL starting with the Ocata release (for now it can be accessed from the master branch of the plugin source repository).

We look forward to any feedback on this api-ref so feel free to open a bug, or reach out to me directly.

What's new with neutron-lib 0.4.0

Forward

OpenStack neutron-lib version 0.4.0 was recently released to PyPI  and contains a number of updates to constants, db, exceptions, policy and utils.

The complete list of public API changes are summarized below (and can be viewed on github):

New API Signatures
-----------------------------------------------------
neutron_lib.constants.DEVICE_OWNER_BAREMETAL_PREFIX = baremetal:
neutron_lib.db.constants.DESCRIPTION_FIELD_SIZE = 255
neutron_lib.db.constants.DEVICE_ID_FIELD_SIZE = 255
neutron_lib.db.constants.DEVICE_OWNER_FIELD_SIZE = 255
neutron_lib.db.constants.IP_ADDR_FIELD_SIZE = 64
neutron_lib.db.constants.LONG_DESCRIPTION_FIELD_SIZE = 1024
neutron_lib.db.constants.MAC_ADDR_FIELD_SIZE = 32
neutron_lib.db.constants.NAME_FIELD_SIZE = 255
neutron_lib.db.constants.PROJECT_ID_FIELD_SIZE = 255
neutron_lib.db.constants.RESOURCE_TYPE_FIELD_SIZE = 255
neutron_lib.db.constants.STATUS_FIELD_SIZE = 16
neutron_lib.db.constants.UUID_FIELD_SIZE = 36
neutron_lib.db.model_base.BASEV2 = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasId
neutron_lib.db.model_base.HasId.id = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasProject
neutron_lib.db.model_base.HasProject.get_tenant_id(self)
neutron_lib.db.model_base.HasProject.project_id = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasProject.set_tenant_id(self, value)
neutron_lib.db.model_base.HasProject.tenant_id(cls)
neutron_lib.db.model_base.HasProjectNoIndex
neutron_lib.db.model_base.HasProjectNoIndex.project_id = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasProjectPrimaryKey
neutron_lib.db.model_base.HasProjectPrimaryKey.project_id = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasProjectPrimaryKeyIndex
neutron_lib.db.model_base.HasProjectPrimaryKeyIndex.project_id = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasStatusDescription
neutron_lib.db.model_base.HasStatusDescription.status = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.HasStatusDescription.status_description = PYIR UNKNOWN VALUE
neutron_lib.db.model_base.NeutronBaseV2
neutron_lib.db.utils.is_retriable(exception)
neutron_lib.db.utils.reraise_as_retryrequest(function)
neutron_lib.exceptions.DeviceNotFoundError
neutron_lib.exceptions.DeviceNotFoundError.message = Device '%(device_name)s' does not exist.
neutron_lib.exceptions.MultipleExceptions
neutron_lib.exceptions.PolicyCheckError
neutron_lib.exceptions.PolicyCheckError.message = Failed to check policy %(policy)s because %(reason)s.
neutron_lib.exceptions.PolicyInitError
neutron_lib.exceptions.PolicyInitError.message = Failed to initialize policy %(policy)s because %(reason)s.
neutron_lib.hacking.checks.check_no_eventlet_imports(logical_line)
neutron_lib.hacking.translation_checks.check_delayed_string_interpolation(logical_line, filename, noqa)
neutron_lib.policy.check_is_admin(context)
neutron_lib.policy.check_is_advsvc(context)
neutron_lib.policy.init(conf=PYIR UNKNOWN VALUE, policy_file=None)
neutron_lib.policy.refresh(policy_file=None)
neutron_lib.policy.reset()
neutron_lib.utils.file.ensure_dir(dir_path)
neutron_lib.utils.file.replace_file(file_name, data, file_mode=420)
neutron_lib.utils.helpers._(s)
neutron_lib.utils.helpers.camelize(s)
neutron_lib.utils.helpers.compare_elements(a, b)
neutron_lib.utils.helpers.dict2str(dic)
neutron_lib.utils.helpers.dict2tuple(d)
neutron_lib.utils.helpers.diff_list_of_dict(old_list, new_list)
neutron_lib.utils.helpers.get_random_string(length)
neutron_lib.utils.helpers.parse_mappings(mapping_list, unique_values=True, unique_keys=True)
neutron_lib.utils.helpers.round_val(val)
neutron_lib.utils.helpers.safe_decode_utf8(s)
neutron_lib.utils.helpers.safe_sort_key(value)
neutron_lib.utils.helpers.str2dict(string)
neutron_lib.utils.host.cpu_count()
neutron_lib.utils.net.get_hostname()
-----------------------------------------------------

Removed API Signatures
-----------------------------------------------------
-----------------------------------------------------

Changed API Signatures
-----------------------------------------------------
-----------------------------------------------------

Note that the report above does not include private API changes, tests, etc.. As always consumers should refrain from using private APIs as they are susceptible to change at any time.

In the previous neutron-lib release blog we dug into some of the actual API usage with sample python code. However as neutron-lib 0.4.0 has a number of new APIs, we'll stick a high-level overview in this post and forgo the python code samples.

Database

As shown in the public API report above, a number of classes, functions and constants have been re-homed from neutron.db into neutron_lib.db (for more details see the review). The goal here is to centralize common database functionality used across neutron stadium projects into neutron-lib. As part of this effort we need to be careful not to pull over any database functionality that couples neutron-lib to neutron.

In neutron-lib 0.4.0 neutron_lib.db.constants was added and defines a number of common database field sizes for use in place of statically typed field size values. For example, instead of using 255 to define the size of a description field, consumers can use the neutron_lib.db.constants.DESCRIPTION_FIELD_SIZE constant.

Additionally neutron_lib.db.model_base was added. This module contains a handful of "barebones" neutron base model definitions/mix-ins such as HasProject and others. Consumers can now start replacing their use of these models from neutron with the definition in neutron_lib.db.model_base.

Two new functions were also added to neutron_lib.db.utils (see API report above). These functions have been re-homed from neutron.db.api and are now ready for use.

Exceptions

A few exceptions where re-homed to neutron-lib including DeviceNotFoundError, MultipleExceptions, PolicyCheckError and PolicyInitError. These exceptions are now ready for consumption in neutron-lib and will soon be deprecated in their neutron origination.

Hacking Checks

The 0.4.0 release of neutron-lib contains two new hacking checks.

As the names imply, check_no_eventlet_imports checks that the eventlet library is not imported and  check_delayed_string_interpolation ensures all logging calls use delay string interpolation. While check_no_eventlet_imports is intended for neutron-lib specific hacking checks (consumers need not comply), check_delayed_string_interpolation will likely become one of the checks registered in neutron-lib's hacking check factory longer-term.

Neither checks are automatically registered in neutron-lib's hacking check factory for 0.4.0. Before rolling out new hacking checks (via factory), we need to better solidify neutron-lib's hacking check consumption and roll-out process (for example patch 350723).

Policy

Neutron's policy API was re-homed to neutron-lib in 0.4.0 with patch 303867. This change adds the neutron_lib.policy module and it's public APIs. Consumers should start moving their code to neutron_lib's policy rather than using neutrons.

Utils

In 0.4.0 we starting re-homing the common neutron utils into the neutron_lib.utils package (see 319769). Utility APIs in neutron-lib are grouped by functionality and thus we have modules like; neutron_lib.utils.net, neutron_lib.utils.host, etc.. Consumers can now start using these utils by importing the respective modules they need, rather than calling these utility APIs from neutron.