Neutron/LBaaS/Deprecation

= OpenStack neutron-lbaas Deprecation FAQ =

Why are we deprecating neutron-lbaas?
There are many reasons we have been working towards deprecating neutron-lbaas, some are:


 * OpenStack load balancing no longer requires deep access into the neutron code base and database. All of the required networking capabilities are now available via stable APIs.
 * The neutron stadium has become large, leading to project management scaling issues. As part of the neutron stadium evolution neutron-lbaas was identified as a project that should spin out of neutron and become a top level OpenStack project.
 * The load balancing spin out of neutron was approved during the newton release cycle.
 * This change de-couples the load balancing release versioning from the rest of the OpenStack deployment. Since Octavia uses stable APIs when interacting with other OpenStack services, you can run a different version of Octavia in relation to your OpenStack cloud deployment. One operator is running Queens Octavia against a Liberty release based cloud (We highly recommend you do extensive testing when running with mis-matched releases).
 * We increase the performance of the load balancing API by removing layers of neutron API code supporting extensions.
 * The addition of new API features required patches in up to four different repositories when running under neutron. With the new Octavia project we have reduced this down to two repositories.
 * We were limited in some API capabilities by the neutron API extensions framework.
 * The neutron-lbaas API code has some fundamental defects in the object locking logic that led to inconsistent state with very high API call rates. Fixing these would essentially require a full re-write of the API code which Octavia already provides.
 * As an independent project, we can evolve faster. For example, Octavia supported the python 3.5 and policy-in-code community goals before neutron.
 * People are confused because it has "neutron" in the name.

What does neutron-lbaas deprecation mean?
neutron-lbaas and neutron-lbaas-dashboard will not longer accept new feature enhancements.

This is an indicator that deployments and driver developers will need to start planing for a migration to Octavia.

Both projects will continue to be supported and receive bug fixes for the duration of the deprecation cycle.

The code and projects will not be retired until the end of the deprecation cycle.

For more information on the OpenStack deprecation process see the follows-standard-deprecation document and the TC resolution Definition of Upstream Support.

When is neutron-lbaas being marked as deprecated?
neutron-lbaas and neutron-lbaas-dashboard are marked deprecated as of the Queens OpenStack release cycle. The neutron client was marked as deprecated during the Ocata OpenStack release cycle.

When will the neutron-lbaas deprecation cycle end?
At a minimum it will be two release cycles, meaning the first release that the projects could be retired in would be the "T" OpenStack release cycle.

We plan to retire neutron-lbaas and neutron-lbaas-dashboard in September 2019 or the "U" OpenStack release cycle, whichever comes first. This means the code will be be removed and will not be released as part of the "U" OpenStack release. The September 2019 date lands in the Train release cycle, meaning neutron-lbaas will not be released as part of the Train release. Neutron-lbaas will be retired during the Train release cycle.

What does retiring neutron-lbaas mean?
The infrastructure manual describes the process of retiring a project.

What are the replacement projects?

 * neutron-lbaas is replaced by Octavia
 * neutron-lbaas-dashboard is replaced by octavia-dashboard
 * neutron client (python-neutronclient) is replaced by python-octaviaclient for load balancer commands.
 * Python bindings for the Octavia v2 API are provided by the OpenStack SDK.

neutron-lbaas
Neutron-lbaas is a neutron extension that extends the neutron API to provide load balancing capabilities. It implements the LBaaS v2 API. Neutron-lbaas runs inside the neutron API process and must be installed with the neutron API.

LBaaS v2 API
LBaaS v2 API is the second version of the Load Balancing as a Service (LBaaS) API. LBaaS v1 is End of Life (EoL) as of the Mitaka OpenStack release cycle and has been retired.

Both neutron-lbaas and octavia implement the LBaaS v2 API, however octavia is a superset of the LBaaS v2 API meaning it includes additional features.

Octavia
Octavia is an official OpenStack service project providing load balancing capabilities for OpenStack. It includes a standalone API endpoint advertised in Keystone as service-type "load-balancer". Octavia includes a reference load balancing driver, octavia, that provides load balancing by using "amphora" which are currently implemented as service VMs. Octavia implements the LBaaS v2 API, like neutron-lbaas, but also provides additional features. See the Octavia v2 API reference.

Octavia v2 API
The Octavia v2 API is a fully backward compatible superset of the LBaaS v2 API. It includes all of the capabilities of the LBaaS v2 API with additional features such as: listener statistics, batch member updates, load balancer failover, status fields for all objects, cascade delete, and many more.

See the Octavia v2 API reference for more information on the Octavia v2 API.

How do I migrate to Octavia?
If your neutron-lbaas load balancers are using the Octavia driver all you need to do is upgrade Octavia to the Pike release of OpenStack or newer and enable the v2 API. Your load balancer details are already in the Octavia database and using the Octavia driver infrastructure. This means that your applications can simply update the endpoint being used for load balancing from the neutron API endpoint to the Octavia API endpoint. The one caveat to this is that if neutron-lbaas created the VIP neutron port(s), Octavia will not delete it when the load balancer is deleted via the Octavia API. There will be a port migration tool provided to transfer ownership of the neutron port(s) from neutron-lbaas to Octavia.

A migration guide will be developed and made available in the administration documentation.

The lbaasv2-proxy neutron service plugin is available to allow users to continue to access load balancing via the neutron API during your migration. Please see the section titled "What migration tools are available?" for more information.

