diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 174a0962e..788bee9f4 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -22,10 +22,10 @@ #### Description - + #### Deployment - - - + + + diff --git a/.travis.yml b/.travis.yml index 06a3ca891..4849f7a6d 100755 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,4 @@ -sudo: true +sudo: required env: global: - DIST_REPO="f5-openstack-agent-dist" @@ -15,7 +15,7 @@ python: before_install: - git config --global user.email "OpenStack_TravisCI@f5.com" - git config --global user.name "Travis F5 Openstack" - + - docker pull f5devcentral/containthedocs:latest install: - pip install tox script: @@ -25,6 +25,7 @@ script: - f5-openstack-agent-dist/scripts/package_agent.sh "ubuntu" "14.04" - sudo chown -R travis:travis ${DIST_REPO}/rpms/build - sudo chown -R travis:travis ${DIST_REPO}/deb_dist/*.deb + - ./docs/scripts/docker-docs.sh ./docs/scripts/test-docs.sh after_success: - md5sum ${PKG_RELEASE_EL7} > ${PKG_RELEASE_EL7}.md5 && md5sum --check ${PKG_RELEASE_EL7}.md5 - md5sum ${PKG_RELEASE_1404} > ${PKG_RELEASE_1404}.md5 && md5sum --check ${PKG_RELEASE_1404}.md5 @@ -54,6 +55,26 @@ deploy: tags: true python: 2.7 skip_cleanup: true + # deploy docs to s3 + # if this is not a tagged release, the docs go to /products/openstack/agent/$TRAVIS_BRANCH + - provider: script + skip_cleanup: true + on: + repo: F5Networks/f5-openstack-agent + branch: mitaka + condition: $TRAVIS_TAG = "" + script: + - ./docs/scripts/deploy-docs.sh publish-product-docs-to-prod openstack/agent $TRAVIS_BRANCH + # if this is a tagged release, the docs go to /products/openstack/agent/$TRAVIS_BRANCH/vX.Y + - provider: script + skip_cleanup: true + env: + - RELEASE_TAG="$(echo $TRAVIS_TAG |cut -c1-4)" + on: + tags: true + repo: F5Networks/f5-openstack-agent + script: + - ./docs/scripts/deploy-docs.sh publish-product-docs-to-prod openstack/agent/$TRAVIS_BRANCH $RELEASE_TAG notifications: slack: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 48a25d422..3146bd66d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,7 +58,7 @@ $ py.test --cov ./ --cov-report=html $ open htmlcov/index.html ``` -If you are running our functional tests you will need a real BIG-IP® to run +If you are running our functional tests you will need a real BIG-IP to run them against; you can get one of those pretty easily in [Amazon EC2](https://aws.amazon.com/marketplace/pp/B00JL3UASY/ref=srh_res_product_title?ie=UTF8&sr=0-10&qid=1449332167461). ## License @@ -77,4 +77,4 @@ See the License for the specific language governing permissions and limitations under the License. ### Contributor License Agreement -Individuals or business entities who contribute to this project must have completed and submitted the [F5® Contributor License Agreement](http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing) to Openstack_CLA@f5.com prior to their code submission being included in this project. +Individuals or business entities who contribute to this project must have completed and submitted the [F5 Contributor License Agreement](http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing) to Openstack_CLA@f5.com prior to their code submission being included in this project. diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..96867f1a3 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Makefile for building and testing documentation in a docker container +# + +.PHONY: help +help: + @echo " docker-preview to build live preview of docs using sphinx-autobuild in a docker container" + @echo " docker-test to build and test docs in a docker container" + +# Build live preview docs in a docker container +.PHONY: docker-preview +docker-preview: + make -C docs clean + DOCKER_RUN_ARGS="-p 0.0.0.0:8000:8000" ./docs/scripts/docker-docs.sh \ + make -C docs preview + +# run quality tests in a docker container +.PHONY: docker-test +docker-test: + make -C docs clean + ./docs/scripts/docker-docs.sh ./docs/scripts/test-docs.sh \ No newline at end of file diff --git a/README.rst b/README.rst index 5e21abfd0..7b6f4cfde 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ .. raw:: html -f5-openstack-agent -################## +F5 Agent for OpenStack Neutron +============================== |Build Status| |slack badge| |coveralls badge| + +version |release| +----------------- + + Introduction -************ +------------ -The F5® agent translates from 'OpenStack' to 'F5®'. It uses the `f5-sdk `_ to translate OpenStack messaging calls -- such as those from the Neutron RPC messaging queue -- into iControl® REST calls to F5® technologies, such as BIG-IP®. +The F5 Agent for OpenStack Neutron is an OpenStack `Neutron plugin agent `_. It works in conjunction with the `F5 driver for OpenStack LBaaSv2 `_ to manage F5 BIG-IP `Local Traffic Manager `_ (LTM) services via the OpenStack Neutron API. Documentation -************* +------------- -Documentation is published on Read the Docs, at http://f5-openstack-agent.readthedocs.io. +Documentation is published on `clouddocs.f5.com `_. Compatibility -************* +------------- -The F5® OpenStack agent is compatible with OpenStack releases from Liberty forward. If you are using Kilo or earlier, you'll need the `LBaaSv1 plugin `_. +The F5 Agent for OpenStack Neutron is compatible with OpenStack releases from Liberty forward. -See the `F5® OpenStack Releases and Support Matrix `_ for more information. +See the `F5 OpenStack Releases and Support Matrix `_ for more information. -Installation -************ +Installing the F5 Agent +----------------------- -Please see the `documentation `_ for installation instructions. +Please see `installing the F5 agent `_. -For Developers -************** -Filing Issues -============= +Using the Built-in Debugger +--------------------------- -If you find an issue, we would love to hear about it. Please open a new `issue `_ aissue for each bug you'd like to report or feature you'd like to request. Please be specific, and include as much information about your environment and the issue as possible. +Use the built-in debugger -- ``debug_bundler.py`` -- to package information about your environment for debugging purposes. -Contributing -************ -See `Contributing `_. +When the you install ``f5-openstack-agent``, the ``debug_bundler.py`` script installs itself in ``/usr/bin/f5/``. +When you run the debugger, it searches for log and config files and dumps a complete listing of the ``pip lists`` output. +The debugger bundles everything it finds into a tarfile that you can provide to F5's support representatives to assist them in identifying the cause of your issue. -Test -**** -Before you open a pull request, your code must have passing -`pytest `__ unit tests. In addition, you should -include a set of functional tests written to use a real BIG-IP® device -for testing. Information on how to run our set of tests is included -below. +------------- -Style Checks -============ +**WARNING** -We use the hacking module for our style checks. +The files added to the debug bundle may contain **VERY SENSITIVE INFORMATION** such as **encryption keys**, **passwords**, and **usernames**. +Do not upload this bundle, or any information within, to a public forum unless you have thoroughly scrubbed sensitive information. +When in doubt, don't upload it at all. -:: - $ pip install tox - $ tox -e style +------------- -Unit Tests -========== -We use tox to run our pytest unit tests. To run the unit tests use the tox -environment `unit`. +Basic usage with the default command-line arguments +``````````````````````````````````````````````````` + +The command below creates a .tar file in the specified directory (in this example, `/home/myuser/debug_bundle_output/`) containing all logs and configuration files the script found. +The script offers a best-effort search of the specified directories. +If it cannot find the log files it is looking for in those directories, it prints an error message and continues to run. + :: - $ pip install tox - $ tox -e unit -Functional Tests -================= + $ python /usr/bin/f5/debug_bundler.py /home/myuser/debug_bundle_output/ -Functional tests can be run without a full OpenStack deployment, but do require -access to a BIG-IP device or VE instance. -1. Create a symbol's file that describes the environment that you are running - your test in by copying and editing the `symbols.json.example `_ - file to have the values that are correct for your BIG-IP. -2. Run the functional tests by supplying the symbol file that you just created - which includes the information relative to your environment using the - example file. The example below runs the disconnected services neutronless - functional test cases (the tox target changes to the [test/functional](test/functional) - directory before running. +Override log/config file locations +`````````````````````````````````` -:: +The default log location is `/var/log/neutron`. +The default configuration file location is `/etc/neutron`. - $ tox -e functest -- \ - --symbols ~/path/to/symbols/symbols.json \ - neutronless/disconnected_service +To override the log and/or config file locations, use the command-line arguments shown below: :: -Troubleshooting -=============== + $ python /usr/bin/f5/debug_bundler.py --log-dir=/var/log/mylogs --config-dir /etc/myconfigs/ ~/ -When the f5-openstack-agent is installed, the *debug_bundler.py* script will be installed to */usr/bin/f5/*. This script can be run from the command line directly. It will search in the specified directories to bundle log files and configuration files for use in debugging an issue with the f5-openstack-agent. In addition to the above files, it also dumps a complete listing of the ``pip lists`` output. -**WARNING** +Issues +`````` + +If you find any issues with the debug_bundler, please `file an issue <#filing-issues>`_. + + +For Developers +-------------- + +Filing Issues +````````````` + +If you find an issue, we would love to hear about it. +Please file an `issue `_ in this repository. +Use the issue template to tell us as much as you can about what you found, how you found it, your environment, etc. +Admins will triage your issue and assign it for a fix based on the priority level assigned. +We also welcome you to file issues for feature requests. + +Contributing +```````````` + +See `Contributing `_. -The files added to this bundle may contain VERY SENSITIVE INFORMATION such as encryption keys, passwords, and usernames. Do not upload this bundle, or any information within, to a public forum unless you have scrubbed sensitive information thoroughly. When in doubt, don't upload it at all. +Testing +``````` -Below you can see the basic usage, using the default command-line arguments: +Before you open a pull request, your code must have passing `pytest `__ unit tests. +In addition, you should include a set of functional tests written to use an actual BIG-IP device for testing. +Information on how to run our test set is included below. + +Style Checks +~~~~~~~~~~~~ + +We use the ``hacking`` module for our style checks. :: - $ python /usr/bin/f5/debug_bundler.py /home/myuser/debug_bundle_output/ + $ pip install tox + $ tox -e style + +Unit Tests +~~~~~~~~~~ -A tarred, compressed, file will be created in the directory specified. It will contain all logs and configuration files the script found. Note that the script offers a best-effort search of the directories given, and if it cannot find the log files it is looking for in those directories, it will print a message and continue running. +We use ``tox`` to run our ``pytest`` unit tests. -The default log location is set to `/var/log/neutron` and the default configuration file location is in `/etc/neutron`. These locations can be overriden via the command-line invocation shown below: +To run the unit tests, use the ``tox`` ``unit`` environment. :: - $ python /usr/bin/f5/debug_bundler.py --log-dir=/var/log/mylogs --config-dir /etc/myconfigs/ ~/ + $ pip install tox + $ tox -e unit + +Functional Tests +~~~~~~~~~~~~~~~~ + +You can run functional tests without a full OpenStack deployment. +They do require access to a BIG-IP device or BIG-IP Virtual Edition (VE) instance. + +#. Copy and edit the `symbols.json.example `_ with the correct values for your BIG-IP device. + +#. Run ``tox -e functest`` with the ``--symbols`` flag pointing to your updates symbols.json file. + + For example, the command below calls the symbols file and runs the ``neutronless/disconnected_service`` functional test cases. + The ``tox`` target changes to the ``[test/functional](test/functional)`` directory before the tests run. + +:: + + $ tox -e functest -- \ + --symbols ~/path/to/symbols/symbols.json \ + neutronless/disconnected_service + -If any issue is found with the debug_bundler script, please file an issue on GitHub. Copyright -********* +--------- -Copyright 2015-2016 F5 Networks Inc. +Copyright 2015-2017 F5 Networks Inc. Support -******* +------- See `Support `_. License -******* +------- Apache V2.0 -=========== +``````````` Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain @@ -158,9 +196,9 @@ See the License for the specific language governing permissions and limitations under the License. Contributor License Agreement -============================= +----------------------------- -Individuals or business entities who contribute to this project must have completed and submitted the `F5® Contributor License Agreement `_ to Openstack\_CLA@f5.com prior to their code submission being included in this project. +Individuals or business entities who contribute to this project must complete and submit the `F5 Contributor License Agreement `_ to Openstack\_CLA@f5.com **before** their code submission can be added to this project. .. |Build Status| image:: https://travis-ci.org/F5Networks/f5-openstack-agent.svg?branch=liberty diff --git a/SUPPORT.md b/SUPPORT.md index a6abb4b83..d848f2cf6 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,6 +1,6 @@ Maintenance and F5 Technical Support of the F5 code is provided only if the software (i) is unmodified; and (ii) has been marked as F5 Supported in -SOL80012344, (https://support.f5.com/kb/en-us/solutions/public/k/80/sol80012344.html). +SOL80012344, (https://support.f5.com/csp/article/K80012344). Support will only be provided to customers who have an existing support contract, purchased separately, subject to F5’s support policies available at http://www.f5.com/about/guidelines-policies/ and http://askf5.com. \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index cb57f8969..2b00b6354 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -47,6 +47,7 @@ help: @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " preview to build local preview of docs using sphinx-autobuild" .PHONY: clean clean: @@ -221,3 +222,11 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +# build live preview docs locally +.PHONY: preview +preview: + @echo "Running autobuild. View live edits at:" + @echo " http://0.0.0.0:8000/index.html" + @echo "" + sphinx-autobuild --host 0.0.0.0 -b html ./ $(BUILDDIR) \ No newline at end of file diff --git a/docs/README.rst b/docs/README.rst new file mode 100644 index 000000000..164de83df --- /dev/null +++ b/docs/README.rst @@ -0,0 +1,734 @@ +F5 Agent for OpenStack Neutron +============================== + +.. sidebar:: **OpenStack version:** + + |openstack| + +|Build Status| + +.. raw:: html + + + + +.. 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 + +.. _agent-installation: + +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 +`````` + +#. Download |agent| and its dependencies (``f5-icontrol-rest-python`` and ``f5-common-python``). +#. Install all three (3) packages. + + .. parsed-literal:: + + 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. + +.. parsed-literal:: + + pip install |f5_agent_pip_url| + + +.. tip:: + + Use ``@`` to install from HEAD on a specific branch. + + For example: + + .. parsed-literal:: + + pip install |f5_agent_pip_url_branch| + + +.. index:: + triple: f5-openstack-agent; install; rpm + + +RPM +``` + +#. Download |agent| and its dependencies (``f5-icontrol-rest-python`` and ``f5-common-python``). +#. Install all three (3) packages. + + .. parsed-literal:: + + 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 `. + +.. index:: + single: f5-openstack-agent; architecture + +.. _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 `. + +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. [#neutroncli]_ +The table below shows the corresponding iControl endpoint and BIG-IP object for each :code:`neutron lbaas-* create` command. + +.. table:: OpenStack Neutron to F5 iControl REST/BIG-IP command mapping + + ========================================== ============================================================================================ ================================== + Command URI Configurations Applied + ========================================== ============================================================================================ ================================== + :code:`neutron lbaas-loadbalancer-create` ``https://:443/mgmt/tm/sys/folder/~Project_`` Creates new BIG-IP partition; + name uses the OpenStack uuid and + tenant ID + ------------------------------------------ -------------------------------------------------------------------------------------------- ---------------------------------- + :code:`neutron lbaas-listener-create` ``https://:443/mgmt/tm/ltm/virtual/`` Creates new BIG-IP virtual server + in the tenant's partition + ------------------------------------------ -------------------------------------------------------------------------------------------- ---------------------------------- + :code:`neutron lbaas-pool-create` ``https://:443/mgmt/tm/ltm/pool/`` Creates new pool on the virtual + server + ------------------------------------------ -------------------------------------------------------------------------------------------- ---------------------------------- + :code:`neutron lbaas-member-create` ``https://:443/mgmt/tm/ltm/pool/~Project_~pool1/members/`` Creates new pool member on the + virtual server + ------------------------------------------ -------------------------------------------------------------------------------------------- ---------------------------------- + :code:`neutron lbaas-healthmonitor-create` ``https://:443/mgmt/tm/ltm/monitor/http/`` Creates new health monitor for the + pool + ========================================== ============================================================================================ ================================== + +.. index:: + single: f5-openstack-agent; supported features + +.. _agent-supported-features: + +Modes of Operation +------------------ + +* :ref:`Global Routed Mode ` +* :ref:`L2/L3-Adjacent Mode ` + + +.. index:: + single: f5-openstack-agent; configure + +.. _configure-the-f5-openstack-agent: + +Configure the |agent-long| +-------------------------- + +#. Use your text editor of choice to edit the :ref:`F5 Agent Configuration File` as appropriate for your environment. + + .. code-block:: console + + vim /etc/neutron/services/f5/f5-openstack-agent.ini + +.. _topic-start-the-agent: + +#. 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. + + .. rubric:: CentOS + .. code-block:: console + + systemctl enable f5-openstack-agent + systemctl start f5-openstack-agent + systemctl stop f5-openstack-agent.service + + .. rubric:: Ubuntu + .. code-block:: console + + service f5-oslbaasv2-agent start + service f5-oslbaasv2-agent stop + + +.. _agent-config-file: +.. _F5 Agent Configuration File: + +F5 Agent Configuration File +--------------------------- + +The :ref:`F5 Agent Configuration File ` (: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: + +a) where to find the BIG-IP device(s) you expect it to manage, and +b) 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 ` and :ref:`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. + + +.. _agent-config-parameters: + +Each section below corresponds to a section of the :ref:`F5 Agent Configuration File`. + +.. index:: + single: f5-openstack-agent; default settings + +.. _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 Any number of seconds, expressed as an Default=10 + the agent's attempts to sync its integer + state with Neutron +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +service_resync_interval integer Sets the frequency at which the Any number of seconds, expressed as an Default=500 + agent discards its service cache integer + and syncs with the Neutron LBaaS + service. +=============================== =========================== =================================== =========================================== ===================== + +.. index:: + single: f5-openstack-agent; environment settings + +.. _environment-settings: + +ENVIRONMENT SETTINGS +```````````````````` + +=============================== =========================== =================================== =========================================== ===================== +Parameter Type Description Allowed Values Recommended Value +=============================== =========================== =================================== =========================================== ===================== +environment_prefix string Sets the default prefix applied Any string beginning with an alpha Default=Project + to all BIG-IP LTM objects character. + in the tenant partition. +=============================== =========================== =================================== =========================================== ===================== + + +.. index:: + single: f5-openstack-agent; static agent configuration settings + +.. _static-agent-data-settings: + +STATIC AGENT CONFIGURATION SETTINGS +``````````````````````````````````` + +=============================== =========================== =================================== =========================================== ===================== +Parameter Type Description Allowed Values Recommended Value +=============================== =========================== =================================== =========================================== ===================== +static_agent_configuration_data key-value pair Defines static agent identification single key-value pair --OR-- N/A + data sent to the Neutron LBaaS comma-separated list of key-value pairs + plugin; used to identify agent + for custom pool-to-agent + scheduling. +=============================== =========================== =================================== =========================================== ===================== + +.. index:: + single: f5-openstack-agent; device settings + +.. _device-settings: + +DEVICE SETTINGS +``````````````` + +=============================== =========================== =================================== =========================================== ===================== +Parameter Type Description Allowed Values Recommended Value +=============================== =========================== =================================== =========================================== ===================== +f5_ha_type string Defines the BIG-IP device high - standalone: single BIG-IP device Default=standalone + availability (HA) mode. - pair: active/standby pair (2 BIG-IP + devices) + - scalen: active/active device cluster + (3 or more BIG-IP devices) +=============================== =========================== =================================== =========================================== ===================== + +.. index:: + single: f5-openstack-agent; L2 segmentation mode settings + +.. _l2-segmentation-settings: + +L2 SEGMENTATION MODE SETTINGS +````````````````````````````` + +==================================== ====================== =================================== =========================================== ===================== +Parameter Type Description Allowed Values Recommended Value +==================================== ====================== =================================== =========================================== ===================== +f5_external_physical_mappings string `Binds VLANs to BIG-IP interfaces`_ string in the format Default= + ; tells the agent about the "physical_network:interface_name:tagged" default:1.1:True + interface's VLAN tagging + settings 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. +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +vlan_binding_driver string Software hook allowing The vlan_binding_driver allows you to bind N/A + VLAN-interface-port mapping 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 +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +interface_port_static_mappings JSON dictionary Enabled by vlan_binding_driver; JSON dictionaries mapping BIG-IP devices N/A + maps BIG-IP devices and interfaces and interfaces to ports. + to specific ports + Follows the format + "{"device_name":{"interface_id":"port_id"}" +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_vtep_folder string The BIG-IP partition containing N/A /Common + the desired `VTEP`_ . +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_vtep_selfip_name string The name of the BIG-IP self IP to N/A vtep + use as the VTEP. +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +advertised_tunnel_types string The type of tunnel to use. vxlan, gre vxlan + + 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). +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_populate_static_arp boolean Controls BIG-IP TRUE: the agent adds static entries TRUE + `Address Resolution Protocol`_ for the IP and MAC addresses in the + (ARP) settings. Neutron LBaaS service definition to the + BIG-IP system ARP cache. + + FALSE: the agent discovers BIG-IP pool + members via flooding. +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +l2_population boolean Sets agent registration policy TRUE: the agent registers for ml2 TRUE + for `Neutron Modular Layer 2`_ population messages; these allow the agent + (ml2) messages 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. +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_network_segment_physical_network string The network segment the agent String; must be the name of the network N/A + should watch. 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. [#hpb]_ +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_network_segment_polling_interval integer The frequency at which the agent integer; in seconds 10 + should poll for disconnected LBaaS + listeners. [#hpb]_ Comment out this setting if + you are not using hierarchical port + binding. +------------------------------------ ---------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_pending_services_timeout integer Maximum amount of time before integer; in seconds 60 + creation of a pending service + errors out. [#hpb]_ Comment out this setting if + you are not using hierarchical port + binding. +==================================== ====================== =================================== =========================================== ===================== + +.. rubric:: Footnotes +.. [#hpb] See `Hierarchical Port Binding`_. + +.. index:: + single: f5-openstack-agent; L3 segmentation mode settings + +.. _l3-segmentation-settings: + +L3 SEGMENTATION MODE SETTINGS +````````````````````````````` + +=============================== =========================== =================================== =========================================== ===================== +Parameter Type Description Allowed Values Recommended Value +=============================== =========================== =================================== =========================================== ===================== +f5_global_routed_mode boolean Defines how the BIG-IP devices TRUE: BIG-IP device(s) connect directly to FALSE + connect to the network 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") +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +use_namespaces boolean Tells the agent if you're using TRUE: you're using BIG-IP route domains TRUE + `BIG-IP route domains`_ to segment tenant network traffic. + Forced to FALSE if + FALSE: you're not using route domains; f5_global_routed_mode + tenant networks cannot use overlapping = TRUE + subnets. +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +max_namespaces_per_tenant integer Sets the maximum number of Any integer, with the caveat that using 1 + namespaces/route tables the agent more than 1 namespace per tenant is NOT + can allocate per tenant a recommended practice. +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_route_domain_strictness boolean Controls the agent's access to TRUE: the agent can only access BIG-IP FALSE + BIG-IP global routing table tenant route domains; it cannot consult the + (route domain ``0``) global routing table. VIPs and members + can only communicate if they are in the + same tenant. + + Requires FALSE: the agent can look for a destination + ``use_namespaces=TRUE`` 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`_. +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_snat_mode boolean Tells the agent if it should TRUE: the agent manages a SNAT pool for the TRUE + allocate `BIG-IP SNAT pools`_ tenant. + for tenants Forced to TRUE if + When set to TRUE, incoming proxy traffic f5_global_routed_mode + uses IP addresses from the SNAT pool. = TRUE + + 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. +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_snat_addresses_per_subnet integer Defines how many IP addresses Any integer. 0 + to allocate in a SNAT pool + Set to ``0`` to use `automap SNAT`_ (the + BIG-IP device automatically creates a SNAT + pool for you). +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +f5_common_external_networks boolean Controls the agent's access to TRUE: the agent adds all provider TRUE + external (infrastructure-based) networks with ``route:external`` set + routes 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``. +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +common_networks key-value pair Tells the agent about shared single key-value pair --OR-- N/A + networks already configured on comma-separated list of key-value pairs + the BIG-IP device + Follows the format + "neutron_network_uuid:BIG-IP_network_name" +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +l3_binding_driver string Software hook allowing Allows you to bind L3 addresses to specific f5_openstack_agent. + L3_address-port binding ports. lbaasv2.drivers.bigip. + l3_binding. + AllowedAddressPairs +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +l3_binding_static_mappings JSON dictionary Using the l3_binding_driver, JSON-encoded dictionary; follows the format N/A + maps Neutron subnet ids to L2 + ports and devices 'subnet_id':[('port_id','BIG-IP_device') +=============================== =========================== =================================== =========================================== ===================== + +.. index:: + single: f5-openstack-agent; device driver/iControl driver settings + +.. _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 single or comma-separated list N/A + hostname, of your BIG-IP device(s) + and/or vCMP guest(s) +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +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 The username of an account with N/A + BIG-IP device permission to create partitions and + create/manage Local Traffic and Network + objects +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +icontrol_password string Password for the BIG-IP user See BIG-IP password requirements. N/A + account +=============================== =========================== =================================== =========================================== ===================== + +.. index:: + single: f5-openstack-agent; certificate manager settings + +.. _cert-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 f5_openstack_agent.lbaasv2.drivers.bigip. Default=None + driver barbican_cert.BarbicanCertManager +------------------------------- --------------------------- ----------------------------------- ------------------------------------------- --------------------- +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 + +.. _agent-config-examples: +.. _agent-config-file-example: + +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. + +.. rubric:: Global routed mode + +* :download:`Download global routed mode example ` + +.. rubric:: L2-adjacent mode + +* :download:`Download GRE example ` +* :download:`Download VLAN example ` +* :download:`Download VXLAN example ` + + +.. index:: + single: f5-openstack-agent; unsupported features + +.. _f5-agent-unsupported-features: + +Unsupported Features +-------------------- + +The items shown in the table below are not supported in the current release. + +.. table:: Unsupported Features in |release| + + ======================================= ================================== + Feature Project + ======================================= ================================== + `Distributed Virtual Router`_ (DVR) Neutron + --------------------------------------- ---------------------------------- + `Role Based Access Control`_ (RBAC) Neutron + --------------------------------------- ---------------------------------- + Agent High Availability (HA) [#agent]_ F5 OpenStack + ======================================= ================================== + +.. index:: + single: f5-openstack-agent; upgrade + +.. _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. + +#. 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. + + .. code-block:: bash + + $ cp /etc/neutron/services/f5/f5-openstack-agent.ini ~/f5-upgrade-temp + +#. 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. + + .. code-block:: bash + + $ mv /var/log/neutron/f5-openstack-agent.log ~/f5-upgrade-temp + +#. Stop and remove the current version of the |agent-short|. + + .. code-block:: bash + :caption: Debian/Ubuntu + + $ sudo service f5-oslbaasv2-agent stop + $ pip uninstall f5-openstack-agent + + .. code-block:: bash + :caption: Red Hat/CentOS + + $ sudo systemctl stop f5-openstack-agent + $ sudo systemctl disable f5-openstack-agent + $ sudo pip uninstall f5-openstack-agent + +#. Follow the :ref:`installation ` instructions to install a different version of the |agent-short|. + +#. 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 ` and :ref:`configuration parameters ` for explanations and config instructions. + + .. code-block:: bash + + $ cp ~/f5-upgrade-temp/f5-openstack-agent.ini /etc/neutron/services/f5/f5-openstack-agent.ini + + +.. rubric:: Footnotes +.. [#neutroncli] See the `Neutron LBaaS documentation `_ +.. [#agent] Similar to BIG-IP :term:`high availability`, but applies to the |agent-short| processes. + +.. |Build Status| image:: https://travis-ci.org/F5Networks/f5-openstack-agent.svg?branch=liberty + :target: https://travis-ci.org/F5Networks/f5-openstack-agent + :alt: Travis-CI Build Status +.. _OpenStack provider network: https://docs.openstack.org/newton/networking-guide/intro-os-networking.html#provider-networks +.. _Address Resolution Protocol: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/11.html +.. _Neutron Modular Layer 2: https://wiki.openstack.org/wiki/Neutron/ML2 +.. _BIG-IP route domains: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/8.html +.. _BIG-IP SNAT pools: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/7.html +.. _OpenStack Barbican: https://wiki.openstack.org/wiki/Barbican +.. _OpenStack Keystone: https://wiki.openstack.org/wiki/Keystone +.. _Binds VLANs to BIG-IP interfaces: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/4.html +.. _automap SNAT: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/7.html +.. _configures the requested objects: /cloud/openstack/latest/lbaas/bigip-command-mapping.html +.. _Distributed Virtual Router: https://specs.openstack.org/openstack/neutron-specs/specs/juno/neutron-ovs-dvr.html +.. _Role Based Access Control: http://specs.openstack.org/openstack/neutron-specs/specs/liberty/rbac-networks.html +.. _f5-openstack-ansible: https://github.com/f5devcentral/f5-openstack-ansible +.. _Deploy OpenStack Agent and Driver with Ansible: https://github.com/f5devcentral/f5-openstack-ansible/blob/master/playbooks/AGENT_DRIVER_DEPLOY.rst diff --git a/docs/_static/config_examples/f5-openstack-agent.gre.ini b/docs/_static/config_examples/f5-openstack-agent.gre.ini new file mode 100644 index 000000000..8e434b7c7 --- /dev/null +++ b/docs/_static/config_examples/f5-openstack-agent.gre.ini @@ -0,0 +1,535 @@ +############################################################################### +# Copyright 2015-2017 F5 Networks Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +############################################################################### +# +# ############ +# ################ +# ###/ _ \###| |# +# ###| |#| |##| |###### +# ####| |######| |###### +# ##| |####\ \### AGILITY YOUR WAY! +# ####| |#########| |### +# ####| |#########| |## +# ###| |########/ /## +# #| |####| /## +# ############## +# ########### +# +# NETWORKS +# +############################################################################### +# +[DEFAULT] +# Show debugging output in log (sets DEBUG log level output). +debug = True +# The LBaaS agent will resync its state with Neutron to recover from any +# transient notification or rpc errors. The interval is number of +# seconds between attempts. +# +periodic_interval = 10 +# +# How often should the agent throw away its service cache and +# resync assigned services with the neutron LBaaS plugin. +# +# service_resync_interval = 500 +# +# Objects created on the BIG-IP by this agent will have their names prefixed +# by an environment string. This allows you set this string. The default is +# 'project'. +# +# WARNING - you should only set this before creating any objects. If you change +# it with established objects, the objects created with an alternative prefix, +# will no longer be associated with this agent and all objects in neutron +# and on the the BIG-IP associated with the old environment will need to be managed +# manually. +# +############################################################################### +# Environment Settings +############################################################################### +# +# Since many TMOS object names must start with an alpha character +# the environment_prefix is used to prefix all service objects. +# +# environment_prefix = 'Project' +# +############################################################################### +# Static Agent Configuration Setting +############################################################################### +# +# Static configuration data to sent back to the plugin. This can be used +# on the plugin side of neutron to provide agent identification for custom +# pool to agent scheduling. This should be a single or comma separated list +# of name:value entries which will be sent in the agent's configuration +# dictionary to neutron. +# +# static_agent_configuration_data = location:DFW1_R122_U9, service_contract:8675309, contact:jenny +# +############################################################################### +# Device Setting +############################################################################### +# +# HA mode +# +# Device can be required to be: +# +# standalone - single device no HA +# pair - active/standby two device HA +# scalen - active device cluster +# +# If the device is external, the devices must be onboarded for the +# appropriate HA mode or else the driver will not provision devices +# +f5_ha_type = standalone +# +# +############################################################################### +# L2 Segmentation Mode Settings +############################################################################### +# +# Device VLAN to interface and tag mapping +# +# For pools or VIPs created on networks with type VLAN we will map +# the VLAN to a particular interface and state if the VLAN tagging +# should be enforced by the external device or not. This setting +# is a comma separated list of the following format: +# +# physical_network:interface_name:tagged, physical:interface_name:tagged +# +# where : +# physical_network corresponds to provider:physical_network attributes +# interface_name is the name of an interface or LAG trunk +# tagged is a boolean (True or False) +# +# If a network does not have a provider:physical_network attribute, +# or the provider:physical_network attribute does not match in the +# configured list, the 'default' physical_network setting will be +# applied. At a minimum you must have a 'default' physical_network +# setting. +# +# standalone example: +# f5_external_physical_mappings = default:1.1:True +# +# pair or scalen (1.1 and 1.2 are used for HA purposes): +# f5_external_physical_mappings = default:1.3:True +# +f5_external_physical_mappings = default:1.1:True +# +# VLAN device and interface to port mappings +# +# Some systems require the need to bind and prune VLANs ids +# allowed to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# tagged VLANs. When a VLAN tagged network is added to a +# specific BIG-IP device, the facing switch port will need +# to allow traffic for that VLAN tag through to the BIG-IP's +# port for traffic to flow. +# +# What is required is a software hook which allows the binding. +# A vlan_binding_driver class needs to reference a subclass of the +# VLANBindingBase class and provides the methods to bind and prune +# VLAN tags to ports. +# +# vlan_binding_driver = f5.oslbaasv1agent.drivers.bigip.vlan_binding.NullBinding +# +# The interface_port_static_mappings allows for a JSON encoded dictionary +# mapping BigIP devices and interfaces to corresponding ports. A port id can be +# any string which is meaningful to a vlan_binding_driver. It can be a +# switch_id and port, or it might be a neutron port_id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM interfaces will be collect +# for each device and neutron will be queried to see if which +# device port_ids correspond to known neutron ports. If they do, +# automatic entries for all mapped port_ids will be made referencing +# the BIG-IP device name and interface and the neutron port_ids. +# +# interface_port_static_mappings = {"device_name_1":{"interface_ida":"port_ida","interface_idb":"port_idb"}, {"device_name_2":{"interface_ida":"port_ida","interface_idb":"port_idb"}} +# +# example: +# +# interface_port_static_mappings = {"bigip1":{"1.1":"switch1:g2/32","1.2":"switch1:g2/33"},"bigip2":{"1.1":"switch1:g3/32","1.2":"switch1:g3/33"}} +# +# Device Tunneling (VTEP) selfips +# +# This is a single entry or comma separated list of cidr (h/m) format +# selfip addresses, one per BIG-IP device, to use for VTEP addresses. +# +# If no gre or vxlan tunneling is required, these settings should be +# commented out or set to None. +# +f5_vtep_folder = Common +f5_vtep_selfip_name = vtep +# +# +# Tunnel types +# +# This is a comma separated list of tunnel types to report +# as available from this agent as well as to send via tunnel_sync +# rpc messages to compute nodes. This should match your ml2 +# network types on your compute nodes. +# +# If you are using only gre tunnels it should be: +# +advertised_tunnel_types = gre +# +# If you are using only vxlan tunnels it should be: +# +# advertised_tunnel_types = vxlan +# +# If this agent could get both gre and vxlan tunnel networks: +# +# advertised_tunnel_types = gre,vxlan +# +# If you are using only vlans only it should be: +# +# advertised_tunnel_types = +# +# Static ARP population for members on tunnel networks +# +# This is a boolean True or False value which specifies +# that if a Pool Member IP address is associated with a gre +# or vxlan tunnel network, in addition to a tunnel fdb +# record being added, that a static arp entry will be created to +# avoid the need to learn the member's MAC address via flooding. +# +# f5_populate_static_arp = True +# +# Device Tunneling (VTEP) selfips +# +# This is a boolean entry which determines if they BIG-IP will use +# L2 Population service to update its fdb tunnel entries. This needs +# to be setup in accordance with the way the other tunnel agents are +# setup. If the BIG-IP agent and other tunnel agents don't match +# the tunnel setup will not work properly. +# +l2_population = True +# +# Hierarchical Port Binding +# +# If hierarchical networking is not required, these settings must be commented +# out or set to None. +# +# Restrict discovery of network segmentation ID to a specific physical network +# name. +# +# f5_network_segment_physical_network = +# +# Periodically scan for disconected listeners (a.k.a virtual servers). The +# interval is number of seconds between attempts. +# +# f5_network_segment_polling_interval = 10 +# +# Maximum amount of time in seconds for wait for a network to become connected. +# DEPECATED: This value is no longer used because the greenthread that used it +# for the Hierarchical Port Binding feature was removed. Please use: +# f5_pending_services_timeout. +# f5_network_segment_gross_timeout = 300 +# +# Maximum amount of time in seconds before a pending service gets moved into +# error state. Polling spacing is 10 seconds which is not yet configurable. +# +# f5_pending_services_timeout = 60 +# +############################################################################### +# L3 Segmentation Mode Settings +############################################################################### +# +# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP +# +# This setting will cause the agent to assume that all VIPs +# and pool members will be reachable via global device +# L3 routes, which must be already provisioned on the BIG-IPs. +# +# In f5_global_routed_mode, BIG-IP will not assume L2 +# adjacentcy to any neutron network, therefore no +# L2 segementation between tenant services in the data plane +# will be provisioned by the agent. Because the routing +# is global, no L3 self IPs or SNATs will be provisioned +# by the agent on behalf of tenants either. You must have +# all necessary L3 routes (including TMM default routes) +# provisioned before LBaaS resources are provisioned for tenants. +# +# WARNING: setting this mode to True will override +# the use_namespaces, setting it to False, because only +# one global routing space will used on the BIG-IP. This +# means overlapping IP addresses between tenants is no +# longer supported. +# +# WARNING: setting this mode to True will override +# the f5_snat_mode, setting it to True, because pool members +# will never be considered L2 adjacent to the BIG-IP by +# the agent. All member access will be via L3 routing, which +# will need to be set up on the BIG-IP before LBaaS provisions +# resources on behalf of tenants. +# +# WARNING: setting this mode to True will override the +# f5_snat_addresses_per_subnet, setting it to 0 (zero). +# This will force all VIPs to use AutoMap SNAT for which +# enough Self IP will need to be pre-provisioned on the +# BIG-IP to handle all pool member connections. The SNAT, +# an L3 mechanism, will all be global without reference +# to any specific tenant SNAT pool. +# +# WARNING: setting this mode will make the VIPs listen +# on all provisioned L2 segments (All VLANs). This is +# because no L2 information will be taken from +# neutron, thus making the assumption that all VIP +# L3 addresses will be globally routable without +# segmentation at L2 on the BIG-IP. +# +f5_global_routed_mode = False +# +# Allow overlapping IP subnets across multiple tenants. +# This creates route domains on BIG-IP in order to +# separate the tenant networks. +# +# This setting is forced to False if +# f5_global_routed_mode = True. +# +use_namespaces = True +# +# When use_namespaces is True there is normally only one route table +# allocated per tenant. However, this limit can be increased by +# changing the max_namespaces_per_tenant variable. This allows one +# tenant to have overlapping IP subnets. +# +# Supporting multiple IP namespaces allows establishing multiple independent +# IP routing topologies within one tenant project, which, for example, +# can accomodate multiple testing environments in one project, with +# each testing environment configured to use the same IP address +# topology as each other test environment. +# +# From a practical point of view, allowing multiple IP namespaces +# per tenant results in a more complicated configuration scheme +# for big-ip and also allows a single tenant to consumes more +# routing tables, which are a limited resource. In order to keep +# a simple one-to-one strategy of one tenant to one route domain, +# it is recommended that separate projects be used if possible to +# establish a new routing namespace rather than allowing multiple route +# domains within one tenant. +# +# If a tenant attempts to use a subnet that overlaps with an existing +# subnet that is already in use in the existing route domain(s), and +# this setting is not high enough to accomodate a new route domain to +# handle the new subnet, then the relevant lbaas element (vip or pool member) +# will be set to the error state. +# +max_namespaces_per_tenant = 1 +# +# Dictates the strict isolation of the routing +# tables. If you set this to True, then all +# VIPs and Members must be in the same tenant +# or else they can't communicate. +# +# This setting is only valid if use_namespaces = True. +# +f5_route_domain_strictness = False +# +# SNAT Mode and SNAT Address Counts +# +# This setting will force the use of SNATs. +# +# If this is set to False, a SNAT will not +# be created (routed mode) and the BIG-IP +# will attempt to set up a floating self IP +# as the subnet's default gateway address. +# and a wild card IP forwarding virtual +# server will be set up on member's network. +# Setting this to False will mean Neutron +# floating self IPs will not longer work +# if the same BIG-IP device is not being used +# as the Neutron Router implementation. +# +# This setting will be forced to True if +# f5_global_routed_mode = True. +# +f5_snat_mode = True +# +# This setting will specify the number of snat +# addresses to put in a snat pool for each +# subnet associated with a created local Self IP. +# +# Setting to 0 (zero) will set VIPs to AutoMap +# SNAT and the device's local Self IP will +# be used to SNAT traffic. +# +# In scalen HA mode, this is the number of snat +# addresses per active traffic-group at the time +# a service is provisioned. +# +# This setting will be forced to 0 (zero) if +# f5_global_routed_mode = True. +# +f5_snat_addresses_per_subnet = 1 +# +# This setting will cause all networks with +# the router:external attribute set to True +# to be created in the Common partition and +# placed in route domain 0. +f5_common_external_networks = True +# +# +# Common Networks +# +# This setting contains a name value pair comma +# separated list where if the name is a neutron +# network id used for a vip or a pool member, +# the network should not be created or deleted +# on the BIG-IP, but rather assumed that the value +# is the name of the network already created in +# the Common partition with all L3 addresses +# assigned to route domain 0. This is useful +# for shared networks which are already defined +# on the BIG-IP prior to LBaaS configuration. The +# network should not be managed by the LBaaS agent, +# but can be used for VIPs or pool members +# +# If your Internet VLAN on your BIG-IP is named +# /Common/external, and that corresponds to +# Neutron uuid: 71718972-78e2-449e-bb56-ce47cc9d2680 +# then the entry would look like: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external +# +# If you had multiple common networks, they are simply +# comma separated like this example: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external,396e06a0-05c7-4a49-8e86-04bb83d14438:vlan1222 +# +# The default is no common networks defined +# +# L3 Bindings +# +# Some systems require the need to bind L3 addresses +# to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# untagged VLANs and is a nova guest instance. By +# default, neutron will attempt to apply security rule +# for anti-spoofing which will not allow just any L3 +# address to be used on the neutron port. The answer is to +# use allowed-address-pairs for the neutron port. +# +# What is required is a software hook which allows the binding. +# l3_binding_driver needs to reference a subclass of the L3BindingBase +# class and provides the methods to bind and unbind L3 address +# to ports. +# +# l3_binding_driver = f5_openstack_agent.lbaasv2.drivers.bigip.l3_binding.AllowedAddressPairs +# +# The l3_binding_static_mappings allows for a JSON encoded dictionary +# mapping neutron subnet ids to lists of L2 ports and devices which +# require mapping. The entries for port and device mappings +# vary between providers. They may look like a neutron port id +# and a nova guest instance id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM MAC addresses will be collected +# and neutron will be queried to see if the MAC addresses +# correspond to known neutron ports. If they do, automatic entries +# for all mapped fixed_ips will be made referencing the ports id +# and the ports device_id. +# +# l3_binding_static_mappings = 'subnet_a':[('port_a','device_a'),('port_b','device_b')], 'subnet_b':[('port_c','device_a'),('port_d','device_b')] +# +# +# +############################################################################### +# Device Driver Setting +############################################################################### +# +f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol_driver.iControlDriver +# +# +############################################################################### +# Device Driver - iControl Driver Setting +############################################################################### +# +# icontrol_hostname is valid for external device type only. +# this setting can be either a single IP address or a +# comma separated list contain all devices in a device +# service group. For guest devices, the first fixed_address +# on the first device interfaces will be used. +# +# If a single IP address is used and the HA model +# is not standalone, all devices in the sync failover +# device group for the hostname specified must have +# their management IP address reachable to the agent. +# If order to access devices' iControl interfaces via +# self IPs, you should specify them as a comma +# separated list below. +# +icontrol_hostname = 10.190.0.0 +# +# If you are using vCMP with VLANs, you will need to configure +# your vCMP host addresses, in addition to the guests addresses. +# vCMP Host access is necessary for provisioning VLANs to a guest. +# Use icontrol_hostname for vCMP guests and icontrol_vcmp_hostname +# for vCMP hosts. The plug-in will automatically determine +# which host corresponds to each guest. +# +# icontrol_vcmp_hostname = 192.168.1.245 +# +# icontrol_username must be a valid Administrator username +# on all devices in a device sync failover group. +# +icontrol_username = admin +# +# icontrol_password must be a valid Administrator password +# on all devices in a device sync failover group. +# +icontrol_password = admin +# +############################################################################### +# Certificate Manager +############################################################################### +#cert_manager = f5_openstack_agent.lbaasv2.drivers.bigip.barbican_cert.BarbicanCertManager +# +# Two authentication modes are supported for BarbicanCertManager: +# keystone_v2, and keystone_v3 +# +# +# Keystone v2 authentication: +# +# auth_version = v2 +# os_auth_url = http://localhost:5000/v2.0 +# os_username = admin +# os_password = changeme +# os_tenant_name = admin +# +# +# Keystone v3 authentication: +# +#auth_version = v3 +#os_auth_url = http://localhost:5000/v3 +#os_username = admin +#os_password = changeme +#os_user_domain_name = default +#os_project_name = admin +#os_project_domain_name = default +# +# +# Parent SSL profile name +# +# A client SSL profile is created for LBaaS listeners that use TERMINATED_HTTPS +# protocol. You can define the parent profile for this profile by setting +# f5_parent_ssl_profile. The profile created to support TERMINATTED_HTTPS will +# inherit settings from the parent you define. This must be an existing profile, +# and if it does not exist on your BIG-IP system the agent will use the default +# profile, clientssl. +#f5_parent_ssl_profile = clientssl +# diff --git a/docs/_static/config_examples/f5-openstack-agent.grm.ini b/docs/_static/config_examples/f5-openstack-agent.grm.ini new file mode 100644 index 000000000..5f76405e2 --- /dev/null +++ b/docs/_static/config_examples/f5-openstack-agent.grm.ini @@ -0,0 +1,534 @@ +############################################################################### +# Copyright 2015-2017 F5 Networks Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +############################################################################### +# +# ############ +# ################ +# ###/ _ \###| |# +# ###| |#| |##| |###### +# ####| |######| |###### +# ##| |####\ \### AGILITY YOUR WAY! +# ####| |#########| |### +# ####| |#########| |## +# ###| |########/ /## +# #| |####| /## +# ############## +# ########### +# +# NETWORKS +# +############################################################################### +# +[DEFAULT] +# Show debugging output in log (sets DEBUG log level output). +debug = True +# The LBaaS agent will resync its state with Neutron to recover from any +# transient notification or rpc errors. The interval is number of +# seconds between attempts. +# +periodic_interval = 10 +# +# How often should the agent throw away its service cache and +# resync assigned services with the neutron LBaaS plugin. +# +# service_resync_interval = 500 +# +# Objects created on the BIG-IP by this agent will have their names prefixed +# by an environment string. This allows you set this string. The default is +# 'Project'. +# +# WARNING - you should only set this before creating any objects. If you change +# it with established objects, the objects created with an alternative prefix, +# will no longer be associated with this agent and all objects in neutron +# and on the the BIG-IP associated with the old environment will need to be managed +# manually. +# +############################################################################### +# Environment Settings +############################################################################### +# +# Since many TMOS object names must start with an alpha character +# the environment_prefix is used to prefix all service objects. +# +# environment_prefix = 'Project' +# +############################################################################### +# Static Agent Configuration Setting +############################################################################### +# +# Static configuration data to sent back to the plugin. This can be used +# on the plugin side of neutron to provide agent identification for custom +# pool to agent scheduling. This should be a single or comma separated list +# of name:value entries which will be sent in the agent's configuration +# dictionary to neutron. +# +# static_agent_configuration_data = location:DFW1_R122_U9, service_contract:8675309, contact:jenny +# +############################################################################### +# Device Setting +############################################################################### +# +# HA mode +# +# Device can be required to be: +# +# standalone - single device no HA +# pair - active/standby two device HA +# scalen - active device cluster +# +# If the device is external, the devices must be onboarded for the +# appropriate HA mode or else the driver will not provision devices +# +f5_ha_type = standalone +# +# +############################################################################### +# L2 Segmentation Mode Settings +############################################################################### +# +# Device VLAN to interface and tag mapping +# +# For pools or VIPs created on networks with type VLAN we will map +# the VLAN to a particular interface and state if the VLAN tagging +# should be enforced by the external device or not. This setting +# is a comma separated list of the following format: +# +# physical_network:interface_name:tagged, physical:interface_name:tagged +# +# where : +# physical_network corresponds to provider:physical_network attributes +# interface_name is the name of an interface or LAG trunk +# tagged is a boolean (True or False) +# +# If a network does not have a provider:physical_network attribute, +# or the provider:physical_network attribute does not match in the +# configured list, the 'default' physical_network setting will be +# applied. At a minimum you must have a 'default' physical_network +# setting. +# +# standalone example: +# f5_external_physical_mappings = default:1.1:True +# +# pair or scalen (1.1 and 1.2 are used for HA purposes): +# f5_external_physical_mappings = default:1.3:True +# +f5_external_physical_mappings = default:1.1:True +# +# VLAN device and interface to port mappings +# +# Some systems require the need to bind and prune VLANs ids +# allowed to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# tagged VLANs. When a VLAN tagged network is added to a +# specific BIG-IP device, the facing switch port will need +# to allow traffic for that VLAN tag through to the BIG-IP's +# port for traffic to flow. +# +# What is required is a software hook which allows the binding. +# A vlan_binding_driver class needs to reference a subclass of the +# VLANBindingBase class and provides the methods to bind and prune +# VLAN tags to ports. +# +# vlan_binding_driver = f5.oslbaasv1agent.drivers.bigip.vlan_binding.NullBinding +# +# The interface_port_static_mappings allows for a JSON encoded dictionary +# mapping BigIP devices and interfaces to corresponding ports. A port id can be +# any string which is meaningful to a vlan_binding_driver. It can be a +# switch_id and port, or it might be a neutron port_id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM interfaces will be collect +# for each device and neutron will be queried to see if which +# device port_ids correspond to known neutron ports. If they do, +# automatic entries for all mapped port_ids will be made referencing +# the BIG-IP device name and interface and the neutron port_ids. +# +# interface_port_static_mappings = {"device_name_1":{"interface_ida":"port_ida","interface_idb":"port_idb"}, {"device_name_2":{"interface_ida":"port_ida","interface_idb":"port_idb"}} +# +# example: +# +# interface_port_static_mappings = {"bigip1":{"1.1":"switch1:g2/32","1.2":"switch1:g2/33"},"bigip2":{"1.1":"switch1:g3/32","1.2":"switch1:g3/33"}} +# +# Device Tunneling (VTEP) Self IPs +# +# This is the name of a BIG-IP self IP address to use for VTEP addresses. +# +# If no gre or vxlan tunneling is required, these settings should be +# commented out or set to None. +# +#f5_vtep_folder = 'Common' +#f5_vtep_selfip_name = 'vtep' +# +# +# Tunnel types +# +# This is a comma separated list of tunnel types to report +# as available from this agent as well as to send via tunnel_sync +# rpc messages to compute nodes. This should match your ml2 +# network types on your compute nodes. +# +# If you are using only gre tunnels it should be: +# +#advertised_tunnel_types = gre +# +# If you are using only vxlan tunnels it should be: +# +# advertised_tunnel_types = vxlan +# +# If this agent could get both gre and vxlan tunnel networks: +# +# advertised_tunnel_types = gre,vxlan +# +# If you are using only vlans only it should be: +# +# advertised_tunnel_types = vlan +# +# Static ARP population for members on tunnel networks +# +# This is a boolean True or False value which specifies +# that if a Pool Member IP address is associated with a gre +# or vxlan tunnel network, in addition to a tunnel fdb +# record being added, that a static arp entry will be created to +# avoid the need to learn the member's MAC address via flooding. +# +# f5_populate_static_arp = True +# +# Device Tunneling (VTEP) selfips +# +# This is a boolean entry which determines if they BIG-IP will use +# L2 Population service to update its fdb tunnel entries. This needs +# to be setup in accordance with the way the other tunnel agents are +# setup. If the BIG-IP agent and other tunnel agents don't match +# the tunnel setup will not work properly. +# +l2_population = True +# +# Hierarchical Port Binding +# +# If hierarchical networking is not required, these settings must be commented +# out or set to None. +# +# Restrict discovery of network segmentation ID to a specific physical network +# name. +# +# f5_network_segment_physical_network = +# +# Periodically scan for disconected listeners (a.k.a virtual servers). The +# interval is number of seconds between attempts. +# +# f5_network_segment_polling_interval = 10 +# +# Maximum amount of time in seconds for wait for a network to become connected. +# DEPECATED: This value is no longer used because the greenthread that used it +# for the Hierarchical Port Binding feature was removed. Please use: +# f5_pending_services_timeout. +# f5_network_segment_gross_timeout = 300 +# +# Maximum amount of time in seconds before a pending service gets moved into +# error state. Polling spacing is 10 seconds which is not yet configurable. +# +# f5_pending_services_timeout = 60 +# +############################################################################### +# L3 Segmentation Mode Settings +############################################################################### +# +# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP +# +# This setting will cause the agent to assume that all VIPs +# and pool members will be reachable via global device +# L3 routes, which must be already provisioned on the BIG-IPs. +# +# In f5_global_routed_mode, BIG-IP will not assume L2 +# adjacentcy to any neutron network, therefore no +# L2 segementation between tenant services in the data plane +# will be provisioned by the agent. Because the routing +# is global, no L3 self IPs or SNATs will be provisioned +# by the agent on behalf of tenants either. You must have +# all necessary L3 routes (including TMM default routes) +# provisioned before LBaaS resources are provisioned for tenants. +# +# WARNING: setting this mode to True will override +# the use_namespaces, setting it to False, because only +# one global routing space will used on the BIG-IP. This +# means overlapping IP addresses between tenants is no +# longer supported. +# +# WARNING: setting this mode to True will override +# the f5_snat_mode, setting it to True, because pool members +# will never be considered L2 adjacent to the BIG-IP by +# the agent. All member access will be via L3 routing, which +# will need to be set up on the BIG-IP before LBaaS provisions +# resources on behalf of tenants. +# +# WARNING: setting this mode to True will override the +# f5_snat_addresses_per_subnet, setting it to 0 (zero). +# This will force all VIPs to use AutoMap SNAT for which +# enough Self IP will need to be pre-provisioned on the +# BIG-IP to handle all pool member connections. The SNAT, +# an L3 mechanism, will all be global without reference +# to any specific tenant SNAT pool. +# +# WARNING: setting this mode will make the VIPs listen +# on all provisioned L2 segments (All VLANs). This is +# because no L2 information will be taken from +# neutron, thus making the assumption that all VIP +# L3 addresses will be globally routable without +# segmentation at L2 on the BIG-IP. +# +f5_global_routed_mode = True +# +# Allow overlapping IP subnets across multiple tenants. +# This creates route domains on BIG-IP in order to +# separate the tenant networks. +# +# This setting is forced to False if +# f5_global_routed_mode = True. +# +use_namespaces = False +# +# When use_namespaces is True there is normally only one route table +# allocated per tenant. However, this limit can be increased by +# changing the max_namespaces_per_tenant variable. This allows one +# tenant to have overlapping IP subnets. +# +# Supporting multiple IP namespaces allows establishing multiple independent +# IP routing topologies within one tenant project, which, for example, +# can accomodate multiple testing environments in one project, with +# each testing environment configured to use the same IP address +# topology as each other test environment. +# +# From a practical point of view, allowing multiple IP namespaces +# per tenant results in a more complicated configuration scheme +# for big-ip and also allows a single tenant to consumes more +# routing tables, which are a limited resource. In order to keep +# a simple one-to-one strategy of one tenant to one route domain, +# it is recommended that separate projects be used if possible to +# establish a new routing namespace rather than allowing multiple route +# domains within one tenant. +# +# If a tenant attempts to use a subnet that overlaps with an existing +# subnet that is already in use in the existing route domain(s), and +# this setting is not high enough to accomodate a new route domain to +# handle the new subnet, then the relevant lbaas element (vip or pool member) +# will be set to the error state. +# +max_namespaces_per_tenant = 1 +# +# Dictates the strict isolation of the routing +# tables. If you set this to True, then all +# VIPs and Members must be in the same tenant +# or less they can't communicate. +# +# This setting is only valid if use_namespaces = True. +# +f5_route_domain_strictness = False +# +# SNAT Mode and SNAT Address Counts +# +# This setting will force the use of SNATs. +# +# If this is set to False, a SNAT will not +# be created (routed mode) and the BIG-IP +# will attempt to set up a floating self IP +# as the subnet's default gateway address. +# and a wild card IP forwarding virtual +# server will be set up on member's network. +# Setting this to False will mean Neutron +# floating self IPs will not longer work +# if the same BIG-IP device is not being used +# as the Neutron Router implementation. +# +# This setting will be forced to True if +# f5_global_routed_mode = True. +# +f5_snat_mode = True +# +# This setting will specify the number of snat +# addresses to put in a snat pool for each +# subnet associated with a created local Self IP. +# +# Setting to 0 (zero) will set VIPs to AutoMap +# SNAT and the device's local Self IP will +# be used to SNAT traffic. +# +# In scalen HA mode, this is the number of snat +# addresses per active traffic-group at the time +# a service is provisioned. +# +# This setting will be forced to 0 (zero) if +# f5_global_routed_mode = True. +# +f5_snat_addresses_per_subnet = 0 +# +# This setting will cause all networks with +# the router:external attribute set to True +# to be created in the Common partition and +# placed in route domain 0. +f5_common_external_networks = True +# +# +# Common Networks +# +# This setting contains a name value pair comma +# separated list where if the name is a neutron +# network id used for a vip or a pool member, +# the network should not be created or deleted +# on the BIG-IP, but rather assumed that the value +# is the name of the network already created in +# the Common partition with all L3 addresses +# assigned to route domain 0. This is useful +# for shared networks which are already defined +# on the BIG-IP prior to LBaaS configuration. The +# network should not be managed by the LBaaS agent, +# but can be used for VIPs or pool members +# +# If your Internet VLAN on your BIG-IP is named +# /Common/external, and that corresponds to +# Neutron uuid: 71718972-78e2-449e-bb56-ce47cc9d2680 +# then the entry would look like: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external +# +# If you had multiple common networks, they are simply +# comma separated like this example: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external,396e06a0-05c7-4a49-8e86-04bb83d14438:vlan1222 +# +# The default is no common networks defined +# +# L3 Bindings +# +# Some systems require the need to bind L3 addresses +# to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# untagged VLANs and is a nova guest instance. By +# default, neutron will attempt to apply security rule +# for anti-spoofing which will not allow just any L3 +# address to be used on the neutron port. The answer is to +# use allowed-address-pairs for the neutron port. +# +# What is required is a software hook which allows the binding. +# l3_binding_driver needs to reference a subclass of the L3BindingBase +# class and provides the methods to bind and unbind L3 address +# to ports. +# +# l3_binding_driver = f5_openstack_agent.lbaasv2.drivers.bigip.l3_binding.AllowedAddressPairs +# +# The l3_binding_static_mappings allows for a JSON encoded dictionary +# mapping neutron subnet ids to lists of L2 ports and devices which +# require mapping. The entries for port and device mappings +# vary between providers. They may look like a neutron port id +# and a nova guest instance id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM MAC addresses will be collected +# and neutron will be queried to see if the MAC addresses +# correspond to known neutron ports. If they do, automatic entries +# for all mapped fixed_ips will be made referencing the ports id +# and the ports device_id. +# +# l3_binding_static_mappings = 'subnet_a':[('port_a','device_a'),('port_b','device_b')], 'subnet_b':[('port_c','device_a'),('port_d','device_b')] +# +# +# +############################################################################### +# Device Driver Setting +############################################################################### +# +f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol_driver.iControlDriver +# +# +############################################################################### +# Device Driver - iControl Driver Setting +############################################################################### +# +# icontrol_hostname is valid for external device type only. +# this setting can be either a single IP address or a +# comma separated list contain all devices in a device +# service group. For guest devices, the first fixed_address +# on the first device interfaces will be used. +# +# If a single IP address is used and the HA model +# is not standalone, all devices in the sync failover +# device group for the hostname specified must have +# their management IP address reachable to the agent. +# If order to access devices' iControl interfaces via +# self IPs, you should specify them as a comma +# separated list below. +# +icontrol_hostname = 10.190.0.0 +# +# If you are using vCMP with VLANs, you will need to configure +# your vCMP host addresses, in addition to the guests addresses. +# vCMP Host access is necessary for provisioning VLANs to a guest. +# Use icontrol_hostname for vCMP guests and icontrol_vcmp_hostname +# for vCMP hosts. The plug-in will automatically determine +# which host corresponds to each guest. +# +# icontrol_vcmp_hostname = 192.168.1.245 +# +# icontrol_username must be a valid Administrator username +# on all devices in a device sync failover group. +# +icontrol_username = admin +# +# icontrol_password must be a valid Administrator password +# on all devices in a device sync failover group. +# +icontrol_password = admin +# +############################################################################### +# Certificate Manager +############################################################################### +#cert_manager = f5_openstack_agent.lbaasv2.drivers.bigip.barbican_cert.BarbicanCertManager +# +# Two authentication modes are supported for BarbicanCertManager: +# keystone_v2, and keystone_v3 +# +# +# Keystone v2 authentication: +# +# auth_version = v2 +# os_auth_url = http://localhost:5000/v2.0 +# os_username = admin +# os_password = changeme +# os_tenant_name = admin +# +# +# Keystone v3 authentication: +# +#auth_version = v3 +#os_auth_url = http://localhost:5000/v3 +#os_username = admin +#os_password = changeme +#os_user_domain_name = default +#os_project_name = admin +#os_project_domain_name = default +# +# +# Parent SSL profile name +# +# A client SSL profile is created for LBaaS listeners that use TERMINATED_HTTPS +# protocol. You can define the parent profile for this profile by setting +# f5_parent_ssl_profile. The profile created to support TERMINATTED_HTTPS will +# inherit settings from the parent you define. This must be an existing profile, +# and if it does not exist on your BIG-IP system the agent will use the default +# profile, clientssl. +#f5_parent_ssl_profile = clientssl +# \ No newline at end of file diff --git a/docs/_static/config_examples/f5-openstack-agent.vlan.ini b/docs/_static/config_examples/f5-openstack-agent.vlan.ini new file mode 100644 index 000000000..0ee909fea --- /dev/null +++ b/docs/_static/config_examples/f5-openstack-agent.vlan.ini @@ -0,0 +1,535 @@ +############################################################################### +# Copyright 2015-2017 F5 Networks Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +############################################################################### +# +# ############ +# ################ +# ###/ _ \###| |# +# ###| |#| |##| |###### +# ####| |######| |###### +# ##| |####\ \### AGILITY YOUR WAY! +# ####| |#########| |### +# ####| |#########| |## +# ###| |########/ /## +# #| |####| /## +# ############## +# ########### +# +# NETWORKS +# +############################################################################### +# +[DEFAULT] +# Show debugging output in log (sets DEBUG log level output). +debug = True +# The LBaaS agent will resync its state with Neutron to recover from any +# transient notification or rpc errors. The interval is number of +# seconds between attempts. +# +periodic_interval = 10 +# +# How often should the agent throw away its service cache and +# resync assigned services with the neutron LBaaS plugin. +# +# service_resync_interval = 500 +# +# Objects created on the BIG-IP by this agent will have their names prefixed +# by an environment string. This allows you set this string. The default is +# 'project'. +# +# WARNING - you should only set this before creating any objects. If you change +# it with established objects, the objects created with an alternative prefix, +# will no longer be associated with this agent and all objects in neutron +# and on the the BIG-IP associated with the old environment will need to be managed +# manually. +# +############################################################################### +# Environment Settings +############################################################################### +# +# Since many TMOS object names must start with an alpha character +# the environment_prefix is used to prefix all service objects. +# +# environment_prefix = 'Project' +# +############################################################################### +# Static Agent Configuration Setting +############################################################################### +# +# Static configuration data to sent back to the plugin. This can be used +# on the plugin side of neutron to provide agent identification for custom +# pool to agent scheduling. This should be a single or comma separated list +# of name:value entries which will be sent in the agent's configuration +# dictionary to neutron. +# +# static_agent_configuration_data = location:DFW1_R122_U9, service_contract:8675309, contact:jenny +# +############################################################################### +# Device Setting +############################################################################### +# +# HA mode +# +# Device can be required to be: +# +# standalone - single device no HA +# pair - active/standby two device HA +# scalen - active device cluster +# +# If the device is external, the devices must be onboarded for the +# appropriate HA mode or else the driver will not provision devices +# +f5_ha_type = standalone +# +# +############################################################################### +# L2 Segmentation Mode Settings +############################################################################### +# +# Device VLAN to interface and tag mapping +# +# For pools or VIPs created on networks with type VLAN we will map +# the VLAN to a particular interface and state if the VLAN tagging +# should be enforced by the external device or not. This setting +# is a comma separated list of the following format: +# +# physical_network:interface_name:tagged, physical:interface_name:tagged +# +# where : +# physical_network corresponds to provider:physical_network attributes +# interface_name is the name of an interface or LAG trunk +# tagged is a boolean (True or False) +# +# If a network does not have a provider:physical_network attribute, +# or the provider:physical_network attribute does not match in the +# configured list, the 'default' physical_network setting will be +# applied. At a minimum you must have a 'default' physical_network +# setting. +# +# standalone example: +# f5_external_physical_mappings = default:1.1:True +# +# pair or scalen (1.1 and 1.2 are used for HA purposes): +# f5_external_physical_mappings = default:1.3:True +# +f5_external_physical_mappings = default:1.1:True +# +# VLAN device and interface to port mappings +# +# Some systems require the need to bind and prune VLANs ids +# allowed to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# tagged VLANs. When a VLAN tagged network is added to a +# specific BIG-IP device, the facing switch port will need +# to allow traffic for that VLAN tag through to the BIG-IP's +# port for traffic to flow. +# +# What is required is a software hook which allows the binding. +# A vlan_binding_driver class needs to reference a subclass of the +# VLANBindingBase class and provides the methods to bind and prune +# VLAN tags to ports. +# +# vlan_binding_driver = f5.oslbaasv1agent.drivers.bigip.vlan_binding.NullBinding +# +# The interface_port_static_mappings allows for a JSON encoded dictionary +# mapping BigIP devices and interfaces to corresponding ports. A port id can be +# any string which is meaningful to a vlan_binding_driver. It can be a +# switch_id and port, or it might be a neutron port_id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM interfaces will be collect +# for each device and neutron will be queried to see if which +# device port_ids correspond to known neutron ports. If they do, +# automatic entries for all mapped port_ids will be made referencing +# the BIG-IP device name and interface and the neutron port_ids. +# +# interface_port_static_mappings = {"device_name_1":{"interface_ida":"port_ida","interface_idb":"port_idb"}, {"device_name_2":{"interface_ida":"port_ida","interface_idb":"port_idb"}} +# +# example: +# +# interface_port_static_mappings = {"bigip1":{"1.1":"switch1:g2/32","1.2":"switch1:g2/33"},"bigip2":{"1.1":"switch1:g3/32","1.2":"switch1:g3/33"}} +# +# Device Tunneling (VTEP) selfips +# +# This is a single entry or comma separated list of cidr (h/m) format +# selfip addresses, one per BIG-IP device, to use for VTEP addresses. +# +# If no gre or vxlan tunneling is required, these settings should be +# commented out or set to None. +# +f5_vtep_folder = None +f5_vtep_selfip_name = None +# +# +# Tunnel types +# +# This is a comma separated list of tunnel types to report +# as available from this agent as well as to send via tunnel_sync +# rpc messages to compute nodes. This should match your ml2 +# network types on your compute nodes. +# +# If you are using only gre tunnels it should be: +# +# advertised_tunnel_types = gre +# +# If you are using only vxlan tunnels it should be: +# +# advertised_tunnel_types = vxlan +# +# If this agent could get both gre and vxlan tunnel networks: +# +# advertised_tunnel_types = gre,vxlan +# +# If you are using only vlans only it should be: +# +advertised_tunnel_types = +# +# Static ARP population for members on tunnel networks +# +# This is a boolean True or False value which specifies +# that if a Pool Member IP address is associated with a gre +# or vxlan tunnel network, in addition to a tunnel fdb +# record being added, that a static arp entry will be created to +# avoid the need to learn the member's MAC address via flooding. +# +# f5_populate_static_arp = True +# +# Device Tunneling (VTEP) selfips +# +# This is a boolean entry which determines if they BIG-IP will use +# L2 Population service to update its fdb tunnel entries. This needs +# to be setup in accordance with the way the other tunnel agents are +# setup. If the BIG-IP agent and other tunnel agents don't match +# the tunnel setup will not work properly. +# +l2_population = True +# +# Hierarchical Port Binding +# +# If hierarchical networking is not required, these settings must be commented +# out or set to None. +# +# Restrict discovery of network segmentation ID to a specific physical network +# name. +# +# f5_network_segment_physical_network = +# +# Periodically scan for disconected listeners (a.k.a virtual servers). The +# interval is number of seconds between attempts. +# +# f5_network_segment_polling_interval = 10 +# +# Maximum amount of time in seconds for wait for a network to become connected. +# DEPECATED: This value is no longer used because the greenthread that used it +# for the Hierarchical Port Binding feature was removed. Please use: +# f5_pending_services_timeout. +# f5_network_segment_gross_timeout = 300 +# +# Maximum amount of time in seconds before a pending service gets moved into +# error state. Polling spacing is 10 seconds which is not yet configurable. +# +# f5_pending_services_timeout = 60 +# +############################################################################### +# L3 Segmentation Mode Settings +############################################################################### +# +# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP +# +# This setting will cause the agent to assume that all VIPs +# and pool members will be reachable via global device +# L3 routes, which must be already provisioned on the BIG-IPs. +# +# In f5_global_routed_mode, BIG-IP will not assume L2 +# adjacentcy to any neutron network, therefore no +# L2 segementation between tenant services in the data plane +# will be provisioned by the agent. Because the routing +# is global, no L3 self IPs or SNATs will be provisioned +# by the agent on behalf of tenants either. You must have +# all necessary L3 routes (including TMM default routes) +# provisioned before LBaaS resources are provisioned for tenants. +# +# WARNING: setting this mode to True will override +# the use_namespaces, setting it to False, because only +# one global routing space will used on the BIG-IP. This +# means overlapping IP addresses between tenants is no +# longer supported. +# +# WARNING: setting this mode to True will override +# the f5_snat_mode, setting it to True, because pool members +# will never be considered L2 adjacent to the BIG-IP by +# the agent. All member access will be via L3 routing, which +# will need to be set up on the BIG-IP before LBaaS provisions +# resources on behalf of tenants. +# +# WARNING: setting this mode to True will override the +# f5_snat_addresses_per_subnet, setting it to 0 (zero). +# This will force all VIPs to use AutoMap SNAT for which +# enough Self IP will need to be pre-provisioned on the +# BIG-IP to handle all pool member connections. The SNAT, +# an L3 mechanism, will all be global without reference +# to any specific tenant SNAT pool. +# +# WARNING: setting this mode will make the VIPs listen +# on all provisioned L2 segments (All VLANs). This is +# because no L2 information will be taken from +# neutron, thus making the assumption that all VIP +# L3 addresses will be globally routable without +# segmentation at L2 on the BIG-IP. +# +f5_global_routed_mode = False +# +# Allow overlapping IP subnets across multiple tenants. +# This creates route domains on BIG-IP in order to +# separate the tenant networks. +# +# This setting is forced to False if +# f5_global_routed_mode = True. +# +use_namespaces = True +# +# When use_namespaces is True there is normally only one route table +# allocated per tenant. However, this limit can be increased by +# changing the max_namespaces_per_tenant variable. This allows one +# tenant to have overlapping IP subnets. +# +# Supporting multiple IP namespaces allows establishing multiple independent +# IP routing topologies within one tenant project, which, for example, +# can accomodate multiple testing environments in one project, with +# each testing environment configured to use the same IP address +# topology as each other test environment. +# +# From a practical point of view, allowing multiple IP namespaces +# per tenant results in a more complicated configuration scheme +# for big-ip and also allows a single tenant to consumes more +# routing tables, which are a limited resource. In order to keep +# a simple one-to-one strategy of one tenant to one route domain, +# it is recommended that separate projects be used if possible to +# establish a new routing namespace rather than allowing multiple route +# domains within one tenant. +# +# If a tenant attempts to use a subnet that overlaps with an existing +# subnet that is already in use in the existing route domain(s), and +# this setting is not high enough to accomodate a new route domain to +# handle the new subnet, then the relevant lbaas element (vip or pool member) +# will be set to the error state. +# +max_namespaces_per_tenant = 1 +# +# Dictates the strict isolation of the routing +# tables. If you set this to True, then all +# VIPs and Members must be in the same tenant +# or else they can't communicate. +# +# This setting is only valid if use_namespaces = True. +# +f5_route_domain_strictness = False +# +# SNAT Mode and SNAT Address Counts +# +# This setting will force the use of SNATs. +# +# If this is set to False, a SNAT will not +# be created (routed mode) and the BIG-IP +# will attempt to set up a floating self IP +# as the subnet's default gateway address. +# and a wild card IP forwarding virtual +# server will be set up on member's network. +# Setting this to False will mean Neutron +# floating self IPs will not longer work +# if the same BIG-IP device is not being used +# as the Neutron Router implementation. +# +# This setting will be forced to True if +# f5_global_routed_mode = True. +# +f5_snat_mode = True +# +# This setting will specify the number of snat +# addresses to put in a snat pool for each +# subnet associated with a created local Self IP. +# +# Setting to 0 (zero) will set VIPs to AutoMap +# SNAT and the device's local Self IP will +# be used to SNAT traffic. +# +# In scalen HA mode, this is the number of snat +# addresses per active traffic-group at the time +# a service is provisioned. +# +# This setting will be forced to 0 (zero) if +# f5_global_routed_mode = True. +# +f5_snat_addresses_per_subnet = 1 +# +# This setting will cause all networks with +# the router:external attribute set to True +# to be created in the Common partition and +# placed in route domain 0. +f5_common_external_networks = True +# +# +# Common Networks +# +# This setting contains a name value pair comma +# separated list where if the name is a neutron +# network id used for a vip or a pool member, +# the network should not be created or deleted +# on the BIG-IP, but rather assumed that the value +# is the name of the network already created in +# the Common partition with all L3 addresses +# assigned to route domain 0. This is useful +# for shared networks which are already defined +# on the BIG-IP prior to LBaaS configuration. The +# network should not be managed by the LBaaS agent, +# but can be used for VIPs or pool members +# +# If your Internet VLAN on your BIG-IP is named +# /Common/external, and that corresponds to +# Neutron uuid: 71718972-78e2-449e-bb56-ce47cc9d2680 +# then the entry would look like: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external +# +# If you had multiple common networks, they are simply +# comma separated like this example: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external,396e06a0-05c7-4a49-8e86-04bb83d14438:vlan1222 +# +# The default is no common networks defined +# +# L3 Bindings +# +# Some systems require the need to bind L3 addresses +# to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# untagged VLANs and is a nova guest instance. By +# default, neutron will attempt to apply security rule +# for anti-spoofing which will not allow just any L3 +# address to be used on the neutron port. The answer is to +# use allowed-address-pairs for the neutron port. +# +# What is required is a software hook which allows the binding. +# l3_binding_driver needs to reference a subclass of the L3BindingBase +# class and provides the methods to bind and unbind L3 address +# to ports. +# +# l3_binding_driver = f5_openstack_agent.lbaasv2.drivers.bigip.l3_binding.AllowedAddressPairs +# +# The l3_binding_static_mappings allows for a JSON encoded dictionary +# mapping neutron subnet ids to lists of L2 ports and devices which +# require mapping. The entries for port and device mappings +# vary between providers. They may look like a neutron port id +# and a nova guest instance id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM MAC addresses will be collected +# and neutron will be queried to see if the MAC addresses +# correspond to known neutron ports. If they do, automatic entries +# for all mapped fixed_ips will be made referencing the ports id +# and the ports device_id. +# +# l3_binding_static_mappings = 'subnet_a':[('port_a','device_a'),('port_b','device_b')], 'subnet_b':[('port_c','device_a'),('port_d','device_b')] +# +# +# +############################################################################### +# Device Driver Setting +############################################################################### +# +f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol_driver.iControlDriver +# +# +############################################################################### +# Device Driver - iControl Driver Setting +############################################################################### +# +# icontrol_hostname is valid for external device type only. +# this setting can be either a single IP address or a +# comma separated list contain all devices in a device +# service group. For guest devices, the first fixed_address +# on the first device interfaces will be used. +# +# If a single IP address is used and the HA model +# is not standalone, all devices in the sync failover +# device group for the hostname specified must have +# their management IP address reachable to the agent. +# If order to access devices' iControl interfaces via +# self IPs, you should specify them as a comma +# separated list below. +# +icontrol_hostname = 10.190.0.0 +# +# If you are using vCMP with VLANs, you will need to configure +# your vCMP host addresses, in addition to the guests addresses. +# vCMP Host access is necessary for provisioning VLANs to a guest. +# Use icontrol_hostname for vCMP guests and icontrol_vcmp_hostname +# for vCMP hosts. The plug-in will automatically determine +# which host corresponds to each guest. +# +# icontrol_vcmp_hostname = 192.168.1.245 +# +# icontrol_username must be a valid Administrator username +# on all devices in a device sync failover group. +# +icontrol_username = admin +# +# icontrol_password must be a valid Administrator password +# on all devices in a device sync failover group. +# +icontrol_password = admin +# +############################################################################### +# Certificate Manager +############################################################################### +#cert_manager = f5_openstack_agent.lbaasv2.drivers.bigip.barbican_cert.BarbicanCertManager +# +# Two authentication modes are supported for BarbicanCertManager: +# keystone_v2, and keystone_v3 +# +# +# Keystone v2 authentication: +# +# auth_version = v2 +# os_auth_url = http://localhost:5000/v2.0 +# os_username = admin +# os_password = changeme +# os_tenant_name = admin +# +# +# Keystone v3 authentication: +# +#auth_version = v3 +#os_auth_url = http://localhost:5000/v3 +#os_username = admin +#os_password = changeme +#os_user_domain_name = default +#os_project_name = admin +#os_project_domain_name = default +# +# +# Parent SSL profile name +# +# A client SSL profile is created for LBaaS listeners that use TERMINATED_HTTPS +# protocol. You can define the parent profile for this profile by setting +# f5_parent_ssl_profile. The profile created to support TERMINATTED_HTTPS will +# inherit settings from the parent you define. This must be an existing profile, +# and if it does not exist on your BIG-IP system the agent will use the default +# profile, clientssl. +#f5_parent_ssl_profile = clientssl +# diff --git a/docs/_static/config_examples/f5-openstack-agent.vxlan.ini b/docs/_static/config_examples/f5-openstack-agent.vxlan.ini new file mode 100644 index 000000000..328104056 --- /dev/null +++ b/docs/_static/config_examples/f5-openstack-agent.vxlan.ini @@ -0,0 +1,536 @@ +############################################################################### +# Copyright 2015-2017 F5 Networks Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +############################################################################### +# +# ############ +# ################ +# ###/ _ \###| |# +# ###| |#| |##| |###### +# ####| |######| |###### +# ##| |####\ \### AGILITY YOUR WAY! +# ####| |#########| |### +# ####| |#########| |## +# ###| |########/ /## +# #| |####| /## +# ############## +# ########### +# +# NETWORKS +# +############################################################################### +# +[DEFAULT] +# Show debugging output in log (sets DEBUG log level output). +debug = True +# The LBaaS agent will resync its state with Neutron to recover from any +# transient notification or rpc errors. The interval is number of +# seconds between attempts. +# +periodic_interval = 10 +# +# How often should the agent throw away its service cache and +# resync assigned services with the neutron LBaaS plugin. +# +# service_resync_interval = 500 +# +# Objects created on the BIG-IP by this agent will have their names prefixed +# by an environment string. This allows you set this string. The default is +# 'project'. +# +# WARNING - you should only set this before creating any objects. If you change +# it with established objects, the objects created with an alternative prefix, +# will no longer be associated with this agent and all objects in neutron +# and on the the BIG-IP associated with the old environment will need to be managed +# manually. +# +############################################################################### +# Environment Settings +############################################################################### +# +# Since many TMOS object names must start with an alpha character +# the environment_prefix is used to prefix all service objects. +# +# environment_prefix = 'Project' +# +############################################################################### +# Static Agent Configuration Setting +############################################################################### +# +# Static configuration data to sent back to the plugin. This can be used +# on the plugin side of neutron to provide agent identification for custom +# pool to agent scheduling. This should be a single or comma separated list +# of name:value entries which will be sent in the agent's configuration +# dictionary to neutron. +# +# static_agent_configuration_data = location:DFW1_R122_U9, service_contract:8675309, contact:jenny +# +############################################################################### +# Device Setting +############################################################################### +# +# HA mode +# +# Device can be required to be: +# +# standalone - single device no HA +# pair - active/standby two device HA +# scalen - active device cluster +# +# If the device is external, the devices must be onboarded for the +# appropriate HA mode or else the driver will not provision devices +# +f5_ha_type = standalone +# +# +############################################################################### +# L2 Segmentation Mode Settings +############################################################################### +# +# Device VLAN to interface and tag mapping +# +# For pools or VIPs created on networks with type VLAN we will map +# the VLAN to a particular interface and state if the VLAN tagging +# should be enforced by the external device or not. This setting +# is a comma separated list of the following format: +# +# physical_network:interface_name:tagged, physical:interface_name:tagged +# +# where : +# physical_network corresponds to provider:physical_network attributes +# interface_name is the name of an interface or LAG trunk +# tagged is a boolean (True or False) +# +# If a network does not have a provider:physical_network attribute, +# or the provider:physical_network attribute does not match in the +# configured list, the 'default' physical_network setting will be +# applied. At a minimum you must have a 'default' physical_network +# setting. +# +# standalone example: +# f5_external_physical_mappings = default:1.1:True +# +# pair or scalen (1.1 and 1.2 are used for HA purposes): +# f5_external_physical_mappings = default:1.3:True +# +f5_external_physical_mappings = default:1.1:True +# +# VLAN device and interface to port mappings +# +# Some systems require the need to bind and prune VLANs ids +# allowed to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# tagged VLANs. When a VLAN tagged network is added to a +# specific BIG-IP device, the facing switch port will need +# to allow traffic for that VLAN tag through to the BIG-IP's +# port for traffic to flow. +# +# What is required is a software hook which allows the binding. +# A vlan_binding_driver class needs to reference a subclass of the +# VLANBindingBase class and provides the methods to bind and prune +# VLAN tags to ports. +# +# vlan_binding_driver = f5.oslbaasv1agent.drivers.bigip.vlan_binding.NullBinding +# +# The interface_port_static_mappings allows for a JSON encoded dictionary +# mapping BigIP devices and interfaces to corresponding ports. A port id can be +# any string which is meaningful to a vlan_binding_driver. It can be a +# switch_id and port, or it might be a neutron port_id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM interfaces will be collect +# for each device and neutron will be queried to see if which +# device port_ids correspond to known neutron ports. If they do, +# automatic entries for all mapped port_ids will be made referencing +# the BIG-IP device name and interface and the neutron port_ids. +# +# interface_port_static_mappings = {"device_name_1":{"interface_ida":"port_ida","interface_idb":"port_idb"}, {"device_name_2":{"interface_ida":"port_ida","interface_idb":"port_idb"}} +# +# example: +# +# interface_port_static_mappings = {"bigip1":{"1.1":"switch1:g2/32","1.2":"switch1:g2/33"},"bigip2":{"1.1":"switch1:g3/32","1.2":"switch1:g3/33"}} +# +# Device Tunneling (VTEP) selfips +# +# This is a single entry or comma separated list of cidr (h/m) format +# selfip addresses, one per BIG-IP device, to use for VTEP addresses. +# +# If no gre or vxlan tunneling is required, these settings should be +# commented out or set to None. +# +f5_vtep_folder = Common +f5_vtep_selfip_name = vtep +# +# +# +# Tunnel types +# +# This is a comma separated list of tunnel types to report +# as available from this agent as well as to send via tunnel_sync +# rpc messages to compute nodes. This should match your ml2 +# network types on your compute nodes. +# +# If you are using only gre tunnels it should be: +# +# advertised_tunnel_types = gre +# +# If you are using only vxlan tunnels it should be: +# +advertised_tunnel_types = vxlan +# +# If this agent could get both gre and vxlan tunnel networks: +# +# advertised_tunnel_types = gre,vxlan +# +# If you are using only vlans only it should be: +# +# advertised_tunnel_types = +# +# Static ARP population for members on tunnel networks +# +# This is a boolean True or False value which specifies +# that if a Pool Member IP address is associated with a gre +# or vxlan tunnel network, in addition to a tunnel fdb +# record being added, that a static arp entry will be created to +# avoid the need to learn the member's MAC address via flooding. +# +# f5_populate_static_arp = True +# +# Device Tunneling (VTEP) selfips +# +# This is a boolean entry which determines if they BIG-IP will use +# L2 Population service to update its fdb tunnel entries. This needs +# to be setup in accordance with the way the other tunnel agents are +# setup. If the BIG-IP agent and other tunnel agents don't match +# the tunnel setup will not work properly. +# +l2_population = True +# +# Hierarchical Port Binding +# +# If hierarchical networking is not required, these settings must be commented +# out or set to None. +# +# Restrict discovery of network segmentation ID to a specific physical network +# name. +# +# f5_network_segment_physical_network = +# +# Periodically scan for disconected listeners (a.k.a virtual servers). The +# interval is number of seconds between attempts. +# +# f5_network_segment_polling_interval = 10 +# +# Maximum amount of time in seconds for wait for a network to become connected. +# DEPECATED: This value is no longer used because the greenthread that used it +# for the Hierarchical Port Binding feature was removed. Please use: +# f5_pending_services_timeout. +# f5_network_segment_gross_timeout = 300 +# +# Maximum amount of time in seconds before a pending service gets moved into +# error state. Polling spacing is 10 seconds which is not yet configurable. +# +# f5_pending_services_timeout = 60 +# +############################################################################### +# L3 Segmentation Mode Settings +############################################################################### +# +# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP +# +# This setting will cause the agent to assume that all VIPs +# and pool members will be reachable via global device +# L3 routes, which must be already provisioned on the BIG-IPs. +# +# In f5_global_routed_mode, BIG-IP will not assume L2 +# adjacentcy to any neutron network, therefore no +# L2 segementation between tenant services in the data plane +# will be provisioned by the agent. Because the routing +# is global, no L3 self IPs or SNATs will be provisioned +# by the agent on behalf of tenants either. You must have +# all necessary L3 routes (including TMM default routes) +# provisioned before LBaaS resources are provisioned for tenants. +# +# WARNING: setting this mode to True will override +# the use_namespaces, setting it to False, because only +# one global routing space will used on the BIG-IP. This +# means overlapping IP addresses between tenants is no +# longer supported. +# +# WARNING: setting this mode to True will override +# the f5_snat_mode, setting it to True, because pool members +# will never be considered L2 adjacent to the BIG-IP by +# the agent. All member access will be via L3 routing, which +# will need to be set up on the BIG-IP before LBaaS provisions +# resources on behalf of tenants. +# +# WARNING: setting this mode to True will override the +# f5_snat_addresses_per_subnet, setting it to 0 (zero). +# This will force all VIPs to use AutoMap SNAT for which +# enough Self IP will need to be pre-provisioned on the +# BIG-IP to handle all pool member connections. The SNAT, +# an L3 mechanism, will all be global without reference +# to any specific tenant SNAT pool. +# +# WARNING: setting this mode will make the VIPs listen +# on all provisioned L2 segments (All VLANs). This is +# because no L2 information will be taken from +# neutron, thus making the assumption that all VIP +# L3 addresses will be globally routable without +# segmentation at L2 on the BIG-IP. +# +f5_global_routed_mode = False +# +# Allow overlapping IP subnets across multiple tenants. +# This creates route domains on BIG-IP in order to +# separate the tenant networks. +# +# This setting is forced to False if +# f5_global_routed_mode = True. +# +use_namespaces = True +# +# When use_namespaces is True there is normally only one route table +# allocated per tenant. However, this limit can be increased by +# changing the max_namespaces_per_tenant variable. This allows one +# tenant to have overlapping IP subnets. +# +# Supporting multiple IP namespaces allows establishing multiple independent +# IP routing topologies within one tenant project, which, for example, +# can accomodate multiple testing environments in one project, with +# each testing environment configured to use the same IP address +# topology as each other test environment. +# +# From a practical point of view, allowing multiple IP namespaces +# per tenant results in a more complicated configuration scheme +# for big-ip and also allows a single tenant to consumes more +# routing tables, which are a limited resource. In order to keep +# a simple one-to-one strategy of one tenant to one route domain, +# it is recommended that separate projects be used if possible to +# establish a new routing namespace rather than allowing multiple route +# domains within one tenant. +# +# If a tenant attempts to use a subnet that overlaps with an existing +# subnet that is already in use in the existing route domain(s), and +# this setting is not high enough to accomodate a new route domain to +# handle the new subnet, then the relevant lbaas element (vip or pool member) +# will be set to the error state. +# +max_namespaces_per_tenant = 1 +# +# Dictates the strict isolation of the routing +# tables. If you set this to True, then all +# VIPs and Members must be in the same tenant +# or else they can't communicate. +# +# This setting is only valid if use_namespaces = True. +# +f5_route_domain_strictness = False +# +# SNAT Mode and SNAT Address Counts +# +# This setting will force the use of SNATs. +# +# If this is set to False, a SNAT will not +# be created (routed mode) and the BIG-IP +# will attempt to set up a floating self IP +# as the subnet's default gateway address. +# and a wild card IP forwarding virtual +# server will be set up on member's network. +# Setting this to False will mean Neutron +# floating self IPs will not longer work +# if the same BIG-IP device is not being used +# as the Neutron Router implementation. +# +# This setting will be forced to True if +# f5_global_routed_mode = True. +# +f5_snat_mode = True +# +# This setting will specify the number of snat +# addresses to put in a snat pool for each +# subnet associated with a created local Self IP. +# +# Setting to 0 (zero) will set VIPs to AutoMap +# SNAT and the device's local Self IP will +# be used to SNAT traffic. +# +# In scalen HA mode, this is the number of snat +# addresses per active traffic-group at the time +# a service is provisioned. +# +# This setting will be forced to 0 (zero) if +# f5_global_routed_mode = True. +# +f5_snat_addresses_per_subnet = 1 +# +# This setting will cause all networks with +# the router:external attribute set to True +# to be created in the Common partition and +# placed in route domain 0. +f5_common_external_networks = True +# +# +# Common Networks +# +# This setting contains a name value pair comma +# separated list where if the name is a neutron +# network id used for a vip or a pool member, +# the network should not be created or deleted +# on the BIG-IP, but rather assumed that the value +# is the name of the network already created in +# the Common partition with all L3 addresses +# assigned to route domain 0. This is useful +# for shared networks which are already defined +# on the BIG-IP prior to LBaaS configuration. The +# network should not be managed by the LBaaS agent, +# but can be used for VIPs or pool members +# +# If your Internet VLAN on your BIG-IP is named +# /Common/external, and that corresponds to +# Neutron uuid: 71718972-78e2-449e-bb56-ce47cc9d2680 +# then the entry would look like: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external +# +# If you had multiple common networks, they are simply +# comma separated like this example: +# +# common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external,396e06a0-05c7-4a49-8e86-04bb83d14438:vlan1222 +# +# The default is no common networks defined +# +# L3 Bindings +# +# Some systems require the need to bind L3 addresses +# to specific ports, often for security. +# +# An example would be if a LBaaS iControl endpoint is using +# untagged VLANs and is a nova guest instance. By +# default, neutron will attempt to apply security rule +# for anti-spoofing which will not allow just any L3 +# address to be used on the neutron port. The answer is to +# use allowed-address-pairs for the neutron port. +# +# What is required is a software hook which allows the binding. +# l3_binding_driver needs to reference a subclass of the L3BindingBase +# class and provides the methods to bind and unbind L3 address +# to ports. +# +# l3_binding_driver = f5_openstack_agent.lbaasv2.drivers.bigip.l3_binding.AllowedAddressPairs +# +# The l3_binding_static_mappings allows for a JSON encoded dictionary +# mapping neutron subnet ids to lists of L2 ports and devices which +# require mapping. The entries for port and device mappings +# vary between providers. They may look like a neutron port id +# and a nova guest instance id. +# +# In addition to any static mappings, when the iControl endpoints +# are initialized, all their TMM MAC addresses will be collected +# and neutron will be queried to see if the MAC addresses +# correspond to known neutron ports. If they do, automatic entries +# for all mapped fixed_ips will be made referencing the ports id +# and the ports device_id. +# +# l3_binding_static_mappings = 'subnet_a':[('port_a','device_a'),('port_b','device_b')], 'subnet_b':[('port_c','device_a'),('port_d','device_b')] +# +# +# +############################################################################### +# Device Driver Setting +############################################################################### +# +f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol_driver.iControlDriver +# +# +############################################################################### +# Device Driver - iControl Driver Setting +############################################################################### +# +# icontrol_hostname is valid for external device type only. +# this setting can be either a single IP address or a +# comma separated list contain all devices in a device +# service group. For guest devices, the first fixed_address +# on the first device interfaces will be used. +# +# If a single IP address is used and the HA model +# is not standalone, all devices in the sync failover +# device group for the hostname specified must have +# their management IP address reachable to the agent. +# If order to access devices' iControl interfaces via +# self IPs, you should specify them as a comma +# separated list below. +# +icontrol_hostname = 10.190.0.0 +# +# If you are using vCMP with VLANs, you will need to configure +# your vCMP host addresses, in addition to the guests addresses. +# vCMP Host access is necessary for provisioning VLANs to a guest. +# Use icontrol_hostname for vCMP guests and icontrol_vcmp_hostname +# for vCMP hosts. The plug-in will automatically determine +# which host corresponds to each guest. +# +# icontrol_vcmp_hostname = 192.168.1.245 +# +# icontrol_username must be a valid Administrator username +# on all devices in a device sync failover group. +# +icontrol_username = admin +# +# icontrol_password must be a valid Administrator password +# on all devices in a device sync failover group. +# +icontrol_password = admin +# +############################################################################### +# Certificate Manager +############################################################################### +#cert_manager = f5_openstack_agent.lbaasv2.drivers.bigip.barbican_cert.BarbicanCertManager +# +# Two authentication modes are supported for BarbicanCertManager: +# keystone_v2, and keystone_v3 +# +# +# Keystone v2 authentication: +# +# auth_version = v2 +# os_auth_url = http://localhost:5000/v2.0 +# os_username = admin +# os_password = changeme +# os_tenant_name = admin +# +# +# Keystone v3 authentication: +# +#auth_version = v3 +#os_auth_url = http://localhost:5000/v3 +#os_username = admin +#os_password = changeme +#os_user_domain_name = default +#os_project_name = admin +#os_project_domain_name = default +# +# +# Parent SSL profile name +# +# A client SSL profile is created for LBaaS listeners that use TERMINATED_HTTPS +# protocol. You can define the parent profile for this profile by setting +# f5_parent_ssl_profile. The profile created to support TERMINATTED_HTTPS will +# inherit settings from the parent you define. This must be an existing profile, +# and if it does not exist on your BIG-IP system the agent will use the default +# profile, clientssl. +#f5_parent_ssl_profile = clientssl +# diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css deleted file mode 100644 index 6cf67ac4e..000000000 --- a/docs/_static/css/custom.css +++ /dev/null @@ -1,246 +0,0 @@ -/* - * Copyright 2017 F5 Networks - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* - * Base structure - */ - -body { - padding-top: 0px; -} - -/* Header paragraph links */ -a.headerlink { - color: #EBEBEB; -} - -a.headerlink:hover { - color: #0083c0; -} - -/* - * Global add-ons - */ - -.sub-header { - padding-bottom: 10px; - border-bottom: 1px solid #eee; -} - -/* - * Top navigation - * Hide default border to remove 1px line. - */ -.navbar-fixed-top { - border: 0; -} - -/* - * Sidebar - */ - -form.search { - margin-left: 0px; -} - -.sidebar { - left: 0; - height: 100%; - background-color: #EBEBEB; - font-size: 14px; - z-index: 0; -} - -.sidebar ul { - padding-left: 15px; -} - -/* Hide for mobile, show later */ -.sidebar { - display: none; -} -@media (min-width: 768px) { - .sidebar { - /* top: 126px; */ - border-bottom-right-radius: 6px; - border-bottom: 1px #4D4F53 solid; - border-right: 1px #4D4F53 solid; - bottom: 0; - left: 0; - display: block; - padding: 20px; - overflow-x: hidden; - overflow-y: auto; /* Scrollable contents if viewport is shorter than content. */ - } -} - -/* Sidebar navigation */ -.nav-sidebar { - margin-right: -21px; /* 20px padding + 1px border */ - margin-bottom: 20px; - margin-left: -20px; -} -.nav-sidebar > li > a { - padding-right: 20px; - padding-left: 20px; -} -.nav-sidebar > .active > a, -.nav-sidebar > .active > a:hover, -.nav-sidebar > .active > a:focus { - color: #fff; - background-color: #428bca; -} - -/* Sidebar Search */ -form.search { - margin: 6px; - padding-bottom: 6px; -} - -.search .btn-primary { - border-radius: 4px; -} -/* - * Main content - */ - -.main { - padding: 20px; -} -@media (min-width: 768px) { - .main { - padding-right: 40px; - padding-left: 40px; - } -} -.main .page-header { - margin-top: 0; -} - -/* -* Panels for Tip, See also, Note etc -*/ - - -.admonition { - border-radius: 4px; - background-color: white; - margin-bottom: 20px; -} - -ul.last { - margin-left: 26px; -} - -/* Yellow: Caution, Warning */ -.caution, .warning { - border: 1px #faebcc solid; -} - -.caution>.admonition-title, -.warning>.admonition-title { - background-color: #fcf8e3; - color: #8a6d3b; - padding: 6px; -} - -.caution>.last, .warning>.last { - padding: 6px; -} - -/* Red: danger, error */ -.danger, .error { - border: 1px #ebccd1 solid; -} - -.danger>.admonition-title, .error>.admonition-title { - background-color: #f2dede; - color: #a94442; - padding: 6px; -} - -.danger>.last, .error>.last { - padding: 6px; -} - -/* Orange: attention */ - -.attention { - border: 1px #ebb96f solid; -} - -.attention>.admonition-title { - background-color: #d39017; - color: #ffffff; - padding: 6px; -} - -.attention>.last { - padding: 6px; -} - -/* Green */ -.hint { - border: 1px #d6e9c6 solid; -} - -.hint>.admonition-title { - background-color: #dff0d8; - color: #3c763d; - padding: 6px; -} - -.hint>.last { - padding: 6px; -} - -/* Lt. Blue */ -.tip, .note { - border: 1px #bce8f1 solid; -} - -.tip>.admonition-title, .note>.admonition-title { - background-color: #D9EDF8; - color: #31708f; - padding: 6px; -} - -.tip>.last, .note>.last { - padding: 6px; -} - -/* Blue */ -.important, .seealso { - border: 1px #337ab7 solid; -} - -.important>.admonition-title, .seealso>.admonition-title { - color: #fff; - background-color: #337ab7; - padding: 6px; -} - -.important>.last, .seealso>.last { - padding: 6px; -} - -/* - * Tables - */ - -th, td { - padding: 4px; -} diff --git a/docs/_static/media/big-ip_undercloud.png b/docs/_static/media/big-ip_undercloud.png new file mode 100644 index 000000000..8bcc0a9fd Binary files /dev/null and b/docs/_static/media/big-ip_undercloud.png differ diff --git a/docs/_static/media/f5-lbaas-global-routed-mode.png b/docs/_static/media/f5-lbaas-global-routed-mode.png new file mode 100644 index 000000000..acfc19522 Binary files /dev/null and b/docs/_static/media/f5-lbaas-global-routed-mode.png differ diff --git a/docs/_static/media/f5-lbaas-ha-active-standby-pair.png b/docs/_static/media/f5-lbaas-ha-active-standby-pair.png new file mode 100644 index 000000000..08402f886 Binary files /dev/null and b/docs/_static/media/f5-lbaas-ha-active-standby-pair.png differ diff --git a/docs/_static/media/f5-lbaas-l2-3-adjacent-mode.png b/docs/_static/media/f5-lbaas-l2-3-adjacent-mode.png new file mode 100644 index 000000000..f69b71e66 Binary files /dev/null and b/docs/_static/media/f5-lbaas-l2-3-adjacent-mode.png differ diff --git a/docs/_static/reuse/edit-agent-config-file.rst b/docs/_static/reuse/edit-agent-config-file.rst new file mode 100644 index 000000000..a0d9c823c --- /dev/null +++ b/docs/_static/reuse/edit-agent-config-file.rst @@ -0,0 +1,7 @@ +#. Edit the F5 Agent Configuration File + + Use your text editor of choice to edit the :ref:`F5 Agent Configuration File` as appropriate for your environment. + +.. code-block:: console + + vim /etc/neutron/services/f5/f5-openstack-agent.ini diff --git a/docs/_static/reuse/ref_agent-config-file.rst b/docs/_static/reuse/ref_agent-config-file.rst new file mode 100644 index 000000000..8ea78947f --- /dev/null +++ b/docs/_static/reuse/ref_agent-config-file.rst @@ -0,0 +1,3 @@ +.. _agent-config-file-example: + +.. literalinclude:: /../etc/neutron/services/f5/f5-openstack-agent.ini diff --git a/docs/_templates/header.html b/docs/_templates/header.html deleted file mode 100644 index e6694b9d3..000000000 --- a/docs/_templates/header.html +++ /dev/null @@ -1,137 +0,0 @@ - diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index 7cd6e0bc2..000000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,34 +0,0 @@ -{% extends "f5_sphinx_theme/layout.html" %} -{% block content %} -
-
-
-

