diff --git a/doc/source/reference/bare-metal/index.rst b/doc/source/reference/bare-metal/index.rst new file mode 100644 index 0000000000..f0cf85dc31 --- /dev/null +++ b/doc/source/reference/bare-metal/index.rst @@ -0,0 +1,11 @@ +========== +Bare Metal +========== + +This section describes configuring bare metal provisioning +such as Ironic. + +.. toctree:: + :maxdepth: 1 + + ironic-guide diff --git a/doc/source/reference/ironic-guide.rst b/doc/source/reference/bare-metal/ironic-guide.rst similarity index 98% rename from doc/source/reference/ironic-guide.rst rename to doc/source/reference/bare-metal/ironic-guide.rst index a08d0c4e5d..9a8c6f88f4 100644 --- a/doc/source/reference/ironic-guide.rst +++ b/doc/source/reference/bare-metal/ironic-guide.rst @@ -1,8 +1,8 @@ .. _ironic-guide: -=============== -Ironic in Kolla -=============== +================================ +Ironic - Bare Metal provisioning +================================ Overview ~~~~~~~~ diff --git a/doc/source/reference/hyperv-guide.rst b/doc/source/reference/compute/hyperv-guide.rst similarity index 98% rename from doc/source/reference/hyperv-guide.rst rename to doc/source/reference/compute/hyperv-guide.rst index d337915931..4039c90d26 100644 --- a/doc/source/reference/hyperv-guide.rst +++ b/doc/source/reference/compute/hyperv-guide.rst @@ -1,8 +1,8 @@ .. _hyperv-guide: -==================== -Nova-HyperV in Kolla -==================== +=========== +Nova HyperV +=========== Overview ~~~~~~~~ diff --git a/doc/source/reference/compute/index.rst b/doc/source/reference/compute/index.rst new file mode 100644 index 0000000000..ba17f64e0e --- /dev/null +++ b/doc/source/reference/compute/index.rst @@ -0,0 +1,15 @@ +======= +Compute +======= + +This section describes configuring nova hypervisors and +compute services like HyperV, XenServer and so on. + +.. toctree:: + :maxdepth: 1 + + hyperv-guide + nova-fake-driver + vmware-guide + xenserver-guide + zun-guide diff --git a/doc/source/reference/nova-fake-driver.rst b/doc/source/reference/compute/nova-fake-driver.rst similarity index 100% rename from doc/source/reference/nova-fake-driver.rst rename to doc/source/reference/compute/nova-fake-driver.rst diff --git a/doc/source/reference/vmware-guide.rst b/doc/source/reference/compute/vmware-guide.rst similarity index 99% rename from doc/source/reference/vmware-guide.rst rename to doc/source/reference/compute/vmware-guide.rst index 7878f1f550..b3f4983997 100644 --- a/doc/source/reference/vmware-guide.rst +++ b/doc/source/reference/compute/vmware-guide.rst @@ -1,8 +1,8 @@ .. _vmware-guide: -=============== -VMware in Kolla -=============== +====== +VMware +====== Overview ~~~~~~~~ diff --git a/doc/source/reference/xenserver-guide.rst b/doc/source/reference/compute/xenserver-guide.rst similarity index 98% rename from doc/source/reference/xenserver-guide.rst rename to doc/source/reference/compute/xenserver-guide.rst index 0a212e55cc..70d5ac8708 100644 --- a/doc/source/reference/xenserver-guide.rst +++ b/doc/source/reference/compute/xenserver-guide.rst @@ -1,8 +1,8 @@ .. _XenServer-guide: -================== -XenServer in Kolla -================== +========= +XenServer +========= Overview ======== diff --git a/doc/source/reference/zun-guide.rst b/doc/source/reference/compute/zun-guide.rst similarity index 96% rename from doc/source/reference/zun-guide.rst rename to doc/source/reference/compute/zun-guide.rst index 26e7c98e76..18e607e5e4 100644 --- a/doc/source/reference/zun-guide.rst +++ b/doc/source/reference/compute/zun-guide.rst @@ -1,6 +1,6 @@ -============ -Zun in Kolla -============ +======================= +Zun - Container service +======================= "Zun is an OpenStack Container service. It aims to provide an OpenStack API for provisioning and managing containerized @@ -12,7 +12,7 @@ Preparation and Deployment -------------------------- Zun requires kuryr and etcd services, for more information about how to -configure kuryr refer to :doc:`kuryr-guide`. +configure kuryr refer to :doc:`../containers/kuryr-guide`. To allow Zun Compute connect to the Docker Daemon, add the following in the ``docker.service`` file on each zun-compute node. diff --git a/doc/source/reference/containers/index.rst b/doc/source/reference/containers/index.rst new file mode 100644 index 0000000000..54d94e65ee --- /dev/null +++ b/doc/source/reference/containers/index.rst @@ -0,0 +1,11 @@ +========== +Containers +========== + +This section describes configuring and running container based services +including kuryr. + +.. toctree:: + :maxdepth: 1 + + kuryr-guide diff --git a/doc/source/reference/kuryr-guide.rst b/doc/source/reference/containers/kuryr-guide.rst similarity index 95% rename from doc/source/reference/kuryr-guide.rst rename to doc/source/reference/containers/kuryr-guide.rst index 7071af3d49..68532e9120 100644 --- a/doc/source/reference/kuryr-guide.rst +++ b/doc/source/reference/containers/kuryr-guide.rst @@ -1,6 +1,6 @@ -============== -Kuryr in Kolla -============== +============================ +Kuryr - Container networking +============================ "Kuryr is a Docker network plugin that uses Neutron to provide networking services to Docker containers. It provides containerized images for the common diff --git a/doc/source/reference/external-mariadb-guide.rst b/doc/source/reference/databases/external-mariadb-guide.rst similarity index 100% rename from doc/source/reference/external-mariadb-guide.rst rename to doc/source/reference/databases/external-mariadb-guide.rst diff --git a/doc/source/reference/databases/index.rst b/doc/source/reference/databases/index.rst new file mode 100644 index 0000000000..d9c135f04a --- /dev/null +++ b/doc/source/reference/databases/index.rst @@ -0,0 +1,10 @@ +========= +Databases +========= + +This section describes configuration of database services. + +.. toctree:: + :maxdepth: 1 + + external-mariadb-guide diff --git a/doc/source/reference/bifrost.rst b/doc/source/reference/deployment-and-bootstrapping/bifrost.rst similarity index 97% rename from doc/source/reference/bifrost.rst rename to doc/source/reference/deployment-and-bootstrapping/bifrost.rst index 422eb570f3..2385199fed 100644 --- a/doc/source/reference/bifrost.rst +++ b/doc/source/reference/deployment-and-bootstrapping/bifrost.rst @@ -1,6 +1,6 @@ -============= -Bifrost Guide -============= +=========================== +Bifrost - Standalone Ironic +=========================== From the ``Bifrost`` developer documentation: Bifrost (pronounced bye-frost) is a set of Ansible playbooks that automates @@ -63,7 +63,7 @@ Preparation Prepare the Control Host ------------------------ -Follow the **Install dependencies** section of the :doc:`../user/quickstart` +Follow the **Install dependencies** section of the :doc:`../../user/quickstart` guide instructions to set up kolla and kolla-ansible dependencies. Follow the instructions in either the **Install kolla for development** section or the **Install kolla for deployment or evaluation** section to install kolla @@ -180,8 +180,8 @@ host on which bifrost is deployed. Prepare Kolla-Ansible Configuration ----------------------------------- -Follow the instructions in :doc:`../user/quickstart` to prepare kolla-ansible's -global configuration file ``globals.yml``. For bifrost, the +Follow the instructions in :doc:`../../user/quickstart` to prepare +kolla-ansible's global configuration file ``globals.yml``. For bifrost, the ``bifrost_network_interface`` variable should be set to the name of the interface that will be used to provision bare metal cloud hosts if this is different than ``network_interface``. For example to use ``eth1``: diff --git a/doc/source/reference/deployment-and-bootstrapping/index.rst b/doc/source/reference/deployment-and-bootstrapping/index.rst new file mode 100644 index 0000000000..3f03172ba1 --- /dev/null +++ b/doc/source/reference/deployment-and-bootstrapping/index.rst @@ -0,0 +1,11 @@ +============================ +Deployment and bootstrapping +============================ + +This section describes deployment and provisioning of baremetal control plane +hosts. + +.. toctree:: + :maxdepth: 1 + + bifrost diff --git a/doc/source/reference/deployment-config/index.rst b/doc/source/reference/deployment-config/index.rst new file mode 100644 index 0000000000..29afc39f97 --- /dev/null +++ b/doc/source/reference/deployment-config/index.rst @@ -0,0 +1,11 @@ +======================== +Deployment configuration +======================== + +This section describes configuration of kolla containers, including limiting +their resources. + +.. toctree:: + :maxdepth: 1 + + resource-constraints diff --git a/doc/source/reference/resource-constraints.rst b/doc/source/reference/deployment-config/resource-constraints.rst similarity index 95% rename from doc/source/reference/resource-constraints.rst rename to doc/source/reference/deployment-config/resource-constraints.rst index 3649f26d0c..4413b59920 100644 --- a/doc/source/reference/resource-constraints.rst +++ b/doc/source/reference/deployment-config/resource-constraints.rst @@ -1,8 +1,8 @@ .. _resource-constraints: -===================================== -Resource Constraints in Kolla Ansible -===================================== +==================== +Resource Constraints +==================== Overview ~~~~~~~~ diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 71feacc8ab..0e1211be07 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -1,32 +1,18 @@ -Projects Deployment References -============================== +=========================================== +Projects Deployment Configuration Reference +=========================================== .. toctree:: :maxdepth: 2 - ceph-guide - external-ceph-guide - central-logging-guide - external-mariadb-guide - cinder-guide - cinder-guide-hnas - designate-guide - hyperv-guide - ironic-guide - manila-guide - manila-hnas-guide - monasca-guide - nova-fake-driver - swift-guide - bifrost - networking-guide - kuryr-guide - zun-guide - osprofiler-guide - skydive-guide - vmware-guide - tacker-guide - xenserver-guide - horizon-guide - resource-constraints - glance-guide + compute/index + bare-metal/index + storage/index + networking/index + shared-services/index + orchestration-and-nfv/index + logging-and-monitoring/index + containers/index + databases/index + deployment-config/index + deployment-and-bootstrapping/index diff --git a/doc/source/reference/central-logging-guide.rst b/doc/source/reference/logging-and-monitoring/central-logging-guide.rst similarity index 99% rename from doc/source/reference/central-logging-guide.rst rename to doc/source/reference/logging-and-monitoring/central-logging-guide.rst index cb494db718..20f3c26f8d 100644 --- a/doc/source/reference/central-logging-guide.rst +++ b/doc/source/reference/logging-and-monitoring/central-logging-guide.rst @@ -1,8 +1,8 @@ .. _central-logging-guide: -======================== -Central Logging in Kolla -======================== +=============== +Central Logging +=============== An OpenStack deployment generates vast amounts of log data. In order to successfully monitor this and use it to diagnose problems, the standard "ssh diff --git a/doc/source/reference/logging-and-monitoring/index.rst b/doc/source/reference/logging-and-monitoring/index.rst new file mode 100644 index 0000000000..2ab7bd4a4c --- /dev/null +++ b/doc/source/reference/logging-and-monitoring/index.rst @@ -0,0 +1,14 @@ +====================== +Logging and monitoring +====================== + +This section describes configuration for the different +logging and monitoring services available in kolla. + +.. toctree:: + :maxdepth: 1 + + central-logging-guide + monasca-guide + osprofiler-guide + skydive-guide diff --git a/doc/source/reference/monasca-guide.rst b/doc/source/reference/logging-and-monitoring/monasca-guide.rst similarity index 99% rename from doc/source/reference/monasca-guide.rst rename to doc/source/reference/logging-and-monitoring/monasca-guide.rst index db140fa05a..3af3399464 100644 --- a/doc/source/reference/monasca-guide.rst +++ b/doc/source/reference/logging-and-monitoring/monasca-guide.rst @@ -1,8 +1,8 @@ .. _monasca-guide: -================ -Monasca in Kolla -================ +============================ +Monasca - Monitoring service +============================ Overview ~~~~~~~~ diff --git a/doc/source/reference/osprofiler-guide.rst b/doc/source/reference/logging-and-monitoring/osprofiler-guide.rst similarity index 93% rename from doc/source/reference/osprofiler-guide.rst rename to doc/source/reference/logging-and-monitoring/osprofiler-guide.rst index 2b8284b5d9..9951d44721 100644 --- a/doc/source/reference/osprofiler-guide.rst +++ b/doc/source/reference/logging-and-monitoring/osprofiler-guide.rst @@ -1,8 +1,8 @@ .. _osprofiler-guide: -=================== -OSprofiler in Kolla -=================== +==================================== +OSprofiler - Cross-project profiling +==================================== Overview ~~~~~~~~ diff --git a/doc/source/reference/skydive-guide.rst b/doc/source/reference/logging-and-monitoring/skydive-guide.rst similarity index 90% rename from doc/source/reference/skydive-guide.rst rename to doc/source/reference/logging-and-monitoring/skydive-guide.rst index 56732bb6ec..686031107a 100644 --- a/doc/source/reference/skydive-guide.rst +++ b/doc/source/reference/logging-and-monitoring/skydive-guide.rst @@ -1,8 +1,8 @@ .. _skydive-guide: -================ -Skydive in Kolla -================ +==================================== +Skydive - Real time network analyzer +==================================== Overview ~~~~~~~~ diff --git a/doc/source/reference/networking-guide.rst b/doc/source/reference/networking-guide.rst deleted file mode 100644 index 67a8063da6..0000000000 --- a/doc/source/reference/networking-guide.rst +++ /dev/null @@ -1,490 +0,0 @@ -.. _networking-guide: - -=================== -Networking in Kolla -=================== - -Kolla deploys Neutron by default as OpenStack networking component. -This section describes configuring and running Neutron extensions like -LBaaS, Networking-SFC, QoS, and so on. - -Enabling Provider Networks -========================== - -Provider networks allow to connect compute instances directly to physical -networks avoiding tunnels. This is necessary for example for some performance -critical applications. Only administrators of OpenStack can create such -networks. For provider networks compute hosts must have external bridge -created and configured by Ansible tasks like it is already done for tenant -DVR mode networking. Normal tenant non-DVR networking does not need external -bridge on compute hosts and therefore operators don't need additional -dedicated network interface. - -To enable provider networks, modify the ``/etc/kolla/globals.yml`` file -as the following example shows: - -.. code-block:: yaml - - enable_neutron_provider_networks: "yes" - -Enabling Neutron Extensions -=========================== - -Networking-SFC -~~~~~~~~~~~~~~ - -Preparation and deployment --------------------------- - -Modify the ``/etc/kolla/globals.yml`` file as the following example shows: - -.. code-block:: yaml - - enable_neutron_sfc: "yes" - -Verification ------------- - -For setting up a testbed environment and creating a port chain, please refer -to `networking-sfc documentation -`__. - -Neutron VPNaaS (VPN-as-a-Service) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Preparation and deployment --------------------------- - -Modify the ``/etc/kolla/globals.yml`` file as the following example shows: - -.. code-block:: yaml - - enable_neutron_vpnaas: "yes" - -Verification ------------- - -VPNaaS is a complex subject, hence this document provides directions for a -simple smoke test to verify the service is up and running. - -On the network node(s), the ``neutron_vpnaas_agent`` should be up (image naming -and versioning may differ depending on deploy configuration): - -.. code-block:: console - - # docker ps --filter name=neutron_vpnaas_agent - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 97d25657d55e operator:5000/kolla/oraclelinux-source-neutron-vpnaas-agent:4.0.0 "kolla_start" 44 minutes ago Up 44 minutes neutron_vpnaas_agent - -Kolla-Ansible includes a small script that can be used in tandem with -``tools/init-runonce`` to verify the VPN using two routers and two Nova VMs: - -.. code-block:: console - - tools/init-runonce - tools/init-vpn - -Verify both VPN services are active: - -.. code-block:: console - - # neutron vpn-service-list - - +--------------------------------------+----------+--------------------------------------+--------+ - | id | name | router_id | status | - +--------------------------------------+----------+--------------------------------------+--------+ - | ad941ec4-5f3d-4a30-aae2-1ab3f4347eb1 | vpn_west | 051f7ce3-4301-43cc-bfbd-7ffd59af539e | ACTIVE | - | edce15db-696f-46d8-9bad-03d087f1f682 | vpn_east | 058842e0-1d01-4230-af8d-0ba6d0da8b1f | ACTIVE | - +--------------------------------------+----------+--------------------------------------+--------+ - -Two VMs can now be booted, one on vpn_east, the other on vpn_west, and -encrypted ping packets observed being sent from one to the other. - -For more information on this and VPNaaS in Neutron refer to the -`Neutron VPNaaS Testing `__ -and the `OpenStack wiki `_. - -Networking-ODL -~~~~~~~~~~~~~~ - -Preparation and deployment --------------------------- - -Modify the ``/etc/kolla/globals.yml`` file as the following example shows: - -.. code-block:: yaml - - enable_opendaylight: "yes" - -Networking-ODL is an additional Neutron plugin that allows the OpenDaylight -SDN Controller to utilize its networking virtualization features. -For OpenDaylight to work, the Networking-ODL plugin has to be installed in -the ``neutron-server`` container. In this case, one could use the -neutron-server-opendaylight container and the opendaylight container by -pulling from Kolla dockerhub or by building them locally. - -OpenDaylight ``globals.yml`` configurable options with their defaults include: - -.. code-block:: yaml - - opendaylight_mechanism_driver: "opendaylight_v2" - opendaylight_l3_service_plugin: "odl-router_v2" - opendaylight_acl_impl: "learn" - enable_opendaylight_qos: "no" - enable_opendaylight_l3: "yes" - enable_opendaylight_legacy_netvirt_conntrack: "no" - opendaylight_port_binding_type: "pseudo-agentdb-binding" - opendaylight_features: "odl-mdsal-apidocs,odl-netvirt-openstack" - opendaylight_allowed_network_types: '"flat", "vlan", "vxlan"' - -Clustered OpenDaylight Deploy ------------------------------ - -High availability clustered OpenDaylight requires modifying the inventory file -and placing three or more hosts in the OpenDaylight or Networking groups. - -.. note:: - - The OpenDaylight role will allow deploy of one or three plus hosts for - OpenDaylight/Networking role. - -Verification ------------- - -Verify the build and deploy operation of Networking-ODL containers. Successful -deployment will bring up an Opendaylight container in the list of running -containers on network/opendaylight node. - -For the source code, please refer to the following link: -https://github.com/openstack/networking-odl - -OVS with DPDK -~~~~~~~~~~~~~ - -Introduction ------------- - -Open vSwitch (ovs) is an open source software virtual switch developed -and distributed via openvswitch.org. -The Data Plane Development Kit (dpdk) is a collection of userspace -libraries and tools that facilitate the development of high-performance -userspace networking applications. - -As of the ovs 2.2 release, the ovs netdev datapath has supported integration -with dpdk for accelerated userspace networking. As of the pike release -of kolla support for deploying ovs with dpdk (ovs-dpdk) has been added -to kolla ansible. The ovs-dpdk role introduced in the pike release has been -tested on centos 7 and ubuntu 16.04 hosts, however, ubuntu is recommended due -to conflicts with the cgroup configuration created by the default systemd -version shipped with centos 7. - -Prerequisites -------------- - -DPDK is a high-performance userspace networking library, as such it has -several requirements to function correctly that are not required when -deploying ovs without dpdk. - -To function efficiently one of the mechanisms dpdk uses to accelerate -memory access is the utilisation of kernel hugepages. The use of hugepage -memory minimises the chance of a translation lookaside buffer(TLB) miss when -translating virtual to physical memory as it increases the total amount of -addressable memory that can be cached via the TLB. Hugepage memory pages are -unswappable contiguous blocks of memory of typically 2MiB or 1GiB in size, -that can be used to facilitate efficient sharing of memory between guests and -a vSwitch or DMA mapping between physical nics and the userspace ovs datapath. - -To deploy ovs-dpdk on a platform a proportion of system memory should -be allocated hugepages. While it is possible to allocate hugepages at runtime -it is advised to allocate them via the kernel command line instead to prevent -memory fragmentation. This can be achieved by adding the following to the grub -config and regenerating your grub file. - -.. code-block:: console - - default_hugepagesz=2M hugepagesz=2M hugepages=25000 - -As dpdk is a userspace networking library it requires userspace compatible -drivers to be able to control the physical interfaces on the platform. -dpdk technically support 3 kernel drivers ``igb_uio``,``uio_pci_generic``, and -``vfio_pci``. -While it is technically possible to use all 3 only ``uio_pci_generic`` and -``vfio_pci`` are recommended for use with kolla. ``igb_uio`` is BSD licenced -and distributed as part of the dpdk library. While it has some advantages over -``uio_pci_generic`` loading the ``igb_uio`` module will taint the kernel and -possibly invalidate distro support. To successfully deploy ``ovs-dpdk``, -``vfio_pci`` or ``uio_pci_generic`` kernel module must be present on the -platform. Most distros include ``vfio_pci`` or ``uio_pci_generic`` as part of -the default kernel though on some distros you may need to install -``kernel-modules-extra`` or the distro equivalent prior to running -:command:`kolla-ansible deploy`. - -Installation ------------- - -To enable ovs-dpdk, add the following configuration to -``/etc/kolla/globals.yml`` file: - -.. code-block:: yaml - - ovs_datapath: "netdev" - enable_ovs_dpdk: yes - enable_openvswitch: yes - tunnel_interface: "dpdk_bridge" - neutron_bridge_name: "dpdk_bridge" - -Unlike standard Open vSwitch deployments, the interface specified by -neutron_external_interface should have an ip address assigned. -The ip address assigned to neutron_external_interface will be moved to -the "dpdk_bridge" as part of deploy action. -When using ovs-dpdk the tunnel_interface must be an ovs bridge with a physical -interfaces attached for tunnelled traffic to be accelerated by dpdk. -Note that due to a limitation in ansible variable names which excluded -the use of - in a variable name it is not possible to use the default -br-ex name for the neutron_bridge_name or tunnel_interface. - -At present, the tunnel interface ip is configured using network manager on -on ubuntu and systemd on centos family operating systems. systemd is used -to work around a limitation of the centos network manager implementation which -does not consider the creation of an ovs bridge to be a hotplug event. In -the future, a new config option will be introduced to allow systemd to be used -on all host distros for those who do not wish to enable the network manager -service on ubuntu. - -Limitations ------------ - -Reconfiguration from kernel ovs to ovs dpdk is currently not supported. -Changing ovs datapaths on a deployed node requires neutron config changes -and libvirt xml changes for all running instances including a hard reboot -of the vm. - -When upgrading ovs-dpdk it should be noted that this will always involve -a dataplane outage. Unlike kernel OVS the dataplane for ovs-dpdk executes in -the ovs-vswitchd process. This means the lifetime of the dpdk dataplane is -tied to the lifetime of the ovsdpdk_vswitchd container. As such it is -recommended to always evacuate all vm workloads from a node running ovs-dpdk -prior to upgrading. - -On ubuntu network manager is required for tunnel networking. -This requirement will be removed in the future. - -Neutron SRIOV -~~~~~~~~~~~~~ - -Preparation and deployment --------------------------- - -SRIOV requires specific NIC and BIOS configuration and is not supported on all -platforms. Consult NIC and platform specific documentation for instructions -on enablement. - -Modify the ``/etc/kolla/globals.yml`` file as the following example shows: - -.. code-block:: yaml - - enable_neutron_sriov: "yes" - -Modify the ``/etc/kolla/config/neutron/ml2_conf.ini`` file and add -``sriovnicswitch`` to the ``mechanism_drivers``. Also, the provider -networks used by SRIOV should be configured. Both flat and VLAN are configured -with the same physical network name in this example: - -.. path /etc/kolla/config/neutron/ml2_conf.ini -.. code-block:: ini - - [ml2] - mechanism_drivers = openvswitch,l2population,sriovnicswitch - - [ml2_type_vlan] - network_vlan_ranges = sriovtenant1:1000:1009 - - [ml2_type_flat] - flat_networks = sriovtenant1 - -Add ``PciPassthroughFilter`` to scheduler_default_filters - -The ``PciPassthroughFilter``, which is required by Nova Scheduler service -on the Controller, should be added to ``scheduler_default_filters`` - -Modify the ``/etc/kolla/config/nova.conf`` file and add -``PciPassthroughFilter`` to ``scheduler_default_filters``. this filter is -required by The Nova Scheduler service on the controller node. - -.. path /etc/kolla/config/nova.conf -.. code-block:: ini - - [DEFAULT] - scheduler_default_filters = , PciPassthroughFilter - scheduler_available_filters = nova.scheduler.filters.all_filters - -Edit the ``/etc/kolla/config/nova.conf`` file and add PCI device whitelisting. -this is needed by OpenStack Compute service(s) on the Compute. - -.. path /etc/kolla/config/nova.conf -.. code-block:: ini - - [pci] - passthrough_whitelist = [{"devname": "ens785f0", "physical_network": "sriovtenant1"}] - -Modify the ``/etc/kolla/config/neutron/sriov_agent.ini`` file. Add physical -network to interface mapping. Specific VFs can also be excluded here. Leaving -blank means to enable all VFs for the interface: - -.. path /etc/kolla/config/neutron/sriov_agent.ini -.. code-block:: ini - - [sriov_nic] - physical_device_mappings = sriovtenant1:ens785f0 - exclude_devices = - -Run deployment. - -Verification ------------- - -Check that VFs were created on the compute node(s). VFs will appear in the -output of both ``lspci`` and ``ip link show``. For example: - -.. code-block:: console - - # lspci | grep net - 05:10.0 Ethernet controller: Intel Corporation 82599 Ethernet Controller Virtual Function (rev 01) - - - # ip -d link show ens785f0 - 4: ens785f0: mtu 1500 qdisc mq master ovs-system state UP mode DEFAULT qlen 1000 - link/ether 90:e2:ba:ba:fb:20 brd ff:ff:ff:ff:ff:ff promiscuity 1 - openvswitch_slave addrgenmode eui64 - vf 0 MAC 52:54:00:36:57:e0, spoof checking on, link-state auto, trust off - vf 1 MAC 52:54:00:00:62:db, spoof checking on, link-state auto, trust off - vf 2 MAC fa:16:3e:92:cf:12, spoof checking on, link-state auto, trust off - vf 3 MAC fa:16:3e:00:a3:01, vlan 1000, spoof checking on, link-state auto, trust off - -Verify the SRIOV Agent container is running on the compute node(s): - -.. code-block:: console - - # docker ps --filter name=neutron_sriov_agent - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b03a8f4c0b80 10.10.10.10:4000/registry/centos-source-neutron-sriov-agent:17.04.0 "kolla_start" 18 minutes ago Up 18 minutes neutron_sriov_agent - -Verify the SRIOV Agent service is present and UP: - -.. code-block:: console - - # openstack network agent list - - +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ - | ID | Agent Type | Host | Availability Zone | Alive | State | Binary | - +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ - | 7c06bda9-7b87-487e-a645-cc6c289d9082 | NIC Switch agent | av09-18-wcp | None | :-) | UP | neutron-sriov-nic-agent | - +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ - -Create a new provider network. Set ``provider-physical-network`` to the -physical network name that was configured in ``/etc/kolla/config/nova.conf``. -Set ``provider-network-type`` to the desired type. If using VLAN, ensure -``provider-segment`` is set to the correct VLAN ID. This example uses ``VLAN`` -network type: - - -.. code-block:: console - - # openstack network create --project=admin \ - --provider-network-type=vlan \ - --provider-physical-network=sriovtenant1 \ - --provider-segment=1000 \ - sriovnet1 - -Create a subnet with a DHCP range for the provider network: - -.. code-block:: console - - # openstack subnet create --network=sriovnet1 \ - --subnet-range=11.0.0.0/24 \ - --allocation-pool start=11.0.0.5,end=11.0.0.100 \ - sriovnet1_sub1 - -Create a port on the provider network with ``vnic_type`` set to ``direct``: - -.. code-block:: console - - # openstack port create --network sriovnet1 --vnic-type=direct sriovnet1-port1 - -Start a new instance with the SRIOV port assigned: - -.. code-block:: console - - # openstack server create --flavor flavor1 \ - --image fc-26 \ - --nic port-id=`openstack port list | grep sriovnet1-port1 | awk '{print $2}'` \ - vm1 - -Verify the instance boots with the SRIOV port. Verify VF assignment by running -dmesg on the compute node where the instance was placed. - -.. code-block:: console - - # dmesg - [ 2896.849970] ixgbe 0000:05:00.0: setting MAC fa:16:3e:00:a3:01 on VF 3 - [ 2896.850028] ixgbe 0000:05:00.0: Setting VLAN 1000, QOS 0x0 on VF 3 - [ 2897.403367] vfio-pci 0000:05:10.4: enabling device (0000 -> 0002) - -For more information see `OpenStack SRIOV documentation `_. - -Nova SRIOV -~~~~~~~~~~ - -Preparation and deployment --------------------------- - -Nova provides a separate mechanism to attach PCI devices to instances that -is independent from Neutron. Using the PCI alias configuration option in -nova.conf, any PCI device (PF or VF) that supports passthrough can be attached -to an instance. One major drawback to be aware of when using this method is -that the PCI alias option uses a device's product id and vendor id only, -so in environments that have NICs with multiple ports configured for SRIOV, -it is impossible to specify a specific NIC port to pull VFs from. - -Modify the file ``/etc/kolla/config/nova.conf``. The Nova Scheduler service -on the control node requires the ``PciPassthroughFilter`` to be added to the -list of filters and the Nova Compute service(s) on the compute node(s) need -PCI device whitelisting. The Nova API service on the control node and the Nova -Compute service on the compute node also require the ``alias`` option under the -``[pci]`` section. The alias can be configured as 'type-VF' to pass VFs or -'type-PF' to pass the PF. Type-VF is shown in this example: - -.. path /etc/kolla/config/nova.conf -.. code-block:: ini - - [DEFAULT] - scheduler_default_filters = , PciPassthroughFilter - scheduler_available_filters = nova.scheduler.filters.all_filters - - [pci] - passthrough_whitelist = [{"vendor_id": "8086", "product_id": "10fb"}] - alias = [{"vendor_id":"8086", "product_id":"10ed", "device_type":"type-VF", "name":"vf1"}] - -Run deployment. - -Verification ------------- - -Create (or use an existing) flavor, and then configure it to request one PCI -device from the PCI alias: - -.. code-block:: console - - # openstack flavor set sriov-flavor --property "pci_passthrough:alias"="vf1:1" - -Start a new instance using the flavor: - -.. code-block:: console - - # openstack server create --flavor sriov-flavor --image fc-26 vm2 - -Verify VF devices were created and the instance starts successfully as in -the Neutron SRIOV case. - -For more information see `OpenStack PCI passthrough documentation `_. diff --git a/doc/source/reference/designate-guide.rst b/doc/source/reference/networking/designate-guide.rst similarity index 98% rename from doc/source/reference/designate-guide.rst rename to doc/source/reference/networking/designate-guide.rst index eda5476c4e..ab91cb632c 100644 --- a/doc/source/reference/designate-guide.rst +++ b/doc/source/reference/networking/designate-guide.rst @@ -1,8 +1,8 @@ .. _designate-guide: -================== -Designate in Kolla -================== +======================= +Designate - DNS service +======================= Overview ~~~~~~~~ diff --git a/doc/source/reference/networking/dpdk.rst b/doc/source/reference/networking/dpdk.rst new file mode 100644 index 0000000000..e0e1e19532 --- /dev/null +++ b/doc/source/reference/networking/dpdk.rst @@ -0,0 +1,113 @@ +.. _dpdk: + +==== +DPDK +==== + +Introduction +------------ + +Open vSwitch (ovs) is an open source software virtual switch developed +and distributed via openvswitch.org. +The Data Plane Development Kit (dpdk) is a collection of userspace +libraries and tools that facilitate the development of high-performance +userspace networking applications. + +As of the ovs 2.2 release, the ovs netdev datapath has supported integration +with dpdk for accelerated userspace networking. As of the pike release +of kolla support for deploying ovs with dpdk (ovs-dpdk) has been added +to kolla ansible. The ovs-dpdk role introduced in the pike release has been +tested on centos 7 and ubuntu 16.04 hosts, however, ubuntu is recommended due +to conflicts with the cgroup configuration created by the default systemd +version shipped with centos 7. + +Prerequisites +------------- + +DPDK is a high-performance userspace networking library, as such it has +several requirements to function correctly that are not required when +deploying ovs without dpdk. + +To function efficiently one of the mechanisms dpdk uses to accelerate +memory access is the utilisation of kernel hugepages. The use of hugepage +memory minimises the chance of a translation lookaside buffer(TLB) miss when +translating virtual to physical memory as it increases the total amount of +addressable memory that can be cached via the TLB. Hugepage memory pages are +unswappable contiguous blocks of memory of typically 2MiB or 1GiB in size, +that can be used to facilitate efficient sharing of memory between guests and +a vSwitch or DMA mapping between physical nics and the userspace ovs datapath. + +To deploy ovs-dpdk on a platform a proportion of system memory should +be allocated hugepages. While it is possible to allocate hugepages at runtime +it is advised to allocate them via the kernel command line instead to prevent +memory fragmentation. This can be achieved by adding the following to the grub +config and regenerating your grub file. + +.. code-block:: console + + default_hugepagesz=2M hugepagesz=2M hugepages=25000 + +As dpdk is a userspace networking library it requires userspace compatible +drivers to be able to control the physical interfaces on the platform. +dpdk technically support 3 kernel drivers ``igb_uio``,``uio_pci_generic``, and +``vfio_pci``. +While it is technically possible to use all 3 only ``uio_pci_generic`` and +``vfio_pci`` are recommended for use with kolla. ``igb_uio`` is BSD licenced +and distributed as part of the dpdk library. While it has some advantages over +``uio_pci_generic`` loading the ``igb_uio`` module will taint the kernel and +possibly invalidate distro support. To successfully deploy ``ovs-dpdk``, +``vfio_pci`` or ``uio_pci_generic`` kernel module must be present on the +platform. Most distros include ``vfio_pci`` or ``uio_pci_generic`` as part of +the default kernel though on some distros you may need to install +``kernel-modules-extra`` or the distro equivalent prior to running +:command:`kolla-ansible deploy`. + +Installation +------------ + +To enable ovs-dpdk, add the following configuration to +``/etc/kolla/globals.yml`` file: + +.. code-block:: yaml + + ovs_datapath: "netdev" + enable_ovs_dpdk: yes + enable_openvswitch: yes + tunnel_interface: "dpdk_bridge" + neutron_bridge_name: "dpdk_bridge" + +Unlike standard Open vSwitch deployments, the interface specified by +neutron_external_interface should have an ip address assigned. +The ip address assigned to neutron_external_interface will be moved to +the "dpdk_bridge" as part of deploy action. +When using ovs-dpdk the tunnel_interface must be an ovs bridge with a physical +interfaces attached for tunnelled traffic to be accelerated by dpdk. +Note that due to a limitation in ansible variable names which excluded +the use of - in a variable name it is not possible to use the default +br-ex name for the neutron_bridge_name or tunnel_interface. + +At present, the tunnel interface ip is configured using network manager on +on ubuntu and systemd on centos family operating systems. systemd is used +to work around a limitation of the centos network manager implementation which +does not consider the creation of an ovs bridge to be a hotplug event. In +the future, a new config option will be introduced to allow systemd to be used +on all host distros for those who do not wish to enable the network manager +service on ubuntu. + +Limitations +----------- + +Reconfiguration from kernel ovs to ovs dpdk is currently not supported. +Changing ovs datapaths on a deployed node requires neutron config changes +and libvirt xml changes for all running instances including a hard reboot +of the vm. + +When upgrading ovs-dpdk it should be noted that this will always involve +a dataplane outage. Unlike kernel OVS the dataplane for ovs-dpdk executes in +the ovs-vswitchd process. This means the lifetime of the dpdk dataplane is +tied to the lifetime of the ovsdpdk_vswitchd container. As such it is +recommended to always evacuate all vm workloads from a node running ovs-dpdk +prior to upgrading. + +On ubuntu network manager is required for tunnel networking. +This requirement will be removed in the future. diff --git a/doc/source/reference/networking/index.rst b/doc/source/reference/networking/index.rst new file mode 100644 index 0000000000..ad6bbdc98a --- /dev/null +++ b/doc/source/reference/networking/index.rst @@ -0,0 +1,18 @@ +========== +Networking +========== + +Kolla deploys Neutron by default as OpenStack networking component. +This section describes configuring and running Neutron extensions like +LBaaS, Networking-SFC, QoS, and so on. + + +.. toctree:: + :maxdepth: 1 + + designate-guide + dpdk + neutron-extensions + opendaylight + provider-networks + sriov diff --git a/doc/source/reference/networking/neutron-extensions.rst b/doc/source/reference/networking/neutron-extensions.rst new file mode 100644 index 0000000000..6b1d8b6ce8 --- /dev/null +++ b/doc/source/reference/networking/neutron-extensions.rst @@ -0,0 +1,80 @@ +.. _neutron-extensions: + +================== +Neutron Extensions +================== + +Networking-SFC +~~~~~~~~~~~~~~ + +Preparation and deployment +-------------------------- + +Modify the ``/etc/kolla/globals.yml`` file as the following example shows: + +.. code-block:: yaml + + enable_neutron_sfc: "yes" + +Verification +------------ + +For setting up a testbed environment and creating a port chain, please refer +to `networking-sfc documentation +`__. + +Neutron VPNaaS (VPN-as-a-Service) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Preparation and deployment +-------------------------- + +Modify the ``/etc/kolla/globals.yml`` file as the following example shows: + +.. code-block:: yaml + + enable_neutron_vpnaas: "yes" + +Verification +------------ + +VPNaaS is a complex subject, hence this document provides directions for a +simple smoke test to verify the service is up and running. + +On the network node(s), the ``neutron_vpnaas_agent`` should be up (image naming +and versioning may differ depending on deploy configuration): + +.. code-block:: console + + # docker ps --filter name=neutron_vpnaas_agent + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 97d25657d55e operator:5000/kolla/oraclelinux-source-neutron-vpnaas-agent:4.0.0 "kolla_start" 44 minutes ago Up 44 minutes neutron_vpnaas_agent + +Kolla-Ansible includes a small script that can be used in tandem with +``tools/init-runonce`` to verify the VPN using two routers and two Nova VMs: + +.. code-block:: console + + tools/init-runonce + tools/init-vpn + +Verify both VPN services are active: + +.. code-block:: console + + # neutron vpn-service-list + + +--------------------------------------+----------+--------------------------------------+--------+ + | id | name | router_id | status | + +--------------------------------------+----------+--------------------------------------+--------+ + | ad941ec4-5f3d-4a30-aae2-1ab3f4347eb1 | vpn_west | 051f7ce3-4301-43cc-bfbd-7ffd59af539e | ACTIVE | + | edce15db-696f-46d8-9bad-03d087f1f682 | vpn_east | 058842e0-1d01-4230-af8d-0ba6d0da8b1f | ACTIVE | + +--------------------------------------+----------+--------------------------------------+--------+ + +Two VMs can now be booted, one on vpn_east, the other on vpn_west, and +encrypted ping packets observed being sent from one to the other. + +For more information on this and VPNaaS in Neutron refer to the +`Neutron VPNaaS Testing `__ +and the `OpenStack wiki `_. diff --git a/doc/source/reference/networking/opendaylight.rst b/doc/source/reference/networking/opendaylight.rst new file mode 100644 index 0000000000..a7f34b825d --- /dev/null +++ b/doc/source/reference/networking/opendaylight.rst @@ -0,0 +1,56 @@ +.. _opendaylight: + +============================= +Opendaylight - SDN controller +============================= + +Preparation and deployment +-------------------------- + +Modify the ``/etc/kolla/globals.yml`` file as the following example shows: + +.. code-block:: yaml + + enable_opendaylight: "yes" + +Networking-ODL is an additional Neutron plugin that allows the OpenDaylight +SDN Controller to utilize its networking virtualization features. +For OpenDaylight to work, the Networking-ODL plugin has to be installed in +the ``neutron-server`` container. In this case, one could use the +neutron-server-opendaylight container and the opendaylight container by +pulling from Kolla dockerhub or by building them locally. + +OpenDaylight ``globals.yml`` configurable options with their defaults include: + +.. code-block:: yaml + + opendaylight_mechanism_driver: "opendaylight_v2" + opendaylight_l3_service_plugin: "odl-router_v2" + opendaylight_acl_impl: "learn" + enable_opendaylight_qos: "no" + enable_opendaylight_l3: "yes" + enable_opendaylight_legacy_netvirt_conntrack: "no" + opendaylight_port_binding_type: "pseudo-agentdb-binding" + opendaylight_features: "odl-mdsal-apidocs,odl-netvirt-openstack" + opendaylight_allowed_network_types: '"flat", "vlan", "vxlan"' + +Clustered OpenDaylight Deploy +----------------------------- + +High availability clustered OpenDaylight requires modifying the inventory file +and placing three or more hosts in the OpenDaylight or Networking groups. + +.. note:: + + The OpenDaylight role will allow deploy of one or three plus hosts for + OpenDaylight/Networking role. + +Verification +------------ + +Verify the build and deploy operation of Networking-ODL containers. Successful +deployment will bring up an Opendaylight container in the list of running +containers on network/opendaylight node. + +For the source code, please refer to the following link: +https://github.com/openstack/networking-odl diff --git a/doc/source/reference/networking/provider-networks.rst b/doc/source/reference/networking/provider-networks.rst new file mode 100644 index 0000000000..7d2a56ba8f --- /dev/null +++ b/doc/source/reference/networking/provider-networks.rst @@ -0,0 +1,21 @@ +.. _provider-networks: + +================= +Provider Networks +================= + +Provider networks allow to connect compute instances directly to physical +networks avoiding tunnels. This is necessary for example for some performance +critical applications. Only administrators of OpenStack can create such +networks. For provider networks compute hosts must have external bridge +created and configured by Ansible tasks like it is already done for tenant +DVR mode networking. Normal tenant non-DVR networking does not need external +bridge on compute hosts and therefore operators don't need additional +dedicated network interface. + +To enable provider networks, modify the ``/etc/kolla/globals.yml`` file +as the following example shows: + +.. code-block:: yaml + + enable_neutron_provider_networks: "yes" diff --git a/doc/source/reference/networking/sriov.rst b/doc/source/reference/networking/sriov.rst new file mode 100644 index 0000000000..be92c6d71f --- /dev/null +++ b/doc/source/reference/networking/sriov.rst @@ -0,0 +1,224 @@ +.. _sriov: + +===== +SRIOV +===== + +Neutron SRIOV +~~~~~~~~~~~~~ + +Preparation and deployment +-------------------------- + +SRIOV requires specific NIC and BIOS configuration and is not supported on all +platforms. Consult NIC and platform specific documentation for instructions +on enablement. + +Modify the ``/etc/kolla/globals.yml`` file as the following example shows: + +.. code-block:: yaml + + enable_neutron_sriov: "yes" + +Modify the ``/etc/kolla/config/neutron/ml2_conf.ini`` file and add +``sriovnicswitch`` to the ``mechanism_drivers``. Also, the provider +networks used by SRIOV should be configured. Both flat and VLAN are configured +with the same physical network name in this example: + +.. path /etc/kolla/config/neutron/ml2_conf.ini +.. code-block:: ini + + [ml2] + mechanism_drivers = openvswitch,l2population,sriovnicswitch + + [ml2_type_vlan] + network_vlan_ranges = sriovtenant1:1000:1009 + + [ml2_type_flat] + flat_networks = sriovtenant1 + +Add ``PciPassthroughFilter`` to scheduler_default_filters + +The ``PciPassthroughFilter``, which is required by Nova Scheduler service +on the Controller, should be added to ``scheduler_default_filters`` + +Modify the ``/etc/kolla/config/nova.conf`` file and add +``PciPassthroughFilter`` to ``scheduler_default_filters``. this filter is +required by The Nova Scheduler service on the controller node. + +.. path /etc/kolla/config/nova.conf +.. code-block:: ini + + [DEFAULT] + scheduler_default_filters = , PciPassthroughFilter + scheduler_available_filters = nova.scheduler.filters.all_filters + +Edit the ``/etc/kolla/config/nova.conf`` file and add PCI device whitelisting. +this is needed by OpenStack Compute service(s) on the Compute. + +.. path /etc/kolla/config/nova.conf +.. code-block:: ini + + [pci] + passthrough_whitelist = [{"devname": "ens785f0", "physical_network": "sriovtenant1"}] + +Modify the ``/etc/kolla/config/neutron/sriov_agent.ini`` file. Add physical +network to interface mapping. Specific VFs can also be excluded here. Leaving +blank means to enable all VFs for the interface: + +.. path /etc/kolla/config/neutron/sriov_agent.ini +.. code-block:: ini + + [sriov_nic] + physical_device_mappings = sriovtenant1:ens785f0 + exclude_devices = + +Run deployment. + +Verification +------------ + +Check that VFs were created on the compute node(s). VFs will appear in the +output of both ``lspci`` and ``ip link show``. For example: + +.. code-block:: console + + # lspci | grep net + 05:10.0 Ethernet controller: Intel Corporation 82599 Ethernet Controller Virtual Function (rev 01) + + + # ip -d link show ens785f0 + 4: ens785f0: mtu 1500 qdisc mq master ovs-system state UP mode DEFAULT qlen 1000 + link/ether 90:e2:ba:ba:fb:20 brd ff:ff:ff:ff:ff:ff promiscuity 1 + openvswitch_slave addrgenmode eui64 + vf 0 MAC 52:54:00:36:57:e0, spoof checking on, link-state auto, trust off + vf 1 MAC 52:54:00:00:62:db, spoof checking on, link-state auto, trust off + vf 2 MAC fa:16:3e:92:cf:12, spoof checking on, link-state auto, trust off + vf 3 MAC fa:16:3e:00:a3:01, vlan 1000, spoof checking on, link-state auto, trust off + +Verify the SRIOV Agent container is running on the compute node(s): + +.. code-block:: console + + # docker ps --filter name=neutron_sriov_agent + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b03a8f4c0b80 10.10.10.10:4000/registry/centos-source-neutron-sriov-agent:17.04.0 "kolla_start" 18 minutes ago Up 18 minutes neutron_sriov_agent + +Verify the SRIOV Agent service is present and UP: + +.. code-block:: console + + # openstack network agent list + + +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ + | ID | Agent Type | Host | Availability Zone | Alive | State | Binary | + +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ + | 7c06bda9-7b87-487e-a645-cc6c289d9082 | NIC Switch agent | av09-18-wcp | None | :-) | UP | neutron-sriov-nic-agent | + +--------------------------------------+--------------------+-------------+-------------------+-------+-------+---------------------------+ + +Create a new provider network. Set ``provider-physical-network`` to the +physical network name that was configured in ``/etc/kolla/config/nova.conf``. +Set ``provider-network-type`` to the desired type. If using VLAN, ensure +``provider-segment`` is set to the correct VLAN ID. This example uses ``VLAN`` +network type: + + +.. code-block:: console + + # openstack network create --project=admin \ + --provider-network-type=vlan \ + --provider-physical-network=sriovtenant1 \ + --provider-segment=1000 \ + sriovnet1 + +Create a subnet with a DHCP range for the provider network: + +.. code-block:: console + + # openstack subnet create --network=sriovnet1 \ + --subnet-range=11.0.0.0/24 \ + --allocation-pool start=11.0.0.5,end=11.0.0.100 \ + sriovnet1_sub1 + +Create a port on the provider network with ``vnic_type`` set to ``direct``: + +.. code-block:: console + + # openstack port create --network sriovnet1 --vnic-type=direct sriovnet1-port1 + +Start a new instance with the SRIOV port assigned: + +.. code-block:: console + + # openstack server create --flavor flavor1 \ + --image fc-26 \ + --nic port-id=`openstack port list | grep sriovnet1-port1 | awk '{print $2}'` \ + vm1 + +Verify the instance boots with the SRIOV port. Verify VF assignment by running +dmesg on the compute node where the instance was placed. + +.. code-block:: console + + # dmesg + [ 2896.849970] ixgbe 0000:05:00.0: setting MAC fa:16:3e:00:a3:01 on VF 3 + [ 2896.850028] ixgbe 0000:05:00.0: Setting VLAN 1000, QOS 0x0 on VF 3 + [ 2897.403367] vfio-pci 0000:05:10.4: enabling device (0000 -> 0002) + +For more information see `OpenStack SRIOV documentation `_. + +Nova SRIOV +~~~~~~~~~~ + +Preparation and deployment +-------------------------- + +Nova provides a separate mechanism to attach PCI devices to instances that +is independent from Neutron. Using the PCI alias configuration option in +nova.conf, any PCI device (PF or VF) that supports passthrough can be attached +to an instance. One major drawback to be aware of when using this method is +that the PCI alias option uses a device's product id and vendor id only, +so in environments that have NICs with multiple ports configured for SRIOV, +it is impossible to specify a specific NIC port to pull VFs from. + +Modify the file ``/etc/kolla/config/nova.conf``. The Nova Scheduler service +on the control node requires the ``PciPassthroughFilter`` to be added to the +list of filters and the Nova Compute service(s) on the compute node(s) need +PCI device whitelisting. The Nova API service on the control node and the Nova +Compute service on the compute node also require the ``alias`` option under the +``[pci]`` section. The alias can be configured as 'type-VF' to pass VFs or +'type-PF' to pass the PF. Type-VF is shown in this example: + +.. path /etc/kolla/config/nova.conf +.. code-block:: ini + + [DEFAULT] + scheduler_default_filters = , PciPassthroughFilter + scheduler_available_filters = nova.scheduler.filters.all_filters + + [pci] + passthrough_whitelist = [{"vendor_id": "8086", "product_id": "10fb"}] + alias = [{"vendor_id":"8086", "product_id":"10ed", "device_type":"type-VF", "name":"vf1"}] + +Run deployment. + +Verification +------------ + +Create (or use an existing) flavor, and then configure it to request one PCI +device from the PCI alias: + +.. code-block:: console + + # openstack flavor set sriov-flavor --property "pci_passthrough:alias"="vf1:1" + +Start a new instance using the flavor: + +.. code-block:: console + + # openstack server create --flavor sriov-flavor --image fc-26 vm2 + +Verify VF devices were created and the instance starts successfully as in +the Neutron SRIOV case. + +For more information see `OpenStack PCI passthrough documentation `_. diff --git a/doc/source/reference/orchestration-and-nfv/index.rst b/doc/source/reference/orchestration-and-nfv/index.rst new file mode 100644 index 0000000000..3e47ef8cc7 --- /dev/null +++ b/doc/source/reference/orchestration-and-nfv/index.rst @@ -0,0 +1,10 @@ +===================== +Orchestration and NFV +===================== + +This section describes configuration of orchestration and NFV services. + +.. toctree:: + :maxdepth: 2 + + tacker-guide diff --git a/doc/source/reference/tacker-guide.rst b/doc/source/reference/orchestration-and-nfv/tacker-guide.rst similarity index 98% rename from doc/source/reference/tacker-guide.rst rename to doc/source/reference/orchestration-and-nfv/tacker-guide.rst index 72f1fb4add..c22f8a00d2 100644 --- a/doc/source/reference/tacker-guide.rst +++ b/doc/source/reference/orchestration-and-nfv/tacker-guide.rst @@ -1,6 +1,6 @@ -=============== -Tacker in Kolla -=============== +========================== +Tacker - NFV orchestration +========================== "Tacker is an OpenStack service for NFV Orchestration with a general purpose VNF Manager to deploy and operate Virtual Network Functions (VNFs) and diff --git a/doc/source/reference/glance-guide.rst b/doc/source/reference/shared-services/glance-guide.rst similarity index 88% rename from doc/source/reference/glance-guide.rst rename to doc/source/reference/shared-services/glance-guide.rst index ce1d52b9f8..6a7bce200e 100644 --- a/doc/source/reference/glance-guide.rst +++ b/doc/source/reference/shared-services/glance-guide.rst @@ -1,8 +1,8 @@ .. _glance-guide: -=============== -Glance in Kolla -=============== +====================== +Glance - Image service +====================== Glance backends --------------- @@ -41,8 +41,8 @@ Ceph backend To make use of ``ceph`` backend in glance, simply enable ceph or external ceph. By default will enable backend ceph automatically. -Please refer to :doc:`ceph-guide` or :doc:`external-ceph-guide` on how to -configure this backend. +Please refer to :doc:`../storage/ceph-guide` +or :doc:`../storage/external-ceph-guide` on how to configure this backend. To enable the ceph backend manually: @@ -54,7 +54,7 @@ VMware backend ~~~~~~~~~~~~~~ To make use of VMware datastores as a glance backend, -enable `glance_backend_vmware` and refer to :doc:`vmware-guide` for +enable `glance_backend_vmware` and refer to :doc:`../compute/vmware-guide` for further VMware configuration. To enable the vmware backend manually: @@ -67,7 +67,8 @@ Swift backend ~~~~~~~~~~~~~ To store glance images in a swift cluster, the ``swift`` backend should -be enabled. Refer to :doc:`swift-guide` on how to configure swift in kolla. +be enabled. Refer to :doc:`../storage/swift-guide` on how to configure +swift in kolla. If ceph is enabled, will have higher precedence over swift as glance backend. To enable the swift backend manually: @@ -103,7 +104,7 @@ need to be enabled. .. warning:: - When using glance backend ``file`` without a shared filesytem, this method cannot + When using glance backend ``file`` without a shared filesystem, this method cannot be used or will end up with a corrupt state of glance services. Reasoning behind is because glance api is only running in one host, blocking the orchestration of a rolling upgrade. diff --git a/doc/source/reference/horizon-guide.rst b/doc/source/reference/shared-services/horizon-guide.rst similarity index 89% rename from doc/source/reference/horizon-guide.rst rename to doc/source/reference/shared-services/horizon-guide.rst index 65e9cdeb64..89d19c72f2 100644 --- a/doc/source/reference/horizon-guide.rst +++ b/doc/source/reference/shared-services/horizon-guide.rst @@ -1,8 +1,8 @@ .. _horizon-guide: -================ -Horizon in Kolla -================ +============================= +Horizon - OpenStack dashboard +============================= Overview ~~~~~~~~ diff --git a/doc/source/reference/shared-services/index.rst b/doc/source/reference/shared-services/index.rst new file mode 100644 index 0000000000..74f82f0ed7 --- /dev/null +++ b/doc/source/reference/shared-services/index.rst @@ -0,0 +1,12 @@ +=============== +Shared services +=============== + +This section describes configuring different shared service options +like backends, dashboards and so on. + +.. toctree:: + :maxdepth: 2 + + glance-guide + horizon-guide diff --git a/doc/source/reference/ceph-guide.rst b/doc/source/reference/storage/ceph-guide.rst similarity index 99% rename from doc/source/reference/ceph-guide.rst rename to doc/source/reference/storage/ceph-guide.rst index 34d27a9969..8cf1c11229 100644 --- a/doc/source/reference/ceph-guide.rst +++ b/doc/source/reference/storage/ceph-guide.rst @@ -1,8 +1,8 @@ .. _ceph-guide: -============= -Ceph in Kolla -============= +=============================== +Ceph - Software Defined Storage +=============================== .. note:: The out-of-the-box Ceph deployment requires 3 hosts with at least one block diff --git a/doc/source/reference/cinder-guide-hnas.rst b/doc/source/reference/storage/cinder-guide-hnas.rst similarity index 100% rename from doc/source/reference/cinder-guide-hnas.rst rename to doc/source/reference/storage/cinder-guide-hnas.rst diff --git a/doc/source/reference/cinder-guide.rst b/doc/source/reference/storage/cinder-guide.rst similarity index 98% rename from doc/source/reference/cinder-guide.rst rename to doc/source/reference/storage/cinder-guide.rst index 50b2fccd57..cd37f879cb 100644 --- a/doc/source/reference/cinder-guide.rst +++ b/doc/source/reference/storage/cinder-guide.rst @@ -1,8 +1,8 @@ .. _cinder-guide: -=============== -Cinder in Kolla -=============== +====================== +Cinder - Block storage +====================== Overview ~~~~~~~~ diff --git a/doc/source/reference/external-ceph-guide.rst b/doc/source/reference/storage/external-ceph-guide.rst similarity index 100% rename from doc/source/reference/external-ceph-guide.rst rename to doc/source/reference/storage/external-ceph-guide.rst diff --git a/doc/source/reference/storage/index.rst b/doc/source/reference/storage/index.rst new file mode 100644 index 0000000000..43559d2277 --- /dev/null +++ b/doc/source/reference/storage/index.rst @@ -0,0 +1,17 @@ +======= +Storage +======= + +This section describes configuration of the different storage backends +supported by kolla. + +.. toctree:: + :maxdepth: 1 + + ceph-guide + external-ceph-guide + cinder-guide + cinder-guide-hnas + manila-guide + manila-hnas-guide + swift-guide diff --git a/doc/source/reference/manila-guide.rst b/doc/source/reference/storage/manila-guide.rst similarity index 99% rename from doc/source/reference/manila-guide.rst rename to doc/source/reference/storage/manila-guide.rst index 475f4c4946..5a9dec4226 100644 --- a/doc/source/reference/manila-guide.rst +++ b/doc/source/reference/storage/manila-guide.rst @@ -1,8 +1,8 @@ .. _manila-guide: -=============== -Manila in Kolla -=============== +=================================== +Manila - Shared filesystems service +=================================== Overview ~~~~~~~~ diff --git a/doc/source/reference/manila-hnas-guide.rst b/doc/source/reference/storage/manila-hnas-guide.rst similarity index 100% rename from doc/source/reference/manila-hnas-guide.rst rename to doc/source/reference/storage/manila-hnas-guide.rst diff --git a/doc/source/reference/swift-guide.rst b/doc/source/reference/storage/swift-guide.rst similarity index 98% rename from doc/source/reference/swift-guide.rst rename to doc/source/reference/storage/swift-guide.rst index 92b780404d..c5c4e23d36 100644 --- a/doc/source/reference/swift-guide.rst +++ b/doc/source/reference/storage/swift-guide.rst @@ -1,8 +1,8 @@ .. _swift-guide: -============== -Swift in Kolla -============== +============================= +Swift- Object storage service +============================= Overview ~~~~~~~~