README.rst

F5 Agent for OpenStack Neutron

OpenStack version:

|openstack|

.. toctree::
   :hidden:
   :caption: Contents
   :maxdepth: 1
   :glob:

   global-routed-mode
   l2-adjacent-mode
   device-driver-settings
   ha-mode

version |release|

|release-notes|

The |agent-long| (f5-openstack-agent) is an OpenStack Neutron plugin agent. It works in conjunction with the F5 Driver for OpenStack LBaaS to manage F5 BIG-IP Local Traffic Manager (LTM) services via the OpenStack Neutron API.

.. seealso::

   For more information about how the |agent-short| interacts with the Neutron API and BIG-IP devices, see :ref:`Architecture`.

.. index::
   triple: f5-openstack-agent; downloads; debian
   triple: f5-openstack-agent; downloads; rpm

Downloads

|deb-download| |rpm-download|

Guides

See the `F5 Integration for OpenStack`_ user documentation.

.. index::
   single: f5-openstack-agent; install

Installation

Follow the instructions for your distribution below to install the |agent-long| on your Neutron controller.

Tip

You can use the f5-openstack-ansible project to deploy the |agent-short|, |driver-long|, and all project dependencies. See Deploy OpenStack Agent and Driver with Ansible for more information.

.. index::
   triple: f5-openstack-agent; install; debian

Debian

1. Download |agent| and its dependencies (f5-icontrol-rest-python and f5-common-python).

2. Install all three (3) packages.

   curl -L -O |f5_agent_deb_url|
   curl -L -O |f5_sdk_deb_url|
   curl -L -O |f5_icontrol_deb_url|
   dpkg –i |f5_icontrol_deb_package|
   dpkg –i |f5_sdk_deb_package|
   dpkg –i |f5_agent_deb_package|
   

.. index::
   triple: f5-openstack-agent; install; pip

Pip

Install the |agent| release package from GitHub.

pip install |f5_agent_pip_url|

Tip

Use @<branch-name> to install from HEAD on a specific branch.

For example:

pip install |f5_agent_pip_url_branch|

.. index::
   triple: f5-openstack-agent; install; rpm

RPM

1. Download |agent| and its dependencies (f5-icontrol-rest-python and f5-common-python).

2. Install all three (3) packages.

   curl -L -O |f5_sdk_rpm_url|
   curl -L -O |f5_icontrol_rpm_url|
   curl -L -O |f5_agent_rpm_url|
   rpm -ivh |f5_icontrol_rpm_package| |f5_sdk_rpm_package| |f5_agent_rpm_package|
   

Next Steps

• Install the F5 driver for OpenStack LBaaSv2.
• :ref:`Configure the F5 Agent for OpenStack Neutron <configure-the-f5-openstack-agent>`.

.. index::
   single: f5-openstack-agent; architecture

Architecture

The |driver-long| assigns LBaaS tasks from the Neutron RPC Messaging queue to the |agent-long|. The |agent-short| translates the Neutron LBaaS API calls to iControl REST API calls and configures the requested objects on the BIG-IP device(s) identified in the :ref:`F5 Agent Configuration File <agent-config-file>`.

When the |agent-short| and |driver-short| run on your OpenStack Neutron Controller, you can use the standard neutron lbaas commands to manage BIG-IP LTM objects. [2] The table below shows the corresponding iControl endpoint and BIG-IP object for each neutron lbaas-* create command.

OpenStack Neutron to F5 iControl REST/BIG-IP command mapping