{{ project }} {{ release }}

- {%- if sidebars != None %} - {%- for sidebartemplate in sidebars %} - {%- include sidebartemplate %} - {%- endfor %} - {% endif %} -
-
-

- {{ theme_site_name|striptags|e }} > {{ project|striptags|e }} - Index -

- {% block body %}{% endblock %} - {% if (next or prev) and theme_next_prev_link%} - - {% if prev %} - - {% endif %} - {% if next %} - - {% endif %} -
<< PreviousNext >>
-
- {% endif %} -
-
-
- -{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 41ae46e10..c6c7d4f17 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# F5 OpenStack Agent documentation build configuration file, created by +# F5 Agent for OpenStack Neutron documentation build configuration file, created by # sphinx-quickstart on Tue May 24 09:31:49 2016. # # This file is execfile()d with the current directory set to its @@ -30,7 +30,7 @@ # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.4' +#needs_sphinx = '1.4' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -42,7 +42,8 @@ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', - 'sphinx.ext.autosectionlabel', + 'cloud_sptheme.ext.table_styling', + 'sphinxjp.themes.basicstrap', ] # Add any paths that contain templates here, relative to this directory. @@ -60,7 +61,7 @@ master_doc = 'index' # General information about the project. -project = u'F5 OpenStack Agent' +project = u'F5 Agent for OpenStack Neutron' copyright = u'2017 F5 Networks' author = u'F5 Networks' @@ -78,19 +79,12 @@ # F5 icontrol REST version should be set here f5_icontrol_version = '1.3.0' -rst_prolog = ''' -.. attention:: - - **The F5 OpenStack Integrations documentation is moving to - clouddocs.f5.com. Thank you for your patience during construction.** -''' +#rst_prolog = ''' +#''' # OpenStack release openstack_release = "Mitaka" -rst_epilog = """ -.. |openstack| replace:: {0} -""".format(openstack_release) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -108,7 +102,15 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', + 'Thumbs.db', + '.DS_Store', + 'README.rst', + 'drafts/', + '_static/reuse', + ] + +suppress_warnings = ['image.nonlocal_uri'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -150,12 +152,12 @@ # documentation. html_theme_options = { #'site_name': 'F5 OpenStack Docs Home', - 'next_prev_link': True + 'next_prev_link': False } # The name for this set of Sphinx documents. # " v documentation" by default. -html_title = u'F5 OpenStack Agent' +html_title = u'F5 Agent for OpenStack Neutron' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -237,7 +239,7 @@ #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'F5OpenStackAgentdoc' +htmlhelp_basename = 'F5-OpenStack-BIG-IP-Controllerdoc' # -- Options for LaTeX output --------------------------------------------- @@ -259,7 +261,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'F5OpenStackAgent.tex', u'F5 OpenStack Agent Documentation', + (master_doc, 'F5-OpenStack-BIG-IP-Controller.tex', u'F5 Agent for OpenStack Neutron Documentation', u'F5 Networks', 'manual'), ] @@ -289,8 +291,11 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'f5openstackagent', u'F5 OpenStack Agent Documentation', - [author], 1) + (master_doc, + 'f5-openstack-agent', + u'F5 Agent for OpenStack Neutron Documentation', + [author], + 1) ] # If true, show URL addresses after external links. @@ -303,9 +308,11 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'F5OpenStackAgent', u'F5 OpenStack Agent Documentation', - author, 'F5OpenStackAgent', 'One line description of project.', - 'Miscellaneous'), + (master_doc, 'f5-openstack-agent', + u'F5 Agent for OpenStack Neutron Documentation', + [author], + 'f5-openstack-agent', + 'manual'), ] # Documents to append as an appendix to all manuals. @@ -315,28 +322,35 @@ #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False # intersphinx: refer to other F5 OpenStack documentation sets. -intersphinx_mapping = {'heat': ( - 'http://f5-openstack-heat.readthedocs.io/en/'+openstack_release.lower(), None), - 'heatplugins': ( - 'http://f5-openstack-heat-plugins.readthedocs.io/en/'+openstack_release.lower(), None), - 'lbaasv1': ( - 'http://f5-openstack-lbaasv1.readthedocs.io/en/'+openstack_release.lower(), None), - 'lbaasv2driver': ( - 'http://f5-openstack-lbaasv2-driver.readthedocs.io/en/'+openstack_release.lower(), None), - 'f5sdk': ( - 'http://f5-sdk.readthedocs.io/en/latest/', None), - } +#intersphinx_mapping = {'heat': ( +# 'http://f5-openstack-heat.readthedocs.io/en/'+openstack_release.lower( +# ), None), +# 'heatplugins': ( +# 'http://f5-openstack-heat-plugins.readthedocs.io/en/'+openstack_release +# .lower(), None), +# 'lbaasv1': ( +# 'http://f5-openstack-lbaasv1.readthedocs.io/en/'+openstack_release +# .lower(), None), +# 'lbaasv2driver': ( +# 'http://f5-openstack-lbaasv2-driver.readthedocs.io/en +# /'+openstack_release.lower(), None), +# 'f5sdk': ( +# 'http://f5-sdk.readthedocs.io/en/latest/', None), +# 'osdocs': ( +# 'http://clouddocs.f5.com/cloud/openstack/latest/', None), +# } rst_epilog = ''' .. |openstack| replace:: %(openstack_release)s .. |f5_agent_pip_url| replace:: git+https://github.com/F5Networks/f5-openstack-agent@v%(version)s +.. |f5_agent_pip_url_branch| replace:: git+https://github.com/F5Networks/f5-openstack-agent@%(openstack_release_l)s .. |f5_agent_deb_url| replace:: https://github.com/F5Networks/f5-openstack-agent/releases/download/v%(version)s/python-f5-openstack-agent_%(version)s-1_1404_all.deb .. |f5_agent_rpm_url| replace:: https://github.com/F5Networks/f5-openstack-agent/releases/download/v%(version)s/f5-openstack-agent-%(version)s-1.el7.noarch.rpm .. |f5_agent_deb_package| replace:: python-f5-openstack-agent_%(version)s-1_1404_all.deb @@ -349,6 +363,33 @@ .. |f5_icontrol_rpm_url| replace:: https://github.com/F5Networks/f5-icontrol-rest-python/releases/download/v%(f5_icontrol_version)s/f5-icontrol-rest-%(f5_icontrol_version)s-1.el7.noarch.rpm .. |f5_icontrol_rpm_package| replace:: f5-icontrol-rest-%(f5_icontrol_version)s-1.el7.noarch.rpm .. |f5_icontrol_deb_package| replace:: python-f5-icontrol-rest_%(f5_icontrol_version)s-1_1404_all.deb +.. |agent-long| replace:: F5 Agent for OpenStack Neutron +.. |agent| replace:: :code:`f5-openstack-agent` +.. |agent-short| replace:: F5 agent +.. |driver| replace:: :code:`f5-openstack-lbaasv2-driver` +.. |driver-long| replace:: F5 Driver for OpenStack LBaaS +.. |driver-short| replace:: F5 driver +.. |deb-download| raw:: html + + Debian package +.. |rpm-download| raw:: html + + RPM package +.. |release-notes| raw:: html + + Release Notes +.. _Hierarchical Port Binding: /cloud/openstack/v1/lbaas/hierarchical-port-binding.html +.. _external provider network: https://docs.openstack.org/newton/networking-guide/intro-os-networking.html#provider-networks +.. _Cisco ACI: http://www.cisco.com/c/en/us/solutions/data-center-virtualization/application-centric-infrastructure/index.html +.. _system configuration: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/bigip-system-initial-configuration-13-0-0/2.html +.. _local traffic management: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/ltm-basics-13-0-0.html +.. _device service clustering: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/bigip-device-service-clustering-admin-13-0-0.html +.. _VTEP: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/bigip-tmos-tunnels-ipsec-13-0-0/3.html +.. _SNATs: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/8.html +.. _self IP: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/6.html +.. _Better or Best license: https://f5.com/products/how-to-buy/simplified-licensing +.. _secure network address translation: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/tmos-routing-administration-13-0-0/8.html +.. _F5 Integration for OpenStack: /cloud/openstack/latest/lbaas ''' % { 'version': version, 'f5_sdk_version': f5_sdk_version, diff --git a/docs/device-driver-settings.rst b/docs/device-driver-settings.rst new file mode 100644 index 000000000..e86b71933 --- /dev/null +++ b/docs/device-driver-settings.rst @@ -0,0 +1,56 @@ +.. _device-driver-settings: + +.. index:: + single: f5-openstack-agent; device driver settings + +.. index:: + single: f5-openstack-agent; iControl driver settings + +.. index:: + single: f5-openstack-agent; BIG-IP setup + +Device Driver Settings/iControl Driver Settings +=============================================== + +The Device Driver Settings in the :ref:`F5 Agent Configuration File` provide the means of communication between the |agent-long| and BIG-IP device(s). **Do not change this setting**. + +The iControl Driver Settings identify the BIG-IP device(s) that you want the |agent-short| to manage and record the login information the agent will use to communicate with the BIG-IP(s). + +If you want to use the |agent-long| to manage BIG-IP devices from within your OpenStack cloud, you **must** provide the correct information in this section of the agent config file. +The |agent-short| can manage a :term:`standalone` device or a :term:`device service cluster`. + +.. seealso:: + + `Manage BIG-IP Clusters with F5 LBaaSv2 `_ + + +Configuration +------------- + +.. include:: /_static/reuse/edit-agent-config-file.rst + +#. Enter the iControl endpoint(s), username, and password for your BIG-IP(s). + + * :code:`icontrol_hostname`: The IP address(es) of the BIG-IP(s) the agent will manage. If you're using multiple devices, provide a comma-separated list containing the management IP address of each device. + * :code:`icontrol_vcmp_hostname`: The IP address(es) of the BIG-IP device(s) used for `vCMP`_ + * :code:`icontrol_username`: The username of the adminstrative user; *must have access to all BIG-IP devices*. + * :code:`icontrol_password`: The password of the adminstrative user; *must have access to all BIG-IP devices*. + + .. code-block:: text + + ############################################################################### + # Device Driver - iControl Driver Setting + ############################################################################### + # + icontrol_hostname = 10.190.7.232 \\ replace with the IP address(es) of your BIG-IP(s) + # + # icontrol_vcmp_hostname = 192.168.1.245 + # + icontrol_username = admin + # + icontrol_password = admin + # + +#. Set up the |agent-long| to use :ref:`L2-adjacent mode ` or :ref:`Global Routed mode `. + +.. _vCMP: /cloud/openstack/v1/lbaas/lbaas-manage-vcmp.html diff --git a/docs/global-routed-mode.rst b/docs/global-routed-mode.rst new file mode 100644 index 000000000..f207db418 --- /dev/null +++ b/docs/global-routed-mode.rst @@ -0,0 +1,137 @@ +.. _global-routed-mode: + +.. index:: + single: f5-openstack-agent; global routed mode + +Global Routed mode +================== + +The |agent-long| :ref:`L2 segmentation mode settings ` and :ref:`L3 segmentation mode settings ` tell the |agent-short| about BIG-IP devices' L2 and L3 network configurations. + +:fonticon:`fa fa-chevron-right` :ref:`Learn more ` + +Caveats +------- + +- In global routed mode, the |agent-long| assumes that all L3 virtual IP addresses are globally routable. + This means that all virtual IPs listen on all VLANs accessible to the BIG-IP (in other words, there is no VLAN segmentation). +- Global routed mode uses the BIG-IP global route domain (``0``). + This precludes the use of overlapping subnets/IP addresses amongst tenants. + +Configuration +------------- + +.. include:: /_static/reuse/edit-agent-config-file.rst + +#. Set up the :ref:`Device driver settings ` and :ref:`HA mode `. + +#. Define the L2- and L3-segmentation settings for Global Routed Mode. + + .. table:: Global Routed Mode settings + + =================================== ============================================= + Setting Description + =================================== ============================================= + ``global_routed_mode`` Boolean; set to `True` to make all VIPs and + pool members globally routable + + ``use_namespaces`` Boolean; forced to `False` in global routed + mode. + + ``f5_snat_mode`` Boolean; forced to `True` in global routed + mode. + + Uses automap SNATs to allocate + self IP addresses for LBaaS objects. + + ``f5_snat_addresses_per_subnet`` Integer; forced to ``0`` in global routed + mode; the BIG-IP device's local + self IP is also the SNAT address. + + ``f5_common_external_networks`` Boolean; when `True`, the agent adds all + external Neutron networks to the global + routing table (the BIG-IP `/Common` + :term:`partition`) and route domain ``0``. + =================================== ============================================= + + .. code-block:: text + + ############################################################################### + # L3 Segmentation Mode Settings + ############################################################################### + # + # Global Routed Mode - No L2 or L3 Segmentation on BIG-IP + # + f5_global_routed_mode = True + # + use_namespaces = False + # + # SNAT Mode and SNAT Address Counts + # + f5_snat_mode = True + # + f5_snat_addresses_per_subnet = 0 + # + f5_common_external_networks = True + # + + :fonticon:`fa fa-download` :download:`Sample Global Routed Mode configuration file ` + +.. _learn-grm: + +Learn more +---------- + +In global routed mode (``f5_global_routed_mode=TRUE``), the |agent-long| assumes the following: + +- All LBaaS objects are accessible via global L3 routes. +- All virtual IPs are routable from clients. +- All pool members are routable from BIG-IP devices. + +All required L2 and L3 Network objects (including routes) must exist on your BIG-IP devices *before* you deploy the |agent-short| in OpenStack. + +.. figure:: /_static/media/f5-lbaas-global-routed-mode.png + :width: 60% + :alt: Global routed mode diagram shows a BIG-IP device cluster as part of an L3-routed network external to the OpenStack cloud. + + Global routed mode + +Use Case +-------- + +Global routed mode is generally used for :term:`undercloud` BIG-IP hardware deployments. +The BIG-IP device resides at the services tier in the `external provider network`_. + +.. figure:: /_static/media/big-ip_undercloud.png + :width: 60% + :alt: Undercloud deployment diagram shows two BIG-IP hardware devices in the service tier of an L3-routed network external to the OpenStack cloud. The F5 OpenStack LBaaS components reside on the Neutron controller in the application layer in the OpenStack cloud. + + BIG-IP "undercloud" deployment + +In global routed mode, the |agent-short| automatically uses BIG-IP Local Traffic Manager (LTM) `secure network address translation`_ (SNAT) 'automapping'. +The BIG-IP Local Traffic Manager automatically creates a SNAT pool of existing `self IP`_ addresses. + +For incoming traffic, Local Traffic Manager maps the origin IP address to an IP address from the SNAT pool. +This ensures that the server response returns to the client through the BIG-IP system. +For server-initiated traffic, Local Traffic Manager maps the server IP address to an IP address from the SNAT pool, effectively hiding the server's actual IP address from clients. + +.. important:: + + Because SNAT automap allocates existing self IP addresses into a SNAT pool, you should create enough self IPs to handle anticipated connection loads **before** deploying the |agent-long| in global routed mode. [#snatselfip]_ + + +Next steps +---------- + +- If this is your initial launch, :ref:`start the F5 agent `. +- If you have updated the configurations for a running |agent-short| instance, restart the service: + + - :command:`systemctl systemctl start f5-openstack-agent` \\ CentOS + - :command:`service f5-oslbaasv2-agent start` \\ Ubuntu + +See the `F5 Integration for OpenStack`_ documentation for more information. + + +.. rubric:: Footnotes +.. [#snatselfip] In an :term:`overcloud` deployment, BIG-IP Virtual Edition (VE) may allocate IP addresses automatically. + diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..cb8aba451 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,90 @@ +:orphan: true + +Glossary +======== + +.. glossary:: + :sorted: + + segmentation ID + segmentation id + `VLAN tag `_ + + device + `BIG-IP`_ hardware or virtual edition (VE). + + overcloud + `BIG-IP`_ virtual edition (VE) deployed as an OpenStack instance. + + undercloud + `BIG-IP`_ device (hardware or VE) deployed outside of OpenStack. + + standalone + A single `BIG-IP`_ device; no :term:`HA`. + + cluster + clustered + clustering + device cluster + device service cluster + device service clusters + DSC + Device Service Clustering provides synchronization and failover of `BIG-IP`_ configuration data among multiple `BIG-IP`_ devices on a network. You can configure a `BIG-IP`_ device on a network to synchronize some or all of its configuration data among several BIG-IP devices; fail over to one of many available devices; and/or mirror connections to a peer device to prevent interruption in service during failover. + + device group + A device group is a component of a device service cluster. It consists of a collection of `BIG-IP`_ devices that trust each other and can synchronize, and sometimes fail over, their configuration data. + + high availability + highly available + HA + The ability of a `BIG-IP`_ device to process network traffic successfully. An HA device is generally part of a :term:`device cluster`. + + pair + Two (2) `BIG-IP`_ devices configured to use the :term:`active-standby` :term:`HA` mode. + + scalen + Two (2) or more `BIG-IP`_ devices configured as an active :term:`device cluster`. + + active-active + Both `BIG-IP`_ devices in a :term:`pair` are in an active state, processing traffic for different virtual servers or SNATs. If one device :term:`fails over`, the remaining device processes traffic from the failed device in addition to its own traffic. + + active-standby + active-standby pair + Only one of the two `BIG-IP`_ devices is in an active state -- that is, processing traffic -- at any given time. If the active device :term:`fails over`, the second device enters active mode and processes traffic that was originally targeted for the primary device. + + failover + fail over + fails over + Failover occurs when one device in an :term:`active-standby` pair becomes unavailable; the secondary device processes traffic that was originally targeted for the primary device. + + mirror + mirroring + A `BIG-IP`_ system redundancy feature that ensures sharing of connection and persistence information across a device service cluster; mirroring helps prevent service interruptions if/when :term:`failover` occurs. + + SSL offloading + `SSL offloading `_ relieves a Web server of the processing burden of encrypting and/or decrypting traffic sent via the SSL security protocol. + + one-arm + one-arm mode + One-arm mode is a network topology wherein servers/clients connect to the BIG-IP via a single interface; a single VLAN handles all traffic. + + multi-arm + multiple-arm + multi-arm mode + multiple-arm mode + Multi-arm mode is a network topology wherein servers/clients connect to the BIG-IP via different interfaces; use two or more VLANs to separate management and data traffic. + + vcmp + Virtual Clustered Multiprocessing (vCMP) is a feature of the BIG-IP system that allows you to run multiple instances of the BIG-IP software on a single hardware platform. + + vCMP host + The vCMP host is the system-wide hypervisor that makes it possible for you to create and view BIG-IP instances, or vCMP 'guests'. + + vCMP guest + A vCMP guest is an instance of BIG-IP software created on the vCMP system for the purpose of provisioning one or more BIG-IP modules to process application traffic. + + partition + A BIG-IP partition is a logical container containing a defined set of BIG-IP system objects. See the `BIG-IP documentation`_ for more information. + +.. _BIG-IP: https://f5.com/products/big-ip +.. _BIG-IP documentation: https://support.f5.com/csp/federated-search?q=BIG-IP%20LTM diff --git a/docs/ha-mode.rst b/docs/ha-mode.rst new file mode 100644 index 000000000..8fdad2d39 --- /dev/null +++ b/docs/ha-mode.rst @@ -0,0 +1,86 @@ +.. _ha-mode: + +.. index:: + single: f5-openstack-agent; BIG-IP HA + +.. index:: + single: f5-openstack-agent; BIG-IP High Availability + +.. index:: + pair: f5-openstack-agent; High Availability; HA + +Set up BIG-IP High Availability mode +==================================== + +Overview +-------- + +:term:`HA`, or, 'high availability', mode refers to high availability of the BIG-IP device(s). +The |agent-long| can configure BIG-IP to operate in :term:`standalone`, :term:`pair`, or :term:`scalen` mode. +The |agent-short| configures LBaaS objects on HA BIG-IP devices in real time. + +:fonticon:`fa fa-chevron-right` :ref:`Learn more ` + +Caveats +------- + +- If you only have one (1) BIG-IP device deployed, you must use ``standalone`` mode. +- In this context, HA pertains to the BIG-IP device(s), not to the |agent-short|. + + +Configuration +------------- + +.. include:: /_static/reuse/edit-agent-config-file.rst + +#. Set the :ref:`Device driver settings `. + +#. Set :code:`f5_ha_type` as appropriate for your environment. + + - ``standalone``: A single BIG-IP device + - ``pair``: An :term:`active-standby` pair of BIG-IP devices + - ``scalen``: An active :term:`device service cluster` of 2 to 4 BIG-IP devices + + .. code-block:: text + + # + # HA mode + # + f5_ha_type = standalone + # + +#. Set up the |agent-long| to use :ref:`L2-adjacent mode ` or :ref:`Global Routed mode `. + +.. _learn-ha: + +Learn more +---------- + +Use Case +```````` + +High availability modes provide redundancy, helping to ensure service interruptions don't occur if a device goes down. + +* :term:`standalone` mode utilizes a single BIG-IP device; here, 'high availability' means that BIG-IP core services are up and running, and VLANs are able to send and receive traffic to and from the device. + +* :term:`pair` mode requires two (2) BIG-IP devices and provides :term:`active-standby` operation. + When an event occurs that prevents the 'active' BIG-IP device from processing network traffic, the 'standby' device immediately begins processing that traffic so users experience no interruption in service. + The standby device takes over the entire traffic load, avoiding a loss in performance. + +* :term:`scalen` mode requires a :term:`device service cluster` of two (2) - four (4) BIG-IP devices. + Scalen allows you to configure multiple active devices, each of which can fail over to other available active devices (:term:`active-active` mode). + For example, if two BIG-IP devices are using active-active mode, both devices in the pair actively handling traffic. + If an event occurs that prevents one device from processing traffic, that traffic automatically directs to the other active device. + + .. note:: + + When failover occurs on an active-active cluster, a secondary device takes over the peer traffic load in addition to its current load. + Depending on device configuration and capabilities, there may be a reduction in performance. + + +.. figure:: /_static/media/f5-lbaas-ha-active-standby-pair.png + :alt: BIG-IP HA pair using active-standby mode + :scale: 60% + + BIG-IP HA pair using active-standby mode + diff --git a/docs/index.rst b/docs/index.rst index 252cd882f..62b5b7603 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,47 +1,4 @@ -.. _home: +.. _agent-home: -F5® OpenStack Agent -=================== - -|Build Status| |Docs Build Status| - -.. raw:: html - - - -Overview --------- - -.. include:: ../README.rst - :start-line: 26 - :end-line: 28 - -.. toctree:: - :hidden: - :maxdepth: 1 - - - -Installation ------------- - -.. include:: topic_install-f5-agent.rst - :start-line: 3 - -For more information about using F5® technologies in OpenStack with Neutron LBaaSv2, please see the :ref:`f5-openstack-lbaasv2-driver documentation `. - - -Configuration and Usage ------------------------ - -See the :ref:`F5® OpenStack LBaaSv2 documentation `. - - -.. |Build Status| image:: https://travis-ci.org/F5Networks/f5-openstack-agent.svg?branch=liberty - :target: https://travis-ci.org/F5Networks/f5-openstack-agent - :alt: Build Status - -.. |Docs Build Status| image:: http://readthedocs.org/projects/f5-openstack-agent/badge/?version=liberty - :target: http://f5-openstack-agent.readthedocs.io/en/liberty/?badge=liberty - :alt: Documentation Status +.. include:: README.rst diff --git a/docs/l2-adjacent-mode.rst b/docs/l2-adjacent-mode.rst new file mode 100644 index 000000000..132aead9e --- /dev/null +++ b/docs/l2-adjacent-mode.rst @@ -0,0 +1,365 @@ +.. _l2-adjacent-mode: + +.. index:: + single: f5-openstack-agent; L2-adjacent mode + +L2-adjacent mode +================ + +L2-adjacent mode (:code:`f5_global_routed_mode = False`) is the default mode of operation for the |agent-long| (F5 agent). +The |agent-short| **does not automatically detect any network or BIG-IP configurations**. +You must provide the appropriate L2/L3 network settings for your BIG-IP device(s) in the :ref:`L2 segmentation mode ` and :ref:`L3 segmentation mode ` sections of the |agent-short| :ref:`configuration file `. + +:fonticon:`fa fa-chevron-right` :ref:`Learn more ` + +Prerequisites +------------- + +You should have VLANs and VxLAN or GRE tunnels configured as appropriate for your environment. +If you're using GRE or VxLAN tunnels, you must have a BIG-IP `Better or Best license`_ that supports SDN. + +.. warning:: + + Many L3 segmentation mode parameters depend on other configuration parameters. + Read the text in the :ref:`F5 agent configuration file` carefully before changing these settings to ensure they don't conflict. + +Configuration +------------- + +.. include:: /_static/reuse/edit-agent-config-file.rst + +.. seealso:: + + * :fonticon:`fa fa-download` :download:`Sample Configuration file for GRE ` + * :fonticon:`fa fa-download` :download:`Sample Configuration file for VXLAN ` + +#. Set up the :ref:`Device driver settings ` and :ref:`HA mode `. + +#. Set up the appropriate L2- and L3-segmentation settings for your deployment. + +.. _l2-segmentation-mode: + +Interface and port mapping +`````````````````````````` + +:code:`f5_external_physical_mappings` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Maps Neutron networks with type :code:`VLAN` to a specific BIG-IP interface. +It follows the format :code:`physical_network:interface_name:tagged`, where: + +* :code:`physical_network` is the `external provider network`_ (Neutron's :code:`provider:physical_network`). +* :code:`interface_name` is the name of a BIG-IP interface or LAG trunk. +* :code:`tagged` is a boolean indicating whether or not the BIG-IP should enforce VLAN tagging. + +.. code-block:: text + + # standalone example: + f5_external_physical_mappings = default:1.1:True + # + # pair or scalen example: + f5_external_physical_mappings = default:1.3:True + +.. note:: + + If using pair or scalen on a 3-NIC device, use interface 1.3. + Interface 1.1 usually maps to an external VLAN and 1.2 to internal VLANs. + +:code:`vlan_binding_driver` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Binds tagged VLANs to specific BIG-IP ports. +For example, if an LBaaS iControl endpoint uses tagged VLANs, and you add a VLAN tagged network to a specific BIG-IP device, the facing switch port needs to allow traffic for that VLAN tag through to the correct BIG-IP port. + +.. caution:: + + This setting requires a custom software hook. + If you choose to write one, keep the following in mind: + + - A :class:`vlan_binding_driver` class must reference an iControl :class:`VLANBindingBase` subclass. + - You must provide the methods to bind VLAN tags to ports and prune unused VLAN tags. + +.. code-block:: text + + # the path to your custom software hook + vlan_binding_driver = f5-openstack-agent.drivers.bigip.vlan_binding.MyBindingDriver + +.. _device-tunneling-vtep: + +Tunneling +````````` + +:code:`f5_vtep_` +~~~~~~~~~~~~~~~~ + +:code:`f5_vtep_folder`: The name of the BIG-IP :term:`partition` in which the `VTEP`_ (VxLAN tunnel endpoint) resides; the default partition is ``/Common``. +:code:`f5_vtep_selfip_name`: The name of the VTEP self IP. + +Can be a single entry or a comma-separated list (one per BIG-IP device); must be in cidr (h/m) format. +The VTEP self IPs must already exist on the BIG-IP device(s). + +.. code-block:: text + + # Device Tunneling (VTEP) selfips + # + f5_vtep_folder = Common + f5_vtep_selfip_name = my_vtep + # + +.. hint:: + + If you're not using GRE or VxLAN tunneling, you can comment these settings out or set both to ``None``. + +:code:`advertised_tunnel_types` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tells the |agent-short| what type of tunnel(s) connect the BIG-IP device(s) to controller/compute node(s) in OpenStack (GRE or VxLAN). +This can be a single entry or comma-separated values. +If you are not using tunnels, leave this setting blank. + +.. note:: + + The |agent-long| creates profiles for all available tunnel types on the BIG-IP device(s) when you start it for the first time. + See `Neutron to BIG-IP command mapping `_ for more information. + + +.. code-block:: text + + # Tunnel types + # + # If you are using only gre tunnels: + # + advertised_tunnel_types = gre + # + # If you are using only vxlan tunnels: + # + advertised_tunnel_types = vxlan + # + # If you are using both gre and vxlan tunnel networks: + # + advertised_tunnel_types = gre,vxlan + # + # If you are NOT using tunnel networks (vlans only): + # + advertised_tunnel_types = + # + +Routing +``````` + +.. _static-arp: + +:code:`f5_populate_static_arp` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A boolean indicating whether or not you want to create static arp entries for pool member IP addresses on VxLAN or GRE tunnel networks. + +The static ARP entry is in addition to the tunnel forwarding database (FDB) entry for the pool member. +It helps avoid the need to learn the member's MAC address via flooding. + +.. code-block:: text + + # Static ARP population for members on tunnel networks + # + f5_populate_static_arp = True + # + +:code:`l2_population` +~~~~~~~~~~~~~~~~~~~~~ + +A boolean indicating whether or not the BIG-IP device should use the L2 population service to update FBD tunnel entries. + +.. important:: + + If you're running any other OpenStack tunnel agents, be sure to set all of them up the same way. + +.. code-block:: text + + # + l2_population = True + # + +:code:`use_namespaces` +~~~~~~~~~~~~~~~~~~~~~~ + +A boolean indicating whether or not the BIG-IP should use tenant routing tables to route traffic. +Set this value to True to allow overlapping subnet IP addresses. + +.. code-block:: text + + # + use_namespaces = True + # + +:code:`max_namespaces_per_tenant` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An integer indicating the maximum number of route domains allowed per tenant. +This allows a tenant to have overlapping IP subnets. + +.. code-block:: text + + # + max_namespaces_per_tenant = 1 + # + +:code:`f5_route_domain_strictness` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A boolean indicating whether VIPS and members in different tenants can communicate with each other. +Set this value to True to force the BIG-IP to prefer tenant routing tables over the global routing table and provide tenant isolation. + +.. code-block:: text + + # + f5_route_domain_strictness = False + # + +:code:`f5_snat_mode` +~~~~~~~~~~~~~~~~~~~~ + +A boolean indicating whether or not to use `SNATs`_. + +:code:`f5_snat_addresses_per_subnet` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An integer indicating the number of `self IP`_ addresses the BIG-IP device should add to a SNAT pool for each subnet. + +.. code-block:: text + + # + f5_snat_mode = True + # + f5_snat_addresses_per_subnet = 1 + # + +:code:`f5_common_external_networks` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A boolean that controls how the BIG-IP device routes traffic on Neutron networks. +Set this value to True to use the global routing table for traffic on all Neutron networks with the :code:`external` router type. + +.. code-block:: text + + # + f5_common_external_networks = True + # + +.. _common networks: + +:code:`common_network_ids` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A 'name-value' pair mapping BIG-IP VLANs to Neutron networks; multiple values can be comma-separated. +The first value is the Neutron network ID; the second is the BIG-IP network name. + +For example, if the Internet VLAN on your BIG-IP device, ``/Common/external``, has the Neutron uuid ``71718972-78e2-449e-bb56-ce47cc9d2680``, the entry would look like this: + +.. code-block:: text + + # Common Networks + # + common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external + # + +You can separate multiple values with commas, as shown below. + +.. code-block:: text + + # + common_network_ids = 71718972-78e2-449e-bb56-ce47cc9d2680:external,396e06a0-05c7-4a49-8e86-04bb83d14438:vlan1222 + # + +.. _l3 binding: + +:code:`l3_binding_driver` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A software hook that binds L3 addresses to specific ports, allowing communications between Nova guest instances. + +.. important:: + + If you're managing :term:`overcloud` BIG-IP VE instances, uncomment this line in the F5 Agent Configuration File. + +.. code-block:: text + + # + l3_binding_driver = f5_openstack_agent.lbaasv2.drivers.bigip.l3_binding.AllowedAddressPairs + # + +Software-defined networking +``````````````````````````` + +:code:`f5_network_segment_physical_network` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The name of the network segment where the BIG-IP device resides. + +:code:`f5_network_segment_polling_interval` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The number of seconds to wait between polling Neutron for a :code:`network_id` to :code:`segmentation_id` mapping (default=10). + +:code:`f5_pending_services_timeout` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The maximum number of seconds to wait for network discovery before a pending service errors out (default=60). + +.. tip:: + + These `Hierarchical Port Binding`_ settings allow you to integrate and manage SDN services using F5 LBaaS. + If you're not using this feature, comment out all three settings, or set them to None, to avoid errors. + +.. code-block:: text + + # Hierarchical Port Binding + # + f5_network_segment_physical_network = + # + # Periodically scan for disconected listeners (a.k.a virtual servers). The + # interval is number of seconds between attempts. + # + f5_network_segment_polling_interval = 10 + # + f5_pending_services_timeout = 60 + # + +.. _learn-lam: + +Learn more +---------- + +Example Use Case +```````````````` + +Typically, the |agent-long| manages one (1) or more BIG-IP devices deployed in the services tier of an `external provider network`_. +The BIG-IP devices may have direct lines of communication with nodes in the OpenStack cloud (VXLAN or GRE tunnels) or they may connect to the same VLAN subnet(s) as OpenStack nodes. + +.. figure:: /_static/media/f5-lbaas-l2-3-adjacent-mode.png + :alt: L2-adjacent BIG-IP cluster diagram shows a BIG-IP device cluster as part of an L3-routed network external to the OpenStack cloud. VXLAN or GRE tunnels connect OpenStack nodes directly to the device cluster. + :width: 60% + + L2-adjacent BIG-IP device cluster + +The |agent-short| can also manage BIG-IP Virtual Edition (VE) instances deployed 'over the cloud' (or :term:`overcloud`) using L2-adjacent mode. +These VE instances would connect to individual OpenStack nodes via VLANs, as opposed to VXLAN or GRE tunnels. +This type of deployment is commonly used as part of a software-defined networking (SDN) solution, such as with `Cisco ACI`_. + +.. todo:: add Cisco APIC/ACI deployment solution guide and link to it here + +.. important:: + + The |agent-short| L2/L3 segmentation mode settings must match the configurations of your existing external network and BIG-IP device(s). + +Next steps +---------- + +- If this is your initial launch, :ref:`start the F5 agent `. +- If you have updated the configurations for a running |agent-short| , restart the service: + + - CentOS: :command:`systemctl systemctl start f5-openstack-agent` + - Ubuntu :command:`service f5-oslbaasv2-agent start` + +See the `F5 Integration for OpenStack`_ documentation for more information. + + diff --git a/docs/ref_agent-config-file.rst b/docs/ref_agent-config-file.rst deleted file mode 100644 index 62944b424..000000000 --- a/docs/ref_agent-config-file.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. toctree:: - :hidden: - -Agent Configuration File ------------------------- - -A sample F5® OpenStack agent configuration file is shown below. The file can be found at ``/etc/neutron/services/f5/f5-openstack-agent.ini``. When setting up your own F5® agent(s), be sure to use the correct information for your environment. - -.. literalinclude:: ../etc/neutron/services/f5/f5-openstack-agent.ini - diff --git a/docs/scripts/deploy-docs.sh b/docs/scripts/deploy-docs.sh new file mode 100755 index 000000000..fe1eec060 --- /dev/null +++ b/docs/scripts/deploy-docs.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +# Don't set -x +# We need to keep the secrets AWS variables out of the logs + +: ${DOC_IMG:=f5devcentral/containthedocs:latest} + +exec docker run --rm -it -v $PWD:$PWD --workdir $PWD \ + -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \ + -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \ + -e AWS_S3_BUCKET=$AWS_S3_BUCKET \ + ${DOC_IMG} "$@" diff --git a/docs/scripts/docker-docs.sh b/docs/scripts/docker-docs.sh new file mode 100755 index 000000000..5d8019f7c --- /dev/null +++ b/docs/scripts/docker-docs.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash + +set -x + +: ${DOC_IMG:=f5devcentral/containthedocs:latest} + +exec docker run --rm -it \ + -v $PWD:$PWD --workdir $PWD \ + ${DOCKER_RUN_ARGS} \ + -e "LOCAL_USER_ID=$(id -u)" \ + ${DOC_IMG} "$@" \ No newline at end of file diff --git a/docs/scripts/test-docs.sh b/docs/scripts/test-docs.sh new file mode 100755 index 000000000..6b30bbde2 --- /dev/null +++ b/docs/scripts/test-docs.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash + +html="make -C docs html" +linkcheck="sphinx-build -b linkcheck docs docs/_build/linkcheck" +grammar="write-good `find ./docs -not \( -path ./docs/drafts -prune \) -name '*.rst'` --passive --so --no-illusion --thereIs --cliches" + +if [ $TRAVIS="true" ]; + then OUTPUT_DIR=${TRAVIS_BUILD_DIR}/_build/linkcheck +fi + +warn() { + printf "%s\n" "$*" >&2 + + exit 0 +} + +die() { + printf "%s\n" "$*" >&2 + + exit 1 +} + +goodjob() { + printf "%s\n" "$*" >&2 + +} + +make -C docs clean + +echo $TRAVIS + +set -e + +echo "Building docs with Sphinx" +set -x +$html + +echo "Checking grammar and style" +set -x +$grammar +set +x +[[ $grammar = "" ]] || goodjob "CONGRATULATIONS! You are a grammar wizard." + +echo "Checking links" +if [[ $linkcheck != "" ]]; then + sphinx-build -b linkcheck docs docs/_build/linkcheck | grep 'broken' + warn "WARNING: Link check failed. See output above for errors." + else echo "Linkcheck succeeded" +fi diff --git a/docs/topic_install-f5-agent.rst b/docs/topic_install-f5-agent.rst deleted file mode 100644 index a00e3c5bb..000000000 --- a/docs/topic_install-f5-agent.rst +++ /dev/null @@ -1,77 +0,0 @@ -Install the F5 OpenStack Agent ------------------------------- - -Quick Start -``````````` - -.. rubric:: Install the ``f5-openstack-agent`` package for v |release|: - -.. parsed-literal:: - - $ sudo pip install |f5_agent_pip_url| - -.. tip:: - - You can install packages from HEAD on a specific branches by adding ``@`` to the end of the install command instead of the release tag. - - .. rubric:: Example: - .. code-block:: text - - $ sudo pip install git+https://github.com/F5Networks/f5-openstack-agent@mitaka - - -Debian Package -`````````````` - -The ``f5-openstack-agent`` package can be installed using ``dpkg`` tools. - -1. Download and install the dependencies: - -.. parsed-literal:: - - $ curl -L -O |f5_sdk_deb_url| - $ curl -L -O |f5_icontrol_deb_url| - $ sudo dpkg –i |f5_icontrol_deb_package| - $ sudo dpkg –i |f5_sdk_deb_package| - -2. Download and install the f5-openstack-agent: - -.. parsed-literal:: - - $ curl -L -O |f5_agent_deb_url| - $ sudo dpkg –i |f5_agent_deb_package| - - -RPM Package -``````````` - -The ``f5-openstack-agent`` package can be installed using ``rpm`` tools. - -1. Download and install the dependencies: - -.. parsed-literal:: - - $ curl -L -O |f5_sdk_rpm_url| - $ curl -L -O |f5_icontrol_rpm_url| - $ sudo rpm -ivh |f5_icontrol_rpm_package| |f5_sdk_rpm_package| - - -2. Download and install the f5-openstack-agent: - -.. parsed-literal:: - - $ curl -L -O |f5_agent_rpm_url| - $ sudo rpm –ivh |f5_agent_rpm_package| - - - -Next Steps -`````````` - -Next, :ref:`install the f5-openstack-lbaasv2-driver `. - - -Need to Upgrade? -```````````````` - -Please see the :ref:`upgrade instructions `. diff --git a/etc/init.d/f5-oslbaasv2-agent b/etc/init.d/f5-oslbaasv2-agent index 5959aad0a..1e10b26e6 100755 --- a/etc/init.d/f5-oslbaasv2-agent +++ b/etc/init.d/f5-oslbaasv2-agent @@ -8,7 +8,7 @@ # Default-Start: 2 3 4 5 # Default-Stop: 0 1 6 # Short-Description: f5-openstack-agent -# Description: Provides the F5® OpenStack agent to configure BIG-IP® +# Description: Provides the F5 OpenStack agent to configure BIG-IP ### END INIT INFO PROJECT_NAME=neutron diff --git a/etc/neutron/services/f5/f5-openstack-agent.ini b/etc/neutron/services/f5/f5-openstack-agent.ini index 493336e43..6957feda9 100644 --- a/etc/neutron/services/f5/f5-openstack-agent.ini +++ b/etc/neutron/services/f5/f5-openstack-agent.ini @@ -50,17 +50,17 @@ periodic_interval = 10 # Environment Settings ############################################################################### # -# Since many TMOS® object names must start with an alpha character +# Since many TMOS object names must start with an alpha character # the environment_prefix is used to prefix all service objects. # -# Objects created on the BIG-IP® by this agent will have their names prefixed +# Objects created on the BIG-IP by this agent will have their names prefixed # by an environment string. This allows you set this string. The default is # 'Project'. # # WARNING - you should only set this before creating any objects. If you change # it with established objects, the objects created with an alternative prefix, # will no longer be associated with this agent and all objects in neutron -# and on the the BIG-IP® associated with the old environment will need to be managed +# and on the the BIG-IP associated with the old environment will need to be managed # manually. # # environment_prefix = 'Project' @@ -183,10 +183,10 @@ f5_external_physical_mappings = default:1.1:True # Some systems require the need to bind and prune VLANs ids # allowed to specific ports, often for security. # -# An example would be if a LBaaS iControl® endpoint is using +# An example would be if a LBaaS iControl endpoint is using # tagged VLANs. When a VLAN tagged network is added to a -# specific BIG-IP® device, the facing switch port will need -# to allow traffic for that VLAN tag through to the BIG-IP®'s +# specific BIG-IP device, the facing switch port will need +# to allow traffic for that VLAN tag through to the BIG-IP's # port for traffic to flow. # # What is required is a software hook which allows the binding. @@ -197,16 +197,16 @@ f5_external_physical_mappings = default:1.1:True # vlan_binding_driver = f5.oslbaasv1agent.drivers.bigip.vlan_binding.NullBinding # # The interface_port_static_mappings allows for a JSON encoded dictionary -# mapping BIG-IP® devices and interfaces to corresponding ports. A port id can be +# mapping BIG-IP devices and interfaces to corresponding ports. A port id can be # any string which is meaningful to a vlan_binding_driver. It can be a # switch_id and port, or it might be a neutron port_id. # -# In addition to any static mappings, when the iControl® endpoints +# In addition to any static mappings, when the iControl endpoints # are initialized, all their TMM interfaces will be collect # for each device and neutron will be queried to see if which # device port_ids correspond to known neutron ports. If they do, # automatic entries for all mapped port_ids will be made referencing -# the BIG-IP® device name and interface and the neutron port_ids. +# the BIG-IP device name and interface and the neutron port_ids. # # interface_port_static_mappings = {"device_name_1":{"interface_ida":"port_ida","interface_idb":"port_idb"}, {"device_name_2":{"interface_ida":"port_ida","interface_idb":"port_idb"}} # @@ -216,7 +216,7 @@ f5_external_physical_mappings = default:1.1:True # # Device Tunneling (VTEP) Self IPs # -# This is the name of a BIG-IP® self IP address to use for VTEP addresses. +# This is the name of a BIG-IP self IP address to use for VTEP addresses. # # If no gre or vxlan tunneling is required, these settings should be # commented out or set to None. @@ -265,10 +265,10 @@ f5_populate_static_arp = False # # Device Tunneling (VTEP) self IPs # -# This is a boolean entry which determines if the BIG-IP® will use +# This is a boolean entry which determines if the BIG-IP will use # L2 Population service to update its fdb tunnel entries. This needs # to be set up in accordance with the way the other tunnel agents are -# set up. If the BIG-IP® agent and other tunnel agents don't match +# set up. If the BIG-IP agent and other tunnel agents don't match # the tunnel setup will not work properly. # l2_population = True @@ -303,13 +303,13 @@ l2_population = True # L3 Segmentation Mode Settings ############################################################################### # -# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP® +# Global Routed Mode - No L2 or L3 Segmentation on BIG-IP # # This setting will cause the agent to assume that all VIPs # and pool members will be reachable via global device -# L3 routes, which must be already provisioned on the BIG-IP®s. +# L3 routes, which must be already provisioned on the BIG-IPs. # -# In f5_global_routed_mode, BIG-IP® will not assume L2 +# In f5_global_routed_mode, BIG-IP will not assume L2 # adjacentcy to any neutron network, therefore no # L2 segementation between tenant services in the data plane # will be provisioned by the agent. Because the routing @@ -320,22 +320,22 @@ l2_population = True # # WARNING: setting this mode to True will override # the use_namespaces, setting it to False, because only -# one global routing space will used on the BIG-IP®. This +# one global routing space will used on the BIG-IP. This # means overlapping IP addresses between tenants is no # longer supported. # # WARNING: setting this mode to True will override # the f5_snat_mode, setting it to True, because pool members -# will never be considered L2 adjacent to the BIG-IP® by +# will never be considered L2 adjacent to the BIG-IP by # the agent. All member access will be via L3 routing, which -# will need to be set up on the BIG-IP® before LBaaS provisions +# will need to be set up on the BIG-IP before LBaaS provisions # resources on behalf of tenants. # # WARNING: setting this mode to True will override the # f5_snat_addresses_per_subnet, setting it to 0 (zero). # This will force all VIPs to use AutoMap SNAT for which # enough Self IP will need to be pre-provisioned on the -# BIG-IP® to handle all pool member connections. The SNAT, +# BIG-IP to handle all pool member connections. The SNAT, # an L3 mechanism, will all be global without reference # to any specific tenant SNAT pool. # @@ -344,7 +344,7 @@ l2_population = True # because no L2 information will be taken from # neutron, thus making the assumption that all VIP # L3 addresses will be globally routable without -# segmentation at L2 on the BIG-IP®. +# segmentation at L2 on the BIG-IP. # f5_global_routed_mode = True # @@ -399,14 +399,14 @@ f5_route_domain_strictness = False # This setting will force the use of SNATs. # # If this is set to False, a SNAT will not -# be created (routed mode) and the BIG-IP® +# be created (routed mode) and the BIG-IP # will attempt to set up a floating self IP # as the subnet's default gateway address. # and a wild card IP forwarding virtual # server will be set up on member's network. # Setting this to False will mean Neutron # floating self IPs will not longer work -# if the same BIG-IP® device is not being used +# if the same BIG-IP device is not being used # as the Neutron Router implementation. # # This setting will be forced to True if @@ -450,16 +450,16 @@ f5_common_external_networks = True # separated list where if the name is a neutron # network id used for a vip or a pool member, # the network should not be created or deleted -# on the BIG-IP®, but rather assumed that the value +# on the BIG-IP, but rather assumed that the value # is the name of the network already created in # the Common partition with all L3 addresses # assigned to route domain 0. This is useful # for shared networks which are already defined -# on the BIG-IP® prior to LBaaS configuration. The +# on the BIG-IP prior to LBaaS configuration. The # network should not be managed by the LBaaS agent, # but can be used for VIPs or pool members # -# If your Internet VLAN on your BIG-IP® is named +# If your Internet VLAN on your BIG-IP is named # /Common/external, and that corresponds to # Neutron uuid: 71718972-78e2-449e-bb56-ce47cc9d2680 # then the entry would look like: @@ -478,7 +478,7 @@ f5_common_external_networks = True # Some systems require the need to bind L3 addresses # to specific ports, often for security. # -# An example would be if a LBaaS iControl® endpoint is using +# An example would be if a LBaaS iControl endpoint is using # untagged VLANs and is a nova guest instance. By # default, neutron will attempt to apply security rule # for anti-spoofing which will not allow just any L3 @@ -498,7 +498,7 @@ f5_common_external_networks = True # vary between providers. They may look like a neutron port id # and a nova guest instance id. # -# In addition to any static mappings, when the iControl® endpoints +# In addition to any static mappings, when the iControl endpoints # are initialized, all their TMM MAC addresses will be collect # and neutron will be queried to see if the MAC addresses # correspond to known neutron ports. If they do, automatic entries @@ -517,7 +517,7 @@ f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol # # ############################################################################### -# Device Driver - iControl® Driver Setting +# Device Driver - iControl Driver Setting ############################################################################### # # icontrol_hostname is valid for external device type only. @@ -530,17 +530,17 @@ f5_bigip_lbaas_device_driver = f5_openstack_agent.lbaasv2.drivers.bigip.icontrol # is not standalone, all devices in the sync failover # device group for the hostname specified must have # their management IP address reachable to the agent. -# If order to access devices' iControl® interfaces via +# If order to access devices' iControl interfaces via # self IPs, you should specify them as a comma # separated list below. # icontrol_hostname = 10.190.7.232 # -# If you are using vCMP® with VLANs, you will need to configure -# your vCMP® host addresses, in addition to the guests addresses. -# vCMP® Host access is necessary for provisioning VLANs to a guest. -# Use icontrol_hostname for vCMP® guests and icontrol_vcmp_hostname -# for vCMP® hosts. The plug-in will automatically determine +# If you are using vCMP with VLANs, you will need to configure +# your vCMP host addresses, in addition to the guests addresses. +# vCMP Host access is necessary for provisioning VLANs to a guest. +# Use icontrol_hostname for vCMP guests and icontrol_vcmp_hostname +# for vCMP hosts. The plug-in will automatically determine # which host corresponds to each guest. # # icontrol_vcmp_hostname = 192.168.1.245 diff --git a/f5_openstack_agent/__init__.py b/f5_openstack_agent/__init__.py index 31c4ffa93..7d26263dd 100644 --- a/f5_openstack_agent/__init__.py +++ b/f5_openstack_agent/__init__.py @@ -1 +1 @@ -__version__ = "9.3.2" +__version__ = "9.3.3.b1" diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/agent_manager.py b/f5_openstack_agent/lbaasv2/drivers/bigip/agent_manager.py index 8159b852c..f1824bd9a 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/agent_manager.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/agent_manager.py @@ -235,7 +235,7 @@ def __init__(self, conf): else: self.agent_host = conf.host - # Load the iControl® driver. + # Load the iControl driver. self._load_driver(conf) # Initialize agent configurations @@ -264,7 +264,7 @@ def __init__(self, conf): self.admin_state_up = True - # Set iControl® driver context for RPC. + # Set iControl driver context for RPC. self.lbdriver.set_context(self.context) # Setup RPC: diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/icontrol_driver.py b/f5_openstack_agent/lbaasv2/drivers/bigip/icontrol_driver.py index b950b4cd9..94288906e 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/icontrol_driver.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/icontrol_driver.py @@ -69,7 +69,7 @@ NS_PREFIX = 'qlbaas-' __VERSION__ = '0.1.1' -# configuration objects specific to iControl® driver +# configuration objects specific to iControl driver # XXX see /etc/neutron/services/f5/f5-openstack-agent.ini OPTS = [ # XXX maybe we should make this a dictionary cfg.StrOpt( @@ -334,7 +334,7 @@ def __init__(self, conf, registerOpts=True): self.connected = False # overrides base, same value self.driver_name = 'f5-lbaasv2-icontrol' - # BIG-IP® containers + # BIG-IP containers self.__bigips = {} self.__traffic_groups = [] self.agent_configurations = {} # overrides base, same value @@ -517,7 +517,7 @@ def _init_bigip_hostnames(self): self.hostnames = sorted(self.hostnames) def _init_bigips(self): - # Connect to all BIG-IP®s + # Connect to all BIG-IPs if self.connected: return try: @@ -1618,7 +1618,7 @@ def _init_traffic_groups(self, bigip): self.__traffic_groups.sort() def _validate_bigip_version(self, bigip, hostname): - # Ensure the BIG-IP® has sufficient version + # Ensure the BIG-IP has sufficient version major_version = self.system_helper.get_major_version(bigip) if major_version < f5const.MIN_TMOS_MAJOR_VERSION: raise f5ex.MajorVersionValidateFailed( diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/l2_service.py b/f5_openstack_agent/lbaasv2/drivers/bigip/l2_service.py index d3ce07375..a3c87b5eb 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/l2_service.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/l2_service.py @@ -34,7 +34,7 @@ def _get_tunnel_name(network): - # BIG-IP® object name for a tunnel + # BIG-IP object name for a tunnel tunnel_type = network['provider:network_type'] tunnel_id = network['provider:segmentation_id'] return 'tunnel-' + str(tunnel_type) + '-' + str(tunnel_id) diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/l3_binding.py b/f5_openstack_agent/lbaasv2/drivers/bigip/l3_binding.py index f5e9a36ee..76a6fde11 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/l3_binding.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/l3_binding.py @@ -58,8 +58,8 @@ def __init__(self, conf, driver): LOG.debug('l3_binding_static_mappings not configured') def register_bigip_mac_addresses(self): - # Delayed binding BIG-IP® ports will be called - # after BIG-IP® endpoints are registered. + # Delayed binding BIG-IP ports will be called + # after BIG-IP endpoints are registered. if not self.__initialized__bigip_ports: for bigip in self.driver.get_all_bigips(): LOG.debug('Request Port information for MACs: %s' diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/lbaas_builder.py b/f5_openstack_agent/lbaasv2/drivers/bigip/lbaas_builder.py index f6decd7c3..512f28bad 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/lbaas_builder.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/lbaas_builder.py @@ -33,8 +33,8 @@ class LBaaSBuilder(object): - # F5® LBaaS Driver using iControl® for BIG-IP® to - # create objects (vips, pools) - not using an iApp®.""" + # F5 LBaaS Driver using iControl for BIG-IP to + # create objects (vips, pools) - not using an iApp.""" def __init__(self, conf, driver, l2_service=None): self.conf = conf diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/listener_service.py b/f5_openstack_agent/lbaasv2/drivers/bigip/listener_service.py index 48c1ea9cb..9bce7a128 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/listener_service.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/listener_service.py @@ -25,11 +25,11 @@ class ListenerServiceBuilder(object): - u"""Create LBaaS v2 Listener on BIG-IP®s. + u"""Create LBaaS v2 Listener on BIG-IPs. Handles requests to create, update, delete LBaaS v2 listener - objects on one or more BIG-IP® systems. Maps LBaaS listener - defined in service object to a BIG-IP® virtual server. + objects on one or more BIG-IP systems. Maps LBaaS listener + defined in service object to a BIG-IP virtual server. """ def __init__(self, service_adapter, cert_manager, parent_ssl_profile=None): @@ -42,9 +42,9 @@ def __init__(self, service_adapter, cert_manager, parent_ssl_profile=None): parent_ssl_profile) def create_listener(self, service, bigips): - u"""Create listener on set of BIG-IP®s. + u"""Create listener on set of BIG-IPs. - Create a BIG-IP® virtual server to represent an LBaaS + Create a BIG-IP virtual server to represent an LBaaS Listener object. :param service: Dictionary which contains a both a listener @@ -75,7 +75,7 @@ def create_listener(self, service, bigips): self.add_ssl_profile(tls, bigip) def get_listener(self, service, bigip): - u"""Retrieve BIG-IP® virtual from a single BIG-IP® system. + u"""Retrieve BIG-IP virtual from a single BIG-IP system. :param service: Dictionary which contains a both a listener and load balancer definition. @@ -88,7 +88,7 @@ def get_listener(self, service, bigip): return obj def delete_listener(self, service, bigips): - u"""Delete Listener from a set of BIG-IP® systems. + u"""Delete Listener from a set of BIG-IP systems. Delete virtual server that represents a Listener object. @@ -148,7 +148,7 @@ def create_ssl_profile(self, container_ref, bigip, vip, sni_default=False): self._add_profile(vip, name, bigip, context='clientside') def update_listener(self, service, bigips): - u"""Update Listener from a single BIG-IP® system. + u"""Update Listener from a single BIG-IP system. Updates virtual servers that represents a Listener object. diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/loadbalancer_service.py b/f5_openstack_agent/lbaasv2/drivers/bigip/loadbalancer_service.py index 6b8dc1342..27c820550 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/loadbalancer_service.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/loadbalancer_service.py @@ -27,16 +27,16 @@ class LoadBalancerServiceBuilder(object): - """Create loadbalancer related objects on BIG-IP®s + """Create loadbalancer related objects on BIG-IPs Handles requests to create and delete LBaaS v2 tenant partition - folders on one or more BIG-IP® systems. + folders on one or more BIG-IP systems. """ def __init__(self): self.folder_helper = BigIPResourceHelper(ResourceType.folder) def create_partition(self, service, bigips): - """Create tenant partition on set of BIG-IP®s. + """Create tenant partition on set of BIG-IPs. Creates a partition if it is not named "Common". @@ -50,7 +50,7 @@ def create_partition(self, service, bigips): self.folder_helper.create(bigip, folder) def delete_partition(self, service, bigips): - """Deletes partition from a set of BIG-IP® systems. + """Deletes partition from a set of BIG-IP systems. Deletes partition if it is not named "Common". diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/pool_service.py b/f5_openstack_agent/lbaasv2/drivers/bigip/pool_service.py index 8c2f7d1ee..dfdbcc952 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/pool_service.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/pool_service.py @@ -28,10 +28,10 @@ class PoolServiceBuilder(object): - """Create LBaaS v2 pools and related objects on BIG-IP®s. + """Create LBaaS v2 pools and related objects on BIG-IPs. Handles requests to create, update, delete LBaaS v2 pools, - health monitors, and members on one or more BIG-IP® systems. + health monitors, and members on one or more BIG-IP systems. """ def __init__(self, service_adapter): @@ -44,9 +44,9 @@ def __init__(self, service_adapter): self.node_helper = BigIPResourceHelper(ResourceType.node) def create_pool(self, service, bigips): - """Create a pool on set of BIG-IP®s. + """Create a pool on set of BIG-IPs. - Creates a BIG-IP® pool to represent an LBaaS pool object. + Creates a BIG-IP pool to represent an LBaaS pool object. :param service: Dictionary which contains a both a pool and load balancer definition. @@ -57,9 +57,9 @@ def create_pool(self, service, bigips): self.pool_helper.create(bigip, pool) def delete_pool(self, service, bigips): - """Delete a pool on set of BIG-IP®s. + """Delete a pool on set of BIG-IPs. - Deletes a BIG-IP® pool defined by LBaaS pool object. + Deletes a BIG-IP pool defined by LBaaS pool object. :param service: Dictionary which contains a both a pool and load balancer definition. @@ -73,7 +73,7 @@ def delete_pool(self, service, bigips): partition=pool["partition"]) def update_pool(self, service, bigips): - """Update BIG-IP® pool. + """Update BIG-IP pool. :param service: Dictionary which contains a both a pool and load balancer definition. @@ -126,7 +126,7 @@ def update_healthmonitor(self, service, bigips): # Note: can't use BigIPResourceHelper class because members # are created within pool objects. Following member methods - # use the F5® SDK directly. + # use the F5 SDK directly. def create_member(self, service, bigips): pool = self.service_adapter.get_pool(service) member = self.service_adapter.get_member(service) diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/resource_helper.py b/f5_openstack_agent/lbaasv2/drivers/bigip/resource_helper.py index f3406f695..1cbc28e4a 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/resource_helper.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/resource_helper.py @@ -22,7 +22,7 @@ class ResourceType(Enum): - u"""Defines supported BIG-IP® resource types.""" + u"""Defines supported BIG-IP resource types.""" nat = 1 pool = 2 @@ -62,9 +62,9 @@ class ResourceType(Enum): class BigIPResourceHelper(object): - u"""Helper class for creating, updating and deleting BIG-IP® resources. + u"""Helper class for creating, updating and deleting BIG-IP resources. - Reduces some of the boilerplate that surrounds using the F5® SDK. + Reduces some of the boilerplate that surrounds using the F5 SDK. Example usage: bigip = BigIP("10.1.1.1", "admin", "admin") pool = {"name": "pool1", @@ -80,13 +80,13 @@ def __init__(self, resource_type): self.resource_type = resource_type def create(self, bigip, model): - u"""Create/update resource (e.g., pool) on a BIG-IP® system. + u"""Create/update resource (e.g., pool) on a BIG-IP system. First checks to see if resource has been created and creates it if not. :param bigip: BigIP instance to use for creating resource. - :param model: Dictionary of BIG-IP® attributes to add resource. Must + :param model: Dictionary of BIG-IP attributes to add resource. Must include name and partition. :returns: created or updated resource object. """ @@ -101,7 +101,7 @@ def exists(self, bigip, name=None, partition=None): return resource.exists(name=name, partition=partition) def delete(self, bigip, name=None, partition=None): - u"""Delete a resource on a BIG-IP® system. + u"""Delete a resource on a BIG-IP system. Checks if resource exists and deletes it. Returns without error if resource does not exist. @@ -116,10 +116,10 @@ def delete(self, bigip, name=None, partition=None): obj.delete() def load(self, bigip, name=None, partition=None): - u"""Retrieve a BIG-IP® resource from a BIG-IP®. + u"""Retrieve a BIG-IP resource from a BIG-IP. Populates a resource object with attributes for instance on a - BIG-IP® system. + BIG-IP system. :param bigip: BigIP instance to use for creating resource. :param name: Name of resource to load. @@ -130,13 +130,13 @@ def load(self, bigip, name=None, partition=None): return resource.load(name=name, partition=partition) def update(self, bigip, model): - u"""Update a resource (e.g., pool) on a BIG-IP® system. + u"""Update a resource (e.g., pool) on a BIG-IP system. - Modifies a resource on a BIG-IP® system using attributes + Modifies a resource on a BIG-IP system using attributes defined in the model object. :param bigip: BigIP instance to use for creating resource. - :param model: Dictionary of BIG-IP® attributes to update resource. + :param model: Dictionary of BIG-IP attributes to update resource. Must include name and partition in order to identify resource. """ partition = None @@ -148,9 +148,9 @@ def update(self, bigip, model): return resource def get_resources(self, bigip, partition=None): - u"""Retrieve a collection BIG-IP® of resources from a BIG-IP®. + u"""Retrieve a collection BIG-IP of resources from a BIG-IP. - Generates a list of resources objects on a BIG-IP® system. + Generates a list of resources objects on a BIG-IP system. :param bigip: BigIP instance to use for creating resource. :param name: Name of resource to load. diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/selfips.py b/f5_openstack_agent/lbaasv2/drivers/bigip/selfips.py index cfb72ee73..9c40ebcc9 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/selfips.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/selfips.py @@ -140,7 +140,7 @@ def assure_bigip_selfip(self, bigip, service, subnetinfo): def _get_bigip_selfip_address(self, bigip, subnet): u"""Ensure a selfip address is allocated on Neutron network.""" - # Get ip address for selfip to use on BIG-IP®. + # Get ip address for selfip to use on BIG-IP. selfip_address = "" selfip_name = "local-" + bigip.device_name + "-" + subnet['id'] ports = self.driver.plugin_rpc.get_port_by_name(port_name=selfip_name) diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/service_adapter.py b/f5_openstack_agent/lbaasv2/drivers/bigip/service_adapter.py index a78788e23..874a44433 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/service_adapter.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/service_adapter.py @@ -28,9 +28,9 @@ class UnsupportedProtocolException(Exception): class ServiceModelAdapter(object): - """Class to translate LBaaS service objects to BIG-IP® model objects. + """Class to translate LBaaS service objects to BIG-IP model objects. - Creates BIG-IP® model objects (dictionary of resource attributes) given + Creates BIG-IP model objects (dictionary of resource attributes) given an LBaaS service objet. """ diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/virtual_address.py b/f5_openstack_agent/lbaasv2/drivers/bigip/virtual_address.py index 4bb073e01..0cd9d1566 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/virtual_address.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/virtual_address.py @@ -24,9 +24,9 @@ class VirtualAddress(object): - u"""Class to translate LBaaS loadbalancer objects to BIG-IP® virtual address. + u"""Class to translate LBaaS loadbalancer objects to BIG-IP virtual address. - Creates BIG-IP® virtual address objects given an LBaaS service object. + Creates BIG-IP virtual address objects given an LBaaS service object. """ def __init__(self, adapter, loadbalancer): diff --git a/f5_openstack_agent/lbaasv2/drivers/bigip/vlan_binding.py b/f5_openstack_agent/lbaasv2/drivers/bigip/vlan_binding.py index d13796150..562d96563 100644 --- a/f5_openstack_agent/lbaasv2/drivers/bigip/vlan_binding.py +++ b/f5_openstack_agent/lbaasv2/drivers/bigip/vlan_binding.py @@ -44,8 +44,8 @@ def __init__(self, conf, driver): LOG.debug('interface_port_static_mappings not configured') def register_bigip_interfaces(self): - # Delayed binding BIG-IP® ports will be called - # after BIG-IP® endpoints are registered. + # Delayed binding BIG-IP ports will be called + # after BIG-IP endpoints are registered. if not self.__initialized__bigip_ports: for bigip in self.driver.get_all_bigips(): diff --git a/f5_openstack_agent/utils/debug_bundler.py b/f5_openstack_agent/utils/debug_bundler.py index 5d0612c25..2cf25afc4 100644 --- a/f5_openstack_agent/utils/debug_bundler.py +++ b/f5_openstack_agent/utils/debug_bundler.py @@ -1,5 +1,5 @@ # coding=utf-8 -# Copyright 2016 F5 Networks Inc. +# Copyright 2016-2017 F5 Networks Inc. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -35,7 +35,7 @@ def __init__(self, command_args): self.no_log_files = command_args.no_log_files def _save_pip_list(self, tar): - '''Dump a pip list, containing packages and versions. + '''Dump a pip list containing packages and versions. :param dest: unicode -- directory of dumped pip list :param tar: tarfile object -- tar where pip list dump will be added @@ -52,7 +52,7 @@ def _save_pip_list(self, tar): return sorted_pkgs def _tar_config_files(self, tar): - '''Add config files specified to tarfile + '''Add specified config files to tarfile :param tar: tarfile object -- tar where config files will be added ''' @@ -67,7 +67,7 @@ def _tar_config_files(self, tar): self._add_file_to_tar(cfg_dir, cfg_file, tar) def _tar_log_files(self, tar): - '''Add log files specified to tarfile + '''Add specified log files to tarfile :param tar: tarfile object -- tar where log files will be added ''' @@ -125,19 +125,19 @@ def produce_bundle(self): if __name__ == "__main__": parser = argparse.ArgumentParser( - description='Bundle important info for troubleshooting purposes.' + description='Bundles important info for troubleshooting purposes.' ) parser.add_argument( '--no-config-files', action='store_true', - help='Include this option if you would not like configuration ' - 'files included in your bundle (they will by default).' + help='Use this option to exclude configuration files' + 'from your bundle (they are included by default).' ) parser.add_argument( '--no-log-files', action='store_true', - help='Include this option if you would not like log files included ' - 'in your bundle (they will by default).' + help='Use this option to exclude log files from your bundle' + '(they are included by default).' ) parser.add_argument( 'tar_dest', help='Directory of bundle produced by this script.' diff --git a/requirements.docs.txt b/requirements.docs.txt index 8de7879c0..a624c4e53 100644 --- a/requirements.docs.txt +++ b/requirements.docs.txt @@ -1,2 +1,4 @@ -Sphinx>=1.5.5 +Sphinx>=1.6.2 git+https://github.com/f5devcentral/f5-sphinx-theme@master +cloud_sptheme +sphinxjp.themes.basicstrap diff --git a/test/send_to_driver/test_listener.py b/test/send_to_driver/test_listener.py index 60fd642ee..79448a4e3 100644 --- a/test/send_to_driver/test_listener.py +++ b/test/send_to_driver/test_listener.py @@ -37,7 +37,7 @@ def test_create_listener(bigip): # create partition lb_service.prep_service(service, bigips) - # create BIG-IP® virtual servers + # create BIG-IP virtual servers listeners = service["listeners"] loadbalancer = service["loadbalancer"]