Merge pull request #59 from jputrino/feature.user-guide

Add user guide (and a bunch of background stuff)

docs/conf.py

@@ -22,10 +22,6 @@
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('.'))
 
-from version import OPENSTACK_RELEASE
-from version import VERSION
-
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -38,6 +34,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
+    'sphinx.ext.doctest',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -64,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '7.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.1'
+release = 'v7.0.1'
 
 # OpenStack release
 openstack_release = "Kilo"
@@ -302,4 +299,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+# intersphinx_mapping = {'https://docs.python.org/': None}

docs/f5-supported-index.rst

@@ -0,0 +1,17 @@
+.. _f5-supported_home:
+
+F5®-Supported Heat Templates
+============================
+
+.. include:: ../f5_supported/README.rst
+    :start-line: 3
+
+
+The following templates are supported by F5®:
+
+.. toctree::
+    :titlesonly:
+    :glob:
+
+    templates/supported/*
+

docs/how-to_launch-bigip-standalone-2nic.rst

@@ -0,0 +1,65 @@
+.. _how-to_launch-standalone-bigip-2nic:
+
+Launch a Standalone, 2-NIC BIG-IP® VE Using Heat
+------------------------------------------------
+
+The standalone, 2-nic deployment template uses an existing BIG-IP® VE image to launch and configure a standalone VE. This template requires an external (physical) network and one internal network. The BIG-IP® receives a floating IP address from the external network; traffic from the insternal network passes through the BIG-IP®, allowing `LTM® <https://www.f5.com/pdf/products/big-ip-local-traffic-manager-ds.pdf>`_ services to be applied.
+
+Deploy BIG-IP® VE using the standalone, 2-nic template
+``````````````````````````````````````````````````````
+
+1. In Horizon, go to :guilabel:`Orchestration` --> :guilabel:`Stacks`.
+
+2. Click :guilabel:`Launch Stack`.
+
+3. Choose the :guilabel:`Template File` -- :file:`f5_ve_standalone_3_nics.yaml` -- from its location on your machine, then click :guilabel:`Next`.
+
+    .. note::
+
+        You will not be able to use the template by entering its GitHub URL because GitHub uses https. You must save the file locally and upload it.
+
+4. Next, you will need to provide the necessary information for the Heat engine to build your stack. You can use the table below as a worksheet to gather all of the necessary information ahead of time.
+
+
+    .. list-table:: Configuration Items
+        :widths: 30, 30
+        :header-rows: 1
+
+        * - Configuration Item
+          - Entry/Description
+        * - Stack Name
+          - big-ip_ve_standalone_3_nic
+        * - Creation Timeout (minutes)
+          - 60
+        * - Password for user "admin"
+          - <your OpenStack password>
+        * - F5 VE Image
+          - select the VE image
+        * - F5 VE Flavor
+          - select the appropriate flavor (default is m1.medium)
+        * - F5 FW Root SSH Key Name
+          - select the appropriate SSH key
+        * - F5 VE Admin User Password
+          - assing a password for the VE's admin user
+        * - F5 VE Root User Password
+          - assign a password for the VE's root user
+        * - Primary VE License Base Key
+          - the license Base Key sent to you by F5 support
+        * - External Network Name
+          - select the external network
+        * - VE Management Network
+          - select the name of the management network to be used by the VE
+        * - VE Network for the 1.1 Interface
+          - select an internal network (e.g., client)
+        * - VE Network Name for the 1.1 Interface
+          - enter a name for the network (e.g., 'network-1.1')
+        * - Default Gateway IP
+          - enter the IP address of your physical network's default gateway (if applicable)
+
+5. Click :guilabel:`Launch`. The Heat engine then creates your stack; the status changes to :guilabel:`Create complete` when it is finished.
+
+Caveats
+```````
+
+VE images come in 3 different sizes: LTM, ALL, and 1SLOT. Each has its own size requirements; see the F5® OpenStack `BIG-IP® flavor matrix <http://f5-openstack-docs.readthedocs.org/en/latest/guides/openstack_big-ip_flavors.html>`_ for more information. To create a new image in Horizon, go to :guilabel:`System` --> :guilabel:`Flavors` and click :guilabel:`Create Flavor`.
+

docs/how-to_launch-bigip-standalone-3nic.rst

@@ -0,0 +1,83 @@
+.. _how-to_launch-standalone-bigip-3nic:
+
+Launch a Standalone, 3-NIC BIG-IP® VE Using Heat
+------------------------------------------------
+
+The standalone, 3-nic deployment template uses an existing BIG-IP® VE image to launch and configure a standalone VE. This template requires an external (physical) network and two internal networks (ours are called 'client' and 'server'). The BIG-IP® receives a floating IP address from the external network; traffic from the client and server networks passes through the BIG-IP®, allowing `LTM® <https://www.f5.com/pdf/products/big-ip-local-traffic-manager-ds.pdf>`_ services to be applied. The client and server networks do not need to be able to communicate with each other; they just need to be able to communicate with the BIG-IP®.
+
+Deploy BIG-IP® VE using the standalone, 3-nic template
+``````````````````````````````````````````````````````
+
+1. In Horizon, go to :guilabel:`Orchestration` --> :guilabel:`Stacks`.
+
+2. Click :guilabel:`Launch Stack`.
+
+3. Choose the :guilabel:`Template File` -- :file:`f5_ve_standalone_3_nics.yaml` -- from its location on your machine, then click :guilabel:`Next`.
+
+    .. note::
+
+        You will not be able to use the template by entering its GitHub URL because GitHub uses https. You must save the file locally and upload it.
+
+4. Next, you will need to provide the necessary information for the Heat engine to build your stack. You can use the table below as a worksheet to gather all of the necessary information ahead of time.
+
+
+    .. list-table:: Configuration Items
+        :widths: 30, 30
+        :header-rows: 1
+
+        * - Configuration Item
+          - Entry/Description
+        * - Stack Name
+          - big-ip_ve_standalone_3_nic
+        * - Creation Timeout (minutes)
+          - 60
+        * - Password for user "admin"
+          - <your OpenStack password>
+        * - F5 VE Image
+          - select the VE image
+        * - F5 VE Flavor
+          - select the appropriate flavor (default is m1.medium)
+        * - F5 FW Root SSH Key Name
+          - select the appropriate SSH key
+        * - F5 VE Admin User Password
+          - <VE password for admin user>
+        * - F5 VE Root User Password
+          - <VE password for root user>
+        * - Primary VE License Base Key
+          - the license Base Key sent to you by F5 support
+        * - External Network Name
+          - select the external network
+        * - VE Management Network
+          - select the name of the management network to be used by the VE
+        * - VE Network for the 1.1 Interface
+          - select an internal network (e.g., client)
+        * - VE Network Name for the 1.1 Interface
+          - enter a name for the network (e.g., 'network-1.1')
+        * - VE Network for the 1.2 Interface
+          - select an internal network (e.g., server)
+        * - VE Network Name for the 1.2 Interface
+          - enter a name for the network (e.g., 'network-1.2')
+        * - Default Gateway IP
+          - enter the IP address of your physical network's default gateway (if applicable)
+
+5. Click :guilabel:`Launch`. The Heat engine then creates your stack; the status changes to :guilabel:`Create complete` when it is finished.
+
+Caveats
+```````
+
+VE images come in 3 different sizes: LTM, ALL, and 1SLOT. Each has its own size requirements; see the F5® OpenStack `BIG-IP® flavor matrix <http://f5-openstack-docs.readthedocs.org/en/latest/guides/openstack_big-ip_flavors.html>`_ for more information. To create a new image in Horizon, go to :guilabel:`System` --> :guilabel:`Flavors` and click :guilabel:`Create Flavor`.
+
+
+
+
+.. the following items are being removed from the template:
+    * - HTTP proxy Host to use to acquire resources
+      - ???
+    * - HTTP proxy Port to use to acquire resources
+      - default is 8080
+    * - HTTP Proxy Script URL for F5 License Client
+      - ???
+    * - License Activation Host
+      - ???
+    * - License Activation Port
+      - default is 443

docs/how-to_onboard-ve-image.rst

@@ -0,0 +1,76 @@
+.. _how-to_onboard-ve:
+
+Onboarding a VE Image in OpenStack
+----------------------------------
+
+In order to use a BIG-IP® VE image in OpenStack, it first has to be made 'OpenStack-ready'. The VE image patch template (:file:`patch_upload_ve_image.yaml`) uses a Ubuntu image as a TMOS VE image onboarding server to convert the image for use in OpenStack. You will need to use an SSH key for authentication.
+
+.. seealso::
+
+    :ref:`Add a Ubuntu image to Glance <add-ubuntu-image-glance>`
+
+    :ref:`Add an SSH key to Horizon <add-ssh-key-horizon>`
+
+
+Import the VE Image
+```````````````````
+
+Follow the steps below to launch a Heat stack to import the VE image. Once the VE image appears in :guilabel:`Images`, you can safely delete the stack.
+
+1. In Horizon, go to :guilabel:`Orchestration` --> :guilabel:`Stacks`.
+
+2. Click :guilabel:`Launch Stack`.
+
+3. Choose the :guilabel:`Template File` -- :file:`patch_upload_ve_image.yaml` from its location on your machine, then click :guilabel:`Next`.
+
+    .. note::
+
+        You will not be able to use the template by entering its GitHub URL because GitHub uses https. You must save the file locally and upload it.
+
+4. Next, you will need to provide the necessary information for the Heat engine to build your stack.
+
+    .. list-table:: Configuration Items
+        :widths: 30, 30
+        :header-rows: 1
+
+        * - Configuration Item
+          - Entry/Description
+        * - Stack Name
+          - big-ip_ve_11.6_LTM
+        * - Creation Timeout (minutes)
+          - 60
+        * - Password for user "admin"
+          - <your OpenStack password>
+        * - Onboard Ubuntu Image
+          - select the image you created
+        * - F5 Onboard Server Flavor
+          - default: m1.medium
+        * - F5 Onboard Server Management Network
+          - choose any network from the drop-down
+        * - SSH Key
+          - select an SSH key pair
+        * - Keystone Auth URL
+          - enter your Keystone authentication URL; usually, this uses the same IP address at which you log in to Horizon
+        * - Image Import Tenant
+          - the project into which you want to import the VE image; it will be imported into your current project by default
+        * - Image Import User
+          - defaults to the user account you are logged in to
+        * - Image Import User Password
+          - the password for the user into whose account the image will be imported
+        * - Image Prep URL
+          - automatically populated with the URL of the F5 Networks® image prep GitHub repo
+        * - F5 VE Image URL
+          - must be a publicly-accessible (i.e., ``http``) URL from which the F5 VE image can be downloaded
+        * - F5 VE Image Name
+          - the VE file name (e.g., :file:`BIGIP-11.6.0.6.0.442.qcow2`)
+
+5. Click :guilabel:`Launch`.
+
+
+The Heat engine will create your stack; the status changes to :guilabel:`Create complete` when it is finished.
+
+Caveats
+```````
+
+There is a `known issue <https://bugs.launchpad.net/glance/+bug/1476770>`_ with ``python-glanceclient`` that returns in an unspecified error after you click :guilabel:`Launch`. You may need to upgrade in order to resolve this issue.
+

docs/includes/concept_f5-bigip-ve-templates.rst

@@ -0,0 +1,21 @@
+.. _ve_home:
+
+F5® BIG-IP® VE Templates
+========================
+
+Overview
+--------
+
+The templates within the VE directory can be used to prepare BIG-IP® Virtual Edition (VE) images for use and to launch VE in OpenStack clouds.
+
+.. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    Image Templates <concept_ve-images>
+    Plugin Templates <concept_f5-iapps-plugins>
+    Common Templates <concept_ve-common>
+    Standalone Templates <concept_ve-standalone>
+
+
+

docs/includes/concept_f5-iapps-plugins.rst

@@ -0,0 +1,35 @@
+.. _f5-heat-plugins:
+
+F5® Heat Plugin Example Templates
+=================================
+
+Before You Start
+----------------
+
+The ``f5_plugins`` templates require the F5® Heat plugins found in `F5Networks/f5-openstack-heat-plugins <https://github.com/F5Networks/f5-openstack-heat-plugins>`_. See the `project documentation <http://f5-openstack-heat-plugins.readthedocs.org/en/>`_ for installation instructions.
+
+Overview
+--------
+The ``f5_plugins`` templates use F5® iApps® and Heat templates in tandem to deploy BIG-IP® resources in OpenStack. F5®'s iApps® contain specific configuration deployments, represented as executable TCL scripts. Each of these scripts is called an iApps® template.
+
+There are two ways to use F5®'s Heat plugins to deploy iApps® templates. The first, demonstrated in :file:`deploy_composite_iapp.yaml` and :file:`F5::Sys::iAppCompositeTemplate`, combines Heat and iApps® templates to create an iApps® service on a BIG-IP®.
+
+The second method is a simple dump of the iApp®'s full TCL file into the Heat template, as we've done in :file:`F5::Sys::iAppFullTemplate`. Once the template has been created on the BIG-IP®, it can be executed to create the iApp® Service (``F5::Sys::iAppService``).
+
+We've provided example templates for each supported F5® plugin. Feel free to browse around the repo (`F5Networks/f5-openstack-heat/unsupported/f5_plugins <https://github.com/F5Networks/f5-openstack-heat/tree/develop/unsupported/f5_plugins>`_); you can fork the project and tweak the parameters and resources to suit your needs.
+
+
+iApps® APIC Integration Template
+--------------------------------
+
+This Heat template deploys an iApps® template that can automate and orchestrate Layer 4-7 applications service deployments using F5® BIG-IP®/BIG-IQ® products. Additionally, it can serve as a common integration point for third party SDN/NFV/Automation/Orchestration products.
+
+There are two major components to this deployment. The iApps® template deploys first, then the Heat template creates the service.  When the service is deployed, the Heat template passes in a set of default answers to the choices/questions posed in the APL section of the iApps® template. These answers, which can be in the form of variables, tables, and/or lists, can be altered as needed to suit your needs.
+
+For more information about this iApp® and its author, please see `appsvcs_integration_iapp <https://github.com/0xHiteshPatel/appsvcs_integration_iapp>`_ on GitHub.
+
+Heat Composition
+----------------
+
+These templates are examples of how to perform Heat template composition. This is not the only way to do Heat template composition. Refer to the `Openstack Template Composition <http://docs.openstack.org/developer/heat/template_guide/composition.html>` for more information on this way to compose Heat templates. These are specifically using composition and the F5® Heat plugins to stand up a load-balancing scenario. The client issues a curl request to the virtual IP address, and that request is proxied to the backend pool member. Both the client and the server are created in the template, but the underlying private networks they connect to are not. The other important note is that the VE itself is not created in these templates, we are merely interacting with an existing VE.
+

docs/includes/concept_learning-stacks.rst

@@ -0,0 +1,7 @@
+Learning Stacks
+===============
+
+If you are just starting out with orchestration in OpenStack, you can use our Learning Stacks template(s) to get an idea of how a Heat stack manages resources.
+
+.. include:: concept_ubuntu-classic-stack.rst
+

docs/unsupported/service-providers_doc.rst → docs/includes/concept_service-providers.rst

@@ -8,5 +8,5 @@ Service Providers
 .. toctree::
     :titlesonly:
 
-    sp-gi-simplify
+    concept_sp-gi-simplify
 

unsupported/learning_stacks/ubuntu_classic_stack.rst → docs/includes/concept_ubuntu-classic-stack.rst

@@ -1,3 +1,7 @@
+.. toctree::
+    :maxdepth: 2
+
+
 Ubuntu Classic Stack
 ====================
 
@@ -14,4 +18,4 @@ Multi-homing
 ------------
 All instances in this stack are multi-homed. This is important to know because default Ubuntu cloud images for 14.04 do not support multiple nics out of the box. You can solve these problems by referring to this `cloudify blog <http://getcloudify.org/2015/05/18/openstack-neutron-nova-cloud-vm-networking-network-automation-orchestration.html>`_ regarding a multi-homed instance in OpenStack.
 
-We have solved this problem by using `ifplugd <http://0pointer.de/lennart/projects/ifplugd/>`_, a service baked into the image that waits for any and all interfaces to be hotplugged. Cloud-init creates the port on the OpenStack side for this instance to connect to the additional networks and configures the ethernet devices to be available on the instance. It does not, however, bring up the additional interfaces. That's the job of ``ifplugd``, or of your startup script and whatever you choose to use.
+We have solved this problem by using `ifplugd <http://linux.die.net/man/8/ifplugd>`_, a service baked into the image that waits for any and all interfaces to be hotplugged. Cloud-init creates the port on the OpenStack side for this instance to connect to the additional networks and configures the ethernet devices to be available on the instance. It does not, however, bring up the additional interfaces. That's the job of ``ifplugd``, or of your startup script and whatever you choose to use.

unsupported/ve/common/common_templates.rst → docs/includes/concept_ve-common.rst

@@ -1,3 +1,5 @@
+.. _ve-common:
+
 BIG-IP® VE Common Template Resources
 ====================================
 
@@ -33,3 +35,5 @@ The templates here named :file:`f5_ve_standalone_*_nic.yaml` contain the ``OS::N
 .. warning::
 
     Do not modify these templates unless you've had experience both with Heat and complex network configurations.
+
+