Command	URI	Configurations Applied
neutron lbaas-loadbalancer-create	https://<icontrol_endpoint>:443/mgmt/tm/sys/folder/~Project_<os_tenant_id>	Creates new BIG-IP partition; name uses the OpenStack uuid and tenant ID
neutron lbaas-listener-create	https://<icontrol_endpoint>:443/mgmt/tm/ltm/virtual/	Creates new BIG-IP virtual server in the tenant's partition
neutron lbaas-pool-create	https://<icontrol_endpoint>:443/mgmt/tm/ltm/pool/	Creates new pool on the virtual server
neutron lbaas-member-create	https://<icontrol_endpoint>:443/mgmt/tm/ltm/pool/~Project_<os_tenant_id>~pool1/members/	Creates new pool member on the virtual server
neutron lbaas-healthmonitor-create	https://<icontrol_endpoint>:443/mgmt/tm/ltm/monitor/http/	Creates new health monitor for the pool

.. index::
   single: f5-openstack-agent; supported features

Modes of Operation

• :ref:`Global Routed Mode <global-routed-mode>`
• :ref:`L2/L3-Adjacent Mode <l2-adjacent-mode>`

.. index::
   single: f5-openstack-agent; configure

Configure the |agent-long|

1. Use your text editor of choice to edit the :ref:`F5 Agent Configuration File` as appropriate for your environment.

   vim /etc/neutron/services/f5/f5-openstack-agent.ini

1. Start the |agent-short|.

   Once you have configured the |agent-short|, you can use the appropriate command(s) for your OS to start or stop the agent service.

   CentOS

   systemctl enable f5-openstack-agent
   systemctl start f5-openstack-agent
   systemctl stop f5-openstack-agent.service

   Ubuntu

   service f5-oslbaasv2-agent start
   service f5-oslbaasv2-agent stop

F5 Agent Configuration File

The :ref:`F5 Agent Configuration File <agent-config-file-example>` (:file:`/etc/neutron/services/f5/f5-openstack-agent.ini`) tells the |agent-long| about the network architecture and how/where the BIG-IP device(s) fit in. The configuration parameters tell the agent:

1. where to find the BIG-IP device(s) you expect it to manage, and
2. what settings are already applied on the BIG-IP device(s).

The latter impacts how the |agent-short| configures BIG-IP objects in response to Neutron API calls.

Important

Use the appropriate |agent-long| configuration parameters for your network architecture and existing BIG-IP configurations.

The |agent-long| has two (2) modes of operation: :ref:`Global routed mode <global-routed-mode>` and :ref:`L2/L3-adjacent mode <l2-adjacent-mode>`. The mode you should use depends on where your BIG-IP device(s) reside in the network architecture.

• Global routed mode -- use with BIG-IP hardware devices that connect directly to the OpenStack provider network.
• L2/L3-adjacent mode -- if your BIG-IP devices or Virtual Edition (VE) instances connect to the provider network via VLANs and/or VXLAN/GRE tunnels.

Each section below corresponds to a section of the :ref:`F5 Agent Configuration File`.

.. index::
   single: f5-openstack-agent; default settings

DEFAULT SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
debug	boolean	Sets the log level to DEBUG.	True, False	True
periodic_interval	integer	Sets the number of seconds between the agent's attempts to sync its state with Neutron	Any number of seconds, expressed as an integer	Default=10
service_resync_interval	integer	Sets the frequency at which the agent discards its service cache and syncs with the Neutron LBaaS service.	Any number of seconds, expressed as an integer	Default=500

.. index::
   single: f5-openstack-agent; environment settings

ENVIRONMENT SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
environment_prefix	string	Sets the default prefix applied to all BIG-IP LTM objects in the tenant partition.	Any string beginning with an alpha character.	Default=Project

.. index::
   single: f5-openstack-agent; static agent configuration settings

STATIC AGENT CONFIGURATION SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
static_agent_configuration_data	key-value pair	Defines static agent identification data sent to the Neutron LBaaS plugin; used to identify agent for custom pool-to-agent scheduling.	single key-value pair --OR-- comma-separated list of key-value pairs	N/A

.. index::
   single: f5-openstack-agent; device settings

DEVICE SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
f5_ha_type	string	Defines the BIG-IP device high availability (HA) mode.	standalone: single BIG-IP device pair: active/standby pair (2 BIG-IP devices) scalen: active/active device cluster (3 or more BIG-IP devices)	Default=standalone