What migration tools are available?
The lbaasv2-proxy neutron service plugin is available to allow users to continue to access load balancing via the neutron API during your migration. This proxy will forward all load balancing requests received via the neutron API to the Octavia API. This should be used as a temporary migration tool as it is included in the neutron-lbaas code base and deprecation. You can enable it by editing your neutron.conf file, [DEFAULT] section and change the "service_plugins" setting from "lbaasv2" to "lbaasv2-proxy".

The database schema for Octavia is very similar to the neutron-lbaas schema in the neutron database. A database migration tool will be made available to move existing load balancers from the neutron-lbaas database into the Octavia database.

This tool is now available here: https://git.openstack.org/cgit/openstack/neutron-lbaas/tree/tools/nlbaas2octavia This tool supports live migration of running load balancers if the provider driver supports it, such as the Octavia amphora driver.

How do I install Octavia?
You may already have Octavia installed as part of your neutron-lbaas installation. Octavia has been the reference driver since the OpenStack Liiberty release. If this is the case you only need to upgrade to the Pike release of OpenStack or newer and enable the v2 API.

There are a number of ways to install Octavia:
 * By hand using the installation documentation.
 * Using OpenStack Ansible
 * Using OpenStack Tripleo
 * Using Puppet
 * Using vendor distributions that include Octavia.

Does Octavia support RBAC?
Yes, Octavia has Role Based Access Control (RBAC) on the Octavia v2 API. Please see the Octavia Policies page in the Octavia documentation.

Does Octavia support quotas?
Yes, Octavia has quota support in the Octavia v2 API. Please see the Quota section in the Octavia v2 API documentation.

If you are using the neutron-lbaas proxy plugin to pass load balancing requests from the neutron API to the Octavia API, both the neutron quota settings and those configured in Octavia will be enforced. You may want to consider setting the neutron load balancing quotas to unlimited when you enable the neutron-lbaas proxy plugin.

Does Octavia have a Horizon dashboard (Web GUI)?
Yes, the Octavia dashboard provides a greatly enhanced load balancing horizon dashboard.

What is the Command Line Interface (CLI) for Octavia?
The python-octaviaclient project provides an OpenStack Client (OSC) plugin.

The OpenStack Client is a unified CLI client for all OpenStack projects. It replaces the, deprecated since Ocata, neutron CLI client.

A command mapping table is available as part of the python-octaviaclient documentation.

Detailed command documentation is available as part of the python-octaviaclient documentation.

Updated user Cookbooks are also available as part of the Octavia user documentation set.

What about neutron-lbaas provider drivers?
In cooperation with our driver authors, a provider driver specification has merged for the Octavia API. This specification brings significant enhancements to the driver capabilities available to operators through the flavors mechanism.

This change will require some modification to the drivers to support the new provider driver specification. This may require more effort if the prior driver was using non-stable internal neutron interfaces.

Over the course of the neutron-lbaas deprecation cycle we expect provider drivers to become available for the Octavia API. These drivers will be listed in the Octavia Administration documentation.

Using the database migration tool descibed above, you should be able to migrate existing load balancers that are using a provider driver without incurring data plane downtime to the load balancer. However, this capability may vary depending on the driver implementation.

Aside from the Octavia reference driver used for testing, provider drivers will no longer exist inside the Octavia project repository. We typically do not have access to the required hardware or software to properly test and maintain these drivers as part of the main Octavia repository. Moving these drivers into their own repository will allow independent development cycles for the drivers. Provider drivers will use Stevedore and packaging to allow easy installation of the driver into the Octavia API.

For more information about provider drivers see the provider driver specification.

Can I run Octavia at the same time as neutron-lbaas?
Yes you can. However note that only load balancers using the Octavia reference driver will be visible in both systems and actions against the Octavia API may not be fully reflected in neutron-lbaas.

The lbaasv2-proxy plugin can also be used to allow load balancers in Octavia to be visible via the neutron API.

The OpenStack Client plugin for load balancing only supports the Octavia v2 API. To interact with neutron-lbaas from the command line you must continue to use the "neutron" client.

What about the Octavia v1 API?
The Octavia v1 API was intended for use by the neutron-lbaas Octavia driver. It should not be exposed to end users as it does not implement access controls. For Octavia API processes hosting the Octavia v2 API for users, the v1 API should be disabled via the octavia.conf file setting "[api_settings] api_v1_enabled = False". You will also see log messages warning you if you have both API versions enabled on the same API process. If you require both APIs available in your cloud, we recommend running a separate v1 API process that is access controlled for your neutron-lbaas octavia drivers to use. This can be accomplished by either running it on an alternate, security group controlled, port or on alternate controller hosts/containers.

The Octavia v1 API will follow the neutron-lbaas deprecation cycle and be removed when neutron-lbaas is removed.

The Octavia v1 API is a proprietary API and is not compatible with the LBaaS v2 API specification or any other LBaaS API specification.

Where do I get more information?

 * The Octavia documentation.
 * The best way to reach the LBaaS team is via IRC on the Freenode IRC network channel #openstack-lbaas
 * Weekly Meeting: 16:00 UTC on Wednesdays in #openstack-lbaas on the Freenode IRC network.
 * Sending email to the OpenStack mailing list: openstack-discuss [at] lists [dot] openstack [dot] org. Please prefix the subject with '[Octavia]'