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.
See the F5 Integration for OpenStack user documentation.
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.
Download f5-openstack-agent
and its dependencies (f5-icontrol-rest-python
and f5-common-python
).
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
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
Download f5-openstack-agent
and its dependencies (f5-icontrol-rest-python
and f5-common-python
).
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
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.
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 |
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
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
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:
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.
Each section below corresponds to a section of the F5 Agent Configuration File.
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 |
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 |
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 |
Parameter | Type | Description | Allowed Values | Recommended Value |
---|---|---|---|---|
f5_ha_type | string | Defines the BIG-IP device high availability (HA) mode. |
|
Default=standalone |
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:
|
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 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. |
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 Requires
|
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:
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 |
f5_common_external_networks | boolean | Controls the agent’s access to external (infrastructure-based) routes | TRUE: the agent adds all provider
networks with 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 |
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 |
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 |
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 |
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
The items shown in the table below are not supported in the current release.
Feature | Project |
---|---|
Distributed Virtual Router (DVR) | Neutron |
Role Based Access Control (RBAC) | Neutron |
Agent High Availability (HA) [3] | F5 OpenStack |
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.
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
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
Stop and remove the current version of the F5 agent.
$ 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
Follow the installation instructions to install a different version of the F5 agent.
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. |