.. index::
   single: f5-openstack-agent; L2 segmentation mode settings

L2 SEGMENTATION MODE SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
f5_external_physical_mappings	string	Binds VLANs to BIG-IP interfaces ; tells the agent about the interface's VLAN tagging settings	string in the format "physical_network:interface_name:tagged" The agent will use the "default" mapping if you don't define mappings for specific VLANs. Example: "ext_net:1.1:True" -- maps the external physical network named "ext_net" to BIG-IP interface 1.1; tells the agent that 1.1 is a tagged interface. Tagged interfaces accept traffic from multiple VLANs. Untagged interfaces accept traffic from a single VLAN.	Default= default:1.1:True
vlan_binding_driver	string	Software hook allowing VLAN-interface-port mapping	The vlan_binding_driver allows you to bind and prune VLAN ids to specific ports. A vlan_binding_driver class must: reference a subclass of :py:class:`VLANBindingBase` contain methods that bind and prune VLAN tags to specific ports	N/A
interface_port_static_mappings	JSON dictionary	Enabled by vlan_binding_driver; maps BIG-IP devices and interfaces to specific ports	JSON dictionaries mapping BIG-IP devices and interfaces to ports. Follows the format "{"device_name":{"interface_id":"port_id"}"	N/A
f5_vtep_folder	string	The BIG-IP partition containing the desired `VTEP`_ .	N/A	/Common
f5_vtep_selfip_name	string	The name of the BIG-IP self IP to use as the VTEP.	N/A	vtep
advertised_tunnel_types	string	The type of tunnel to use. The agent advertises its ability to terminate this tunnel type via the oslo tunnel_sync message queues. The agent registers BIG-IP devices as tunnel peers based on this setting. This setting must be the same on all OpenStack nodes (controller, compute, and network).	vxlan, gre	vxlan
f5_populate_static_arp	boolean	Controls BIG-IP Address Resolution Protocol (ARP) settings.	TRUE: the agent adds static entries for the IP and MAC addresses in the Neutron LBaaS service definition to the BIG-IP system ARP cache. FALSE: the agent discovers BIG-IP pool members via flooding.	TRUE
l2_population	boolean	Sets agent registration policy for Neutron Modular Layer 2 (ml2) messages	TRUE: the agent registers for ml2 population messages; these allow the agent to update the VTEP forwarding table when pool members migrate from one compute node to another. FALSE: the agent does not receive ml2 population messages and does not update VTEP table entries for migrated pool members.	TRUE
f5_network_segment_physical_network	string	The network segment the agent should watch.	String; must be the name of the network segment you want the agent to watch for dynamically-created VLANs. Used in conjunction with software-defined networking (SDN). Comment out this setting if you are not using hierarchical port binding. [1]	N/A
f5_network_segment_polling_interval	integer	The frequency at which the agent should poll for disconnected LBaaS listeners. [1]	integer; in seconds Comment out this setting if you are not using hierarchical port binding.	10
f5_pending_services_timeout	integer	Maximum amount of time before creation of a pending service errors out. [1]	integer; in seconds Comment out this setting if you are not using hierarchical port binding.	60

Footnotes

[1]	(1, 2, 3) See `Hierarchical Port Binding`_.

.. index::
   single: f5-openstack-agent; L3 segmentation mode settings

L3 SEGMENTATION MODE SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
f5_global_routed_mode	boolean	Defines how the BIG-IP devices connect to the network	TRUE: BIG-IP device(s) connect directly to the OpenStack provider network. (L2 routing only) FALSE: BIG-IP devices use VXLAN or GRE tunnels to bridge physical/ virtualized network segments. (L2 & L3 routing; "L2-adjacent mode")	FALSE
use_namespaces	boolean	Tells the agent if you're using BIG-IP route domains	TRUE: you're using BIG-IP route domains to segment tenant network traffic. FALSE: you're not using route domains; tenant networks cannot use overlapping subnets.	TRUE Forced to FALSE if f5_global_routed_mode = TRUE
max_namespaces_per_tenant	integer	Sets the maximum number of namespaces/route tables the agent can allocate per tenant	Any integer, with the caveat that using more than 1 namespace per tenant is NOT a recommended practice.	1
f5_route_domain_strictness	boolean	Controls the agent's access to BIG-IP global routing table (route domain 0) Requires use_namespaces=TRUE	TRUE: the agent can only access BIG-IP tenant route domains; it cannot consult the global routing table. VIPs and members can only communicate if they are in the same tenant. FALSE: the agent can look for a destination route in the global routing table if it can't find a match in the tenant route domains. VIPs and members can communicate across tenants. Set to FALSE to ensure the agent has access to external routes on the OpenStack provider network.	FALSE
f5_snat_mode	boolean	Tells the agent if it should allocate BIG-IP SNAT pools for tenants	TRUE: the agent manages a SNAT pool for the tenant. When set to TRUE, incoming proxy traffic uses IP addresses from the SNAT pool. Set to TRUE when: you want to ensure that server responses always return through the BIG-IP system you want to hide the source addresses of server-initiated requests from external devices. FALSE: the agent doesn't allocate a SNAT pool for the tenant; source IP addresses for outgoing traffic are not masked; incoming traffic follows the destination server's default route. When set to FALSE, the BIG-IP device sets up a floating IP as the subnet's default gateway address and creates a wildcard IP- forwarding virtual server on the member's network. Neutron floating IPs will not work if the BIG-IP device isn't used as the Neutron Router.	TRUE Forced to TRUE if f5_global_routed_mode = TRUE
f5_snat_addresses_per_subnet	integer	Defines how many IP addresses to allocate in a SNAT pool	Any integer. Set to 0 to use automap SNAT (the BIG-IP device automatically creates a SNAT pool for you).	0
f5_common_external_networks	boolean	Controls the agent's access to external (infrastructure-based) routes	TRUE: the agent adds all provider networks with route:external set to true to the BIG-IP global route domain (0). Set to TRUE if you want the agent to route traffic to IP addresses associated with an external route (for example, an infrastructure router). FALSE: the agent cannot route traffic to provider networks with route:external set to true.	TRUE
common_networks	key-value pair	Tells the agent about shared networks already configured on the BIG-IP device	single key-value pair --OR-- comma-separated list of key-value pairs Follows the format "neutron_network_uuid:BIG-IP_network_name"	N/A
l3_binding_driver	string	Software hook allowing L3_address-port binding	Allows you to bind L3 addresses to specific ports.	f5_openstack_agent. lbaasv2.drivers.bigip. l3_binding. AllowedAddressPairs
l3_binding_static_mappings	JSON dictionary	Using the l3_binding_driver, maps Neutron subnet ids to L2 ports and devices	JSON-encoded dictionary; follows the format 'subnet_id':[('port_id','BIG-IP_device')	N/A

.. index::
   single: f5-openstack-agent; device driver/iControl driver settings

DEVICE DRIVER/iCONTROL DRIVER SETTINGS

Parameter	Type	Description	Allowed Values	Recommended Value
f5_bigip_lbaas_device_driver	string	The iControl device driver	DO NOT CHANGE THIS SETTING FROM THE DEFAULT VALUE.
icontrol_hostname	string	The IP address, or DNS-resolvable hostname, of your BIG-IP device(s) and/or vCMP guest(s)	single or comma-separated list	N/A
icontrol_vcmp_hostname	string	The IP address of your vCMP host	single IP address	N/A
icontrol_username	string	The username of an account on the BIG-IP device	The username of an account with permission to create partitions and create/manage Local Traffic and Network objects	N/A
icontrol_password	string	Password for the BIG-IP user account	See BIG-IP password requirements.	N/A

.. index::
   single: f5-openstack-agent; certificate manager settings

CERTIFICATE MANAGER SETTINGS

Important

The settings in this section only apply if you are using the OpenStack Barbican service. If you aren't using Barbican, leave this section commented out.

Parameter	Type	Description	Allowed Values	Recommended Value
cert_manager	string	the agent BarbicanCertManager driver	f5_openstack_agent.lbaasv2.drivers.bigip. barbican_cert.BarbicanCertManager	Default=None
auth_version	string	OpenStack Keystone auth version	v2, v3	N/A
os_auth_url	string	Keystone auth URL		N/A
os_username	string	OpenStack username		N/A
os_password	string	OpenStack password		N/A
os_user_domain_name	string	OpenStack user account domain		N/A
os_project_name	string	OpenStack project (tenant) name		N/A
os_project_domain_name	string	OpenStack project domain		N/A

.. index::
   single: f5-openstack-agent; configuration file examples

Configuration File Examples

The example configuration files provided here can help guide you in setting up the |agent-long| to work with your specific environment.

Global routed mode

• :download:`Download global routed mode example </_static/config_examples/f5-openstack-agent.grm.ini>`

L2-adjacent mode

• :download:`Download GRE example </_static/config_examples/f5-openstack-agent.gre.ini>`
• :download:`Download VLAN example </_static/config_examples/f5-openstack-agent.vlan.ini>`
• :download:`Download VXLAN example </_static/config_examples/f5-openstack-agent.vxlan.ini>`

.. index::
   single: f5-openstack-agent; unsupported features

Unsupported Features

The items shown in the table below are not supported in the current release.

Unsupported Features in |release|

Feature	Project
Distributed Virtual Router (DVR)	Neutron
Role Based Access Control (RBAC)	Neutron
Agent High Availability (HA) [3]	F5 OpenStack

.. index::
   single: f5-openstack-agent; upgrade

Upgrade

To upgrade to/install a different version of |agent|, you'll need to uninstall your current version first. Perform the steps below on every server running |agent-short|.

!DANGER!

If you use pip install --upgrade to upgrade the F5 LBaaSv2 agent, packages that other OpenStack components use might be negatively impacted. F5 does not recommend using pip install --upgrade to upgrade the |agent| package.

1. Copy the |agent-short| configuration file to a different directory (for example, :file:`~/f5-upgrade-temp`).

   Warning

   Your configuration file (:file:`/etc/neutron/services/f5/f5-openstack-agent.ini` gets overwritten when you install a new package. If you don't save a copy elsewhere, you will lose your config settings.

   $ cp /etc/neutron/services/f5/f5-openstack-agent.ini ~/f5-upgrade-temp

2. Move or rename the |agent-short| log file.

   Your new |agent-short| will not start if it finds an existing |agent| .log file. You can either move the log file to a new location, or rename it.

   $ mv /var/log/neutron/f5-openstack-agent.log ~/f5-upgrade-temp

3. Stop and remove the current version of the |agent-short|.

   $ sudo service f5-oslbaasv2-agent stop
   $ pip uninstall f5-openstack-agent

   $ sudo systemctl stop f5-openstack-agent
   $ sudo systemctl disable f5-openstack-agent
   $ sudo pip uninstall f5-openstack-agent

4. Follow the :ref:`installation <agent-installation>` instructions to install a different version of the |agent-short|.

5. Copy your configuration file back into :file:`/etc/neutron/services/f5`.

   Tip

   It's good practice to compare your saved copy of the configuration file with the new one created during installation. Verify that the only differences between the two are those required for your deployment. If new options appear in the config file, see :ref:`supported features <agent-supported-features>` and :ref:`configuration parameters <agent-config-parameters>` for explanations and config instructions.

   $ cp ~/f5-upgrade-temp/f5-openstack-agent.ini /etc/neutron/services/f5/f5-openstack-agent.ini

Footnotes

[2]	See the Neutron LBaaS documentation

[3]	Similar to BIG-IP :term:`high availability`, but applies to the |agent-short| processes.