From 01a5f36dfc9c0d6cc89433e3801aa56e92403f71 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Fri, 29 Jul 2016 15:37:06 -0700 Subject: [PATCH] Added NFV features to the Fuel User Guide - Added sections that describe how to configure and deploy an environment with NFV features. - Added the snippet folder for reusable content - Modified conf.py to exclude the snippets folder to get rid of the toctree error message. Change-Id: Ia287897e1638ecf066a7cd0b6f9c13d56d7d4e8f --- conf.py | 2 +- .../fuel-user-guide/configure-environment.rst | 2 +- .../configure-environment/nfv.rst | 41 ++++++++ .../nfv/nfv-configure-dpdk-nic.rst | 28 ++++++ .../nfv/nfv-configure-sriov-nic.rst | 30 ++++++ .../nfv/nfv-configure.rst | 97 +++++++++++++++++++ .../fuel-user-guide/create-environment.rst | 1 + .../prerequisites-limitations.rst | 38 ++++++++ .../fuel-user-guide/manage-environment.rst | 2 + .../enable-experimental-features.rst | 28 ++++++ .../manage-environment/nfv-run.rst | 23 +++++ .../nfv-run/nfv-associate-floating-ip.rst | 23 +++++ .../nfv-run/nfv-create-flavor.rst | 34 +++++++ .../nfv-run/nfv-create-sriov-port.rst | 21 ++++ .../nfv-run/nfv-launch-vm.rst | 27 ++++++ .../manage-environment/nfv-run/nfv-verify.rst | 19 ++++ .../notes/enable-experimental-features.rst | 6 ++ 17 files changed, 420 insertions(+), 2 deletions(-) create mode 100644 userdocs/fuel-user-guide/configure-environment/nfv.rst create mode 100644 userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-dpdk-nic.rst create mode 100644 userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-sriov-nic.rst create mode 100644 userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure.rst create mode 100644 userdocs/fuel-user-guide/create-environment/prerequisites-limitations.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/enable-experimental-features.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-associate-floating-ip.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-flavor.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-sriov-port.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-launch-vm.rst create mode 100644 userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-verify.rst create mode 100644 userdocs/snippets/notes/enable-experimental-features.rst diff --git a/conf.py b/conf.py index 6ce77e57e..cf4a39326 100644 --- a/conf.py +++ b/conf.py @@ -75,7 +75,7 @@ language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', '.*'] +exclude_patterns = ['_build', '.*', 'userdocs/snippets/*'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/userdocs/fuel-user-guide/configure-environment.rst b/userdocs/fuel-user-guide/configure-environment.rst index 0185c5a51..02e68d73c 100644 --- a/userdocs/fuel-user-guide/configure-environment.rst +++ b/userdocs/fuel-user-guide/configure-environment.rst @@ -38,4 +38,4 @@ This section includes the following topics: configure-environment/settings.rst configure-environment/dns-ntp-support.rst configure-environment/configure-multipath.rst - + configure-environment/nfv.rst diff --git a/userdocs/fuel-user-guide/configure-environment/nfv.rst b/userdocs/fuel-user-guide/configure-environment/nfv.rst new file mode 100644 index 000000000..fe7096af4 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/nfv.rst @@ -0,0 +1,41 @@ +.. _nfv-overview: + +Configure workload acceleration +------------------------------- + +NFV workload acceleration may significantly improve network +performance in certain configurations. Specifically, NFV workflow acceleration +is beneficial in optimizing tenant traffic in private networks. +Fuel allows system administrators to enable NFV features, such as Huge Pages, +Single-Root I/O Virtualization (SR-IOV), Data Plane Developer Kit (DPDK), +Non-Uniform Memory Access (NUMA) and CPU pining automatically during +the deployment of an OpenStack environment. + +Huge Pages accelerate the translation of virtual address of a Linux proccess +to +physical address which enables virtual machine memory allocation from a +predefined memory pool. Using Huge Pages helps to prevent hypervisor overhead +that memory paging often causes. + +NUMA and CPU pinning bind together virtual and physical hardware by allowing +to assign predefined CPU cores to particular flavors of virtual machines and +optimizing memory access from these cores. + +Both DPDK and SR-IOV assist in increasing network performance. DPDK +increases network on a software level by connecting virtual network interfaces +faces to physical network interfaces through Open Virtual Switch (OVS), while +SR-IOV provides almost wire network speed by mapping virtual network +interfaces to a physical hardware directly. DPDK is hardware-agnostic, +while SR-IOV relies on specific hardware implementation. +DPDK provides more agility in terms of traffic filtering and QoS. However, it +results in greater CPU consumption than SR-IOV. DPDK-enabled OVS uses +less CPU than non-DPDK OVS. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 2 + + nfv/nfv-configure.rst + nfv/nfv-configure-sriov-nic.rst + nfv/nfv-configure-dpdk-nic.rst diff --git a/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-dpdk-nic.rst b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-dpdk-nic.rst new file mode 100644 index 000000000..95884b322 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-dpdk-nic.rst @@ -0,0 +1,28 @@ +.. _nfv-configure-dpdk-nic: + +Configure DPDK network interface +-------------------------------- + +When configuring network for DPDK, you must place private network +on the same interface on which you enable DPDK. For better network +performance and redundancy, you can bind two network interfaces in one. + +**To configure DPDK network interface:** + +#. Log in to the Fuel web UI. +#. Click :guilabel:`Nodes`. +#. Select the node on which you enabled DPDK. +#. Click :guilabel:`Configure Interfaces`. +#. Optionally, bond network interfaces. +#. On the required network interface, enable DPDK by clicking + :guilabel:`Disabled` next to :guilabel:`DPDK`. +#. Drag and drop the **Private** network to the DPDK-enabled network + interface. +#. Optionally, adjust the name of the physical network. +#. Click :guilabel:`Apply`. +#. Configure the rest of the environment settings as required and deploy + the environment as described in :ref:`deploy-env`. + +.. seealso:: + + - :ref:`nfv-run-vm` diff --git a/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-sriov-nic.rst b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-sriov-nic.rst new file mode 100644 index 000000000..7de9a1b61 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure-sriov-nic.rst @@ -0,0 +1,30 @@ +.. _nfv-configure-sriov-nic: + +Configure SR-IOV network interface +---------------------------------- + +When configuring network for SR-IOV, you must place private network +on a separate interface from the interface on which you enable SR-IOV. +This enables VLAN network traffic to flow to Open vSwitch while having +SR-IOV enabled. + +**To configure SR-IOV network interface:** + +#. Log in to the Fuel web UI. +#. Click :guilabel:`Nodes`. +#. Select the node on which you enable SR-IOV. +#. Click :guilabel:`Configure Interfaces`. +#. Drag and drop the Private network to a network interface. +#. On a separate network interface, enable SR-IOV by clicking + :guilabel:`Disabled` next to :guilabel:`SR-IOV`. +#. Select the :guilabel:`Enabled` checkbox. +#. Type the number of virtual functions that do not exceed the number + provided by Fuel. +#. Optionally, adjust the name of the physical network. +#. Click :guilabel:`Apply`. +#. Configure the rest of the environment settings as required and deploy + the environment as described in :ref:`deploy-env`. + +.. seealso:: + + - :ref:`nfv-run-vm` diff --git a/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure.rst b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure.rst new file mode 100644 index 000000000..8303ed810 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/nfv/nfv-configure.rst @@ -0,0 +1,97 @@ +.. _nfv-configure: + +Configure SR-IOV and DPDK +------------------------- + +Before completing the steps described in this section, verify that your +environment meets the requirements in :ref:`prerequisites-limitations`. + +To use NFV features, you must configure corresponding settings before you +deploy an OpenStack environment. The values for DPDK, Huge Pages, SR-IOV, +and CPU pinning differ for each workload. + +When calculating resource for DPDK, consider that one DPDK core +can process 3 Mpps of network traffic. For example, if you have 2 x 10 GB +network interfaces in bond, you have throughput of 24 Mpps. Therefore, you +need to assign 8 DPDK cores (8 x 3). + +All NFV features can be enabled on the same compute node or on separate +compute nodes and do not depend on each other. However, the procedure and +requirements are similar. + +For the purpose of example, the following configuration is used: + +.. list-table:: **SR-IOV example configuration** + :widths: 10 10 + :header-rows: 1 + + * - Parameter + - Description + * - Number of controller nodes + - 1 + * - Number of compute nodes + - 2 + * - CPU + - 40 x 2.30 GHz + * - Memory + - 256 GB + * - Nova CPU pinning + - 36 + * - Nova Huge Pages + - 2 MB x 65000 = 130,000 GB + * - DPDK CPU pinning + - 4 + * - DPDK Huge Pages + - 2048 MB + +.. include:: /userdocs/snippets/notes/enable-experimental-features.rst + +**To configure DPDK and SRIOV:** + +#. Log in to the Fuel web UI. +#. Click :guilabel:`New OpenStack Environment`. +#. Follow the prompts of the wizard to create a new OpenStack environment. +#. In the :menuselection:`Compute` screen, select :guilabel:`QEMU-KVM`. +#. In the :menuselection:`Networking Setup` screen, select + :guilabel:`Neutron with VLAN segmentation`. +#. Complete the configuration wizard as required and click :guilabel:`Create`. +#. Select the environment you have just created. +#. Click :menuselection:`Settings -> Compute`. +#. Select :guilabel:`KVM`. +#. Click :guilabel:`Save Settings`. +#. Click :menuselection:`Nodes -> Add Nodes`. +#. Create controller and compute nodes. + + Select the hardware that supports NFV features for the nodes on which you + want to enable SR-IOV. + +#. Click the node settings icon. +#. Enable Huge Pages and CPU pinning: + + * For SR-IOV: + + #. Click :guilabel:`Node Attributes`. + #. Type the Nova CPU pinning and Nova Huge Pages parameters. + #. Click :guilabel:`Save Settings`. + + * For DPDK: + + #. Click :guilabel:`Node Attributes`. + #. Type the Nova CPU pinning and Nova Huge Pages parameters. + #. Type the DPDK CPU pinning and DPDK Huge Pages parameters. + #. Click :guilabel:`Save Settings`. + + * For Huge Pages: + + #. Click :guilabel:`Node Attributes`. + #. Type the required Huge pages value. + + * For CPU pinning: + + #. Click :guilabel:`Node Attributes`. + #. Type the required CPU pinning value. + +#. Proceed to: + + * For SR-IOV, see: :ref:`nfv-configure-sriov-nic`. + * For DPDK, see: :ref:`nfv-configure-dpdk-nic`. diff --git a/userdocs/fuel-user-guide/create-environment.rst b/userdocs/fuel-user-guide/create-environment.rst index bc9e9c663..a882dd9ba 100644 --- a/userdocs/fuel-user-guide/create-environment.rst +++ b/userdocs/fuel-user-guide/create-environment.rst @@ -20,6 +20,7 @@ This section includes the following topics: .. toctree:: :maxdepth: 3 + create-environment/prerequisites-limitations.rst create-environment/start-create-env.rst create-environment/change-password.rst diff --git a/userdocs/fuel-user-guide/create-environment/prerequisites-limitations.rst b/userdocs/fuel-user-guide/create-environment/prerequisites-limitations.rst new file mode 100644 index 000000000..c4a605e38 --- /dev/null +++ b/userdocs/fuel-user-guide/create-environment/prerequisites-limitations.rst @@ -0,0 +1,38 @@ +.. _prerequisites-limitations: + +Prerequisites and limitations +----------------------------- + +Fuel enables you to deploy environments with multiple features. However, +some of the features have special requirements. Depending on the environment +configuration that you want to create, verify that your hardware, as well as +your software configurations meet the corresponding requirements. + +.. list-table:: **Prerequisites and limitations for VMware vSphere** + :widths: 10 10 + :header-rows: 1 + + * - Prerequisites + - Limitations + * - * Fuel NSX or Fuel DVS plugin installed before you start creating an + OpenStack environment. + * A pre-configured VMware vSphere environment that includes VMware + ESXi and VMware vCenter cluster. + - N/A + +.. list-table:: **Prerequisites and limitations for workload acceleration** + :widths: 10 10 + :header-rows: 1 + + * - Prerequisites + - Limitations + * - * CPU pinning supported for all platforms. + * For Huge Pages size of 2 MB all platforms are supported. + * For Huge Pages size of 1 GB, CPU of the selected platform must + support this feature. + * SR-IOV requires SR-IOV support by the physical NIC, as well as + support for Huge Pages in CPU and motherboard. + * DPDK requires Huge Pages, NIC support, Intel CPU (or QEMU) + NFV workload. + - * VMware vSphere as a compute back end is not supported. + * The only supported network topology is Neutron with VLAN segmentation diff --git a/userdocs/fuel-user-guide/manage-environment.rst b/userdocs/fuel-user-guide/manage-environment.rst index 9effebabb..feeeb1400 100644 --- a/userdocs/fuel-user-guide/manage-environment.rst +++ b/userdocs/fuel-user-guide/manage-environment.rst @@ -17,3 +17,5 @@ This section includes the following sections: manage-environment/cgroups/cgroups-modify-single-node.rst manage-environment/cgroups/cgroups-example.rst manage-environment/role-operations.rst + manage-environment/nfv-run.rst + manage-environment/enable-experimental-features.rst diff --git a/userdocs/fuel-user-guide/manage-environment/enable-experimental-features.rst b/userdocs/fuel-user-guide/manage-environment/enable-experimental-features.rst new file mode 100644 index 000000000..47c23910f --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/enable-experimental-features.rst @@ -0,0 +1,28 @@ +.. _enable-experimental-features: + +Enable experimental features +---------------------------- + +Experimental features provide useful functionality, but may not be mature +enough for environments that require high levels of stability. By default, +experimental features are disabled. You can enable experimental features +during the installation of the Fuel Master or anytime later. + +**To enable experimental features:** + +#. Log in to the Fuel Master node CLI. +#. Open the ``/etc/fuel/astute.yaml`` file for editing. +#. Add ``experimental`` to the ``feature_groups`` section. + + **Example:** + + :: + + "FEATURE_GROUPS": + - experimental + +#. Apply the Nailgun Puppet manifest by typing: + + :: + + puppet apply /etc/puppet/modules/fuel/examples/nailgun.pp diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run.rst new file mode 100644 index 000000000..64ebf1537 --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run.rst @@ -0,0 +1,23 @@ +.. _nfv-run-vm: + +Run an instance with workload acceleration +========================================== + +If you have enabled workflow acceleration, you can create a flavor +that supports such NFV features as DPDK and SR-IOV and deploy instances +using that flavor. + +You can configure the corresponding settings in the OpenStack Dashboard +(Horizon) or through the CLI. This section only describes the Horizon +configuration. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 2 + + nfv-run/nfv-create-flavor.rst + nfv-run/nfv-create-sriov-port.rst + nfv-run/nfv-launch-vm.rst + nfv-run/nfv-associate-floating-ip.rst + nfv-run/nfv-verify.rst diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-associate-floating-ip.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-associate-floating-ip.rst new file mode 100644 index 000000000..3bd44479f --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-associate-floating-ip.rst @@ -0,0 +1,23 @@ +.. _nfv-associate-floating-ip: + +Allocate a floating IP address to a virtual machine +------------------------------------------------------ + +You can associate or change a floating IP address of a virtual machine +any time after virtual machine creation. Although, Mirantis OpenStack +automatically assigns a private IP address to a VM at the moment of creation, +you may want to assign a floating IP address, so that the VM can communicate +with external networks. + +**To allocate a floating IP address with a virtual machine:** + +#. Log in to Horizon. +#. Click :menuselection:`Project --> Compute --> Instances`. +#. Click the arrow in the :guilabel:`Actions` column. +#. Select :guilabel:`Associate Floating IP`. + + The Manage Floating IP Associations wizard starts. + +#. In the IP Address field, click :guilabel:`+`. +#. Click :guilabel:`Allocate IP`. +#. Click :guilabel:`Associate`. diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-flavor.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-flavor.rst new file mode 100644 index 000000000..fc09eb82f --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-flavor.rst @@ -0,0 +1,34 @@ +.. _nfv-create-flavor: + +Create a workload-accelerated instance flavor +--------------------------------------------- + +If you have enabled such NFV features as SR-IOV or/and DPDK during the +environment deployment, you can create workload-accelerated instance flavors +and use them to deploy virtual machines with +mission-crtitical applications. + +**To create a workload-accelerated instance flavor:** + +#. Log in to Horizon. +#. Select :menuselection:`System --> Flavors`. +#. Click :guilabel:`Create Flavor`. +#. In the Create Flavor wizard, specify number of vCPUs, RAM, and Root + Disk size. +#. Click :guilabel:`Create Flavor`. +#. On the :guilabel:`Flavors` screen, click :guilabel:`No` under + metadata for the flavor you created in previous step. +#. Add the required metadata parameters and values. + + **Example:** + + * ``hw:mem_page_size`` - large + * ``hw:cpu_policy`` - dedicated + +#. If you plan to use DPDK, proceed to :ref:`nfv-launch-vm`. +#. If you plan to use SR-IOV, proceed to :ref:`nfv-create-sriov-port`. + +.. seealso:: + + - `OpenStack Administrator Guide + `_ diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-sriov-port.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-sriov-port.rst new file mode 100644 index 000000000..7b19a3d29 --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-create-sriov-port.rst @@ -0,0 +1,21 @@ +.. _nfv-create-sriov-port: + +Create a network port for SR-IOV +-------------------------------- + +To use SR-IOV, create a network port in the ``admin_internal_net``. + +**To creat a network port for SR-IOV:** + +#. Log in to Horizon. +#. Click :guilabel:`Networks`. +#. Select the ``admin_internal_net`` network. +#. Click :guilabel:`Create Port`. +#. In the Create Port wizard, fill the following fields: + + * :guilabel:`Name` - for example: ``sriov-port`` + * :guilabel:`Admin State` - UP + * :guilabel:`Binding: VNIC Type` - Direct + +#. Click :guilabel:`Create Port`. +#. Proceed to :ref:`nfv-launch-vm`. diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-launch-vm.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-launch-vm.rst new file mode 100644 index 000000000..b09a19543 --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-launch-vm.rst @@ -0,0 +1,27 @@ +.. _nfv-launch-vm: + +Launch a virtual machine with workload acceleration +--------------------------------------------------- + +After you created a specific VM flavor as described in +:ref:`nfv-create-flavor` and configured an SR-IOV port as +described in :ref:`nfv-create-sriov-port` (for SR-IOV only), +you can launch a virtual machine that supports DPDK and SR-IOV +NFV features. + +**To launch a virtual machine with workload acceleration:** + +#. Log in to Horizon. +#. On the :guilabel:`Source` screen, select a virtual machine template in + QCOW2 format. +#. On the :guilabel:`Flavor` screen, select a flavor that has + workload-accelerated features enabled. +#. Select from the following options: + + * If you want to use DPDK, on the :guilabel:`Networks` screen, select the + ``admin_internal_net``. + * If you want to use SR-IOV, on the :guilabel:`Network Ports` screen, + select the SR-IOV port that you have created in + :ref:`nfv-create-sriov-port`. +#. Launch the instance. +#. Proceed to :ref:`nfv-associate-floating-ip`. diff --git a/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-verify.rst b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-verify.rst new file mode 100644 index 000000000..4c17fd6fa --- /dev/null +++ b/userdocs/fuel-user-guide/manage-environment/nfv-run/nfv-verify.rst @@ -0,0 +1,19 @@ +.. _nfv-verify: + +Verify a virtual instance with accelerated workloads +---------------------------------------------------- + +After you configured and launched a virtual instance, you can verify +that NFV features are enabled on the machine. + +**To verify a virtual instance with accelerated workloads:** + +#. Log in to the virtual instance CLI using SSH as root. + + Use the floating IP address. + +#. View the information about the CPU architecture: + + :: + + lscpu diff --git a/userdocs/snippets/notes/enable-experimental-features.rst b/userdocs/snippets/notes/enable-experimental-features.rst new file mode 100644 index 000000000..9173dad42 --- /dev/null +++ b/userdocs/snippets/notes/enable-experimental-features.rst @@ -0,0 +1,6 @@ +.. note:: + This feature requires Fuel experimental features mode to be enabled. + If you have not enabled Fuel experimental features + during installation of the Fuel Master node, enable it before you complete + the tasks in this section as described in + :ref:`enable-experimental-features`.