Cloud Docs Home > F5 Agent for OpenStack Neutron Index

F5 Agent for OpenStack Neutron

Travis-CI Build Status

version 8.3.6

Release Notes

The F5 Agent for OpenStack Neutron (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.

See also

For more information about how the F5 agent interacts with the Neutron API and BIG-IP devices, see Architecture.

Guides

See the F5 Integration for OpenStack user documentation.

Installation

Follow the instructions for your distribution below to install the F5 Agent for OpenStack Neutron on your Neutron controller.

Tip

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

Debian

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

  2. Install all three (3) packages.

    curl -L -O https://github.com/F5Networks/f5-openstack-agent/releases/download/v8.3.6/python-f5-openstack-agent_8.3.6-1_1404_all.deb
    curl -L -O https://github.com/F5Networks/f5-common-python/releases/download/v2.3.3/python-f5-sdk_2.3.3-1_1404_all.deb
    curl -L -O https://github.com/F5Networks/f5-icontrol-rest-python/releases/download/v1.3.0/python-f5-icontrol-rest_1.3.0-1_1404_all.deb
    dpkg –i python-f5-icontrol-rest_1.3.0-1_1404_all.deb
    dpkg –i python-f5-sdk_2.3.3-1_1404_all.deb
    dpkg –i python-f5-openstack-agent_8.3.6-1_1404_all.deb
    

Pip

Install the f5-openstack-agent release package from GitHub.

pip install git+https://github.com/F5Networks/f5-openstack-agent@v8.3.6

Tip

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

For example:

pip install git+https://github.com/F5Networks/f5-openstack-agent@liberty

RPM

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

  2. Install all three (3) packages.

    curl -L -O https://github.com/F5Networks/f5-common-python/releases/download/v2.3.3/f5-sdk-2.3.3-1.el7.noarch.rpm
    curl -L -O https://github.com/F5Networks/f5-icontrol-rest-python/releases/download/v1.3.0/f5-icontrol-rest-1.3.0-1.el7.noarch.rpm
    curl -L -O https://github.com/F5Networks/f5-openstack-agent/releases/download/v8.3.6/f5-openstack-agent-8.3.6-1.el7.noarch.rpm
    rpm -ivh f5-icontrol-rest-1.3.0-1.el7.noarch.rpm f5-sdk-2.3.3-1.el7.noarch.rpm f5-openstack-agent-8.3.6-1.el7.noarch.rpm
    

Architecture

The F5 Driver for OpenStack LBaaS assigns LBaaS tasks from the Neutron RPC Messaging queue to the F5 Agent for OpenStack Neutron. The F5 agent 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 F5 Agent Configuration File.

When the F5 agent and F5 driver 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

Configure the F5 Agent for OpenStack Neutron

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

    vim /etc/neutron/services/f5/f5-openstack-agent.ini
    
  1. Start the F5 agent.

    Once you have configured the F5 agent, 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 F5 Agent Configuration File (/etc/neutron/services/f5/f5-openstack-agent.ini) tells the F5 Agent for OpenStack Neutron 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 F5 agent configures BIG-IP objects in response to Neutron API calls.

Important

Use the appropriate F5 Agent for OpenStack Neutron configuration parameters for your network architecture and existing BIG-IP configurations.

The F5 Agent for OpenStack Neutron has two (2) modes of operation: Global routed mode and L2/L3-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 F5 Agent Configuration File.

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

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

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

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

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 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.

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

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

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

Configuration File Examples

The example configuration files provided here can help guide you in setting up the F5 Agent for OpenStack Neutron to work with your specific environment.

Global routed mode

L2-adjacent mode

Unsupported Features

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

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

Upgrade

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

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 f5-openstack-agent package.

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

    Warning

    Your configuration 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 F5 agent log file.

    Your new F5 agent will not start if it finds an existing f5-openstack-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 F5 agent.

    Debian/Ubuntu
    $ sudo service f5-oslbaasv2-agent stop
    $ pip uninstall f5-openstack-agent
    
    Red Hat/CentOS
    $ sudo systemctl stop f5-openstack-agent
    $ sudo systemctl disable f5-openstack-agent
    $ sudo pip uninstall f5-openstack-agent
    
  4. Follow the installation instructions to install a different version of the F5 agent.

  5. Copy your configuration file back into /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 supported features and configuration 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 high availability, but applies to the F5 agent processes.