OpenStack VNF Integration User Tasks

Completed review comments
Minor abbreviation fix
Moved topics into its own VNF Integration section
Fixed abbreviations
Re-organized Kubernetes topics

Change-Id: I8940d3572b789990d3b5f2d201f8ec8a46ce2943
Signed-off-by: Keane Lim <keane.lim@windriver.com>

doc/source/index.rst

@@ -138,6 +138,15 @@ User Tasks
 
    usertasks/index
 
+---------------
+VNF Integration
+---------------
+
+.. toctree::
+   :maxdepth: 2
+
+   vnf_integration/index
+   
 -------
 Storage
 -------

doc/source/shared/abbrevs.txt

@@ -8,6 +8,7 @@
 .. |AE| replace:: :abbr:`AE (Aggregated Ethernet)`
 .. |AIO| replace:: :abbr:`AIO (All-In-One)`
 .. |AVP| replace:: :abbr:`AVP (Accelerated Virtual Port)`
+.. |AVPs| replace:: :abbr:`AVPs (Accelerated Virtual Ports)`
 .. |AWS| replace:: :abbr:`AWS (Amazon Web Services)`
 .. |BGP| replace:: :abbr:`BGP (Border Gateway Protocol)`
 .. |BMC| replace:: :abbr:`BMC (Board Management Controller)`
@@ -18,8 +19,8 @@
 .. |CA| replace:: :abbr:`CA (Certificate Authority)`
 .. |CAs| replace:: :abbr:`CAs (Certificate Authorities)`
 .. |CLI| replace:: :abbr:`CLI (Command Line Interface)`
-.. |CNI| replace:: :abbr:`CNI (Container Networking Interface)`
 .. |CMK| replace:: :abbr:`CMK (CPU Manager for Kubernetes)`
+.. |CNI| replace:: :abbr:`CNI (Container Networking Interface)`
 .. |CoW| replace:: :abbr:`CoW (Copy on Write)`
 .. |CSK| replace:: :abbr:`CSK (Code Signing Key)`
 .. |CSKs| replace:: :abbr:`CSKs (Code Signing Keys)`
@@ -30,6 +31,7 @@
 .. |DRBD| replace:: :abbr:`DRBD (Distributed Replicated Block Device)`
 .. |DSCP| replace:: :abbr:`DSCP (Differentiated Services Code Point)`
 .. |DVR| replace:: :abbr:`DVR (Distributed Virtual Router)`
+.. |EMS| replace:: :abbr:`EMS (Element Management System)`
 .. |FEC| replace:: :abbr:`FEC (Forward Error Correction)`
 .. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)`
 .. |FQDN| replace:: :abbr:`FQDN (Fully Qualified Domain Name)`
@@ -68,6 +70,7 @@
 .. |PEM| replace:: :abbr:`PEM (Privacy Enhanced Mail)`
 .. |PF| replace:: :abbr:`PF (Physical Function)`
 .. |PHB| replace:: :abbr:`PHB (Per-Hop Behavior)`
+.. |PMD| replace:: :abbr:`PMD (Pole Mode Driver)`
 .. |PQDN| replace:: :abbr:`PDQN (Partially Qualified Domain Name)`
 .. |PQDNs| replace:: :abbr:`PQDNs (Partially Qualified Domain Names)`
 .. |PSP| replace:: :abbr:`PSP (Pod Security Policy)`
@@ -92,7 +95,7 @@
 .. |SNAT| replace:: :abbr:`SNAT (Source Network Address Translation)`
 .. |SNMP| replace:: :abbr:`SNMP (Simple Network Management Protocol)`
 .. |SRIOV| replace:: :abbr:`SR-IOV (Single Root I/O Virtualization)`
-.. |SRIOVs| replace:: :abbr:`SR-IOV (Single Root I/O Virtualizations)`
+.. |SRIOVs| replace:: :abbr:`SR-IOVs (Single Root I/O Virtualizations)`
 .. |SSD| replace:: :abbr:`SSD (Solid State Drive)`
 .. |SSDs| replace:: :abbr:`SSDs (Solid State Drives)`
 .. |SSH| replace:: :abbr:`SSH (Secure Shell)`
@@ -114,6 +117,8 @@
 .. |VM| replace:: :abbr:`VM (Virtual Machine)`
 .. |VMs| replace:: :abbr:`VMs (Virtual Machines)`
 .. |VNC| replace:: :abbr:`VNC (Virtual Network Computing)`
+.. |VNF| replace:: :abbr:`VNF (Virtual Network Function)`
+.. |VNFs| replace:: :abbr:`VNFs (Virtual Network Functions)`
 .. |VNI| replace:: :abbr:`VNI (VXLAN Network Interface)`
 .. |VNIs| replace:: :abbr:`VNIs (VXLAN Network Interfaces)`
 .. |VPC| replace:: :abbr:`VPC (Virtual Port Channel)`

doc/source/usertasks/index.rst

@@ -1,8 +1,3 @@
-.. User tasks file, created by
-   sphinx-quickstart on Thu Sep  3 15:14:59 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ==========
 User Tasks
 ==========
@@ -14,138 +9,13 @@ Kubernetes
 The |prod-long| Kubernetes user tutorials provide working examples of common
 end-user tasks.
 
-These include tasks related to:
-
-*************
-System access
-*************
-
 .. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-access-overview
-
-Remote CLI access
-*****************
-
-.. toctree::
-   :maxdepth: 1
-
-   remote-cli-access
-   kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients
-   usertask-using-container-backed-remote-clis-and-clients
-   kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host
-   configuring-remote-helm-client
-
-GUI access
-**********
-
-.. toctree::
-   :maxdepth: 1
-
-   accessing-the-kubernetes-dashboard
-
-API access
-**********
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-rest-api-access
-
-**********************
-Application management
-**********************
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-helm-package-manager
-
-*********************
-Local docker registry
-*********************
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-authentication-and-authorization
-   using-an-image-from-the-local-docker-registry-in-a-container-spec
-
-***************************
-NodePort usage restrictions
-***************************
-
-.. toctree::
-   :maxdepth: 1
-
-   nodeport-usage-restrictions
-
-************
-Cert Manager
-************
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-cert-manager
-   letsencrypt-example
-
-********************************
-Vault secret and data management
-********************************
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-vault-overview
-   vault-aware
-   vault-unaware
-
-****************************
-Using Kata container runtime
-****************************
-
-.. toctree::
-   :maxdepth: 1
-
-   kata-containers-overview
-   specifying-kata-container-runtime-in-pod-spec
-   known-limitations
-
-*******************************
-Adding persistent volume claims
-*******************************
-
-.. toctree::
-   :maxdepth: 1
-
-   kubernetes-user-tutorials-creating-persistent-volume-claims
-   kubernetes-user-tutorials-mounting-persistent-volumes-in-containers
-
-****************************************
-Adding an SRIOV interface to a container
-****************************************
-
-.. toctree::
-   :maxdepth: 1
-
-   creating-network-attachment-definitions
-   using-network-attachment-definitions-in-a-container
-
-**************************
-CPU Manager for Kubernetes
-**************************
-
-.. toctree::
-   :maxdepth: 1
-
-   using-kubernetes-cpu-manager-static-policy
-   using-intels-cpu-manager-for-kubernetes-cmk
-   uninstalling-cmk
+   :maxdepth: 2
+   
+   kubernetes/index
 
 ---------
 OpenStack
 ---------
 
-Coming soon.
+Coming soon

doc/source/usertasks/kubernetes/index.rst

@@ -0,0 +1,131 @@
+========
+Contents
+========
+
+*************
+System access
+*************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-access-overview
+
+Remote CLI access
+*****************
+
+.. toctree::
+   :maxdepth: 1
+
+   remote-cli-access
+   kubernetes-user-tutorials-configuring-container-backed-remote-clis-and-clients
+   usertask-using-container-backed-remote-clis-and-clients
+   kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host
+   configuring-remote-helm-client
+
+GUI access
+**********
+
+.. toctree::
+   :maxdepth: 1
+
+   accessing-the-kubernetes-dashboard
+
+API access
+**********
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-rest-api-access
+
+**********************
+Application management
+**********************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-helm-package-manager
+
+*********************
+Local docker registry
+*********************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-authentication-and-authorization
+   using-an-image-from-the-local-docker-registry-in-a-container-spec
+
+***************************
+NodePort usage restrictions
+***************************
+
+.. toctree::
+   :maxdepth: 1
+
+   nodeport-usage-restrictions
+
+************
+Cert Manager
+************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-cert-manager
+   letsencrypt-example
+
+********************************
+Vault secret and data management
+********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-vault-overview
+   vault-aware
+   vault-unaware
+
+****************************
+Using Kata container runtime
+****************************
+
+.. toctree::
+   :maxdepth: 1
+
+   kata-containers-overview
+   specifying-kata-container-runtime-in-pod-spec
+   known-limitations
+
+*******************************
+Adding persistent volume claims
+*******************************
+
+.. toctree::
+   :maxdepth: 1
+
+   kubernetes-user-tutorials-creating-persistent-volume-claims
+   kubernetes-user-tutorials-mounting-persistent-volumes-in-containers
+
+****************************************
+Adding an SRIOV interface to a container
+****************************************
+
+.. toctree::
+   :maxdepth: 1
+
+   creating-network-attachment-definitions
+   using-network-attachment-definitions-in-a-container
+
+**************************
+CPU Manager for Kubernetes
+**************************
+
+.. toctree::
+   :maxdepth: 1
+
+   using-kubernetes-cpu-manager-static-policy
+   using-intels-cpu-manager-for-kubernetes-cmk
+   uninstalling-cmk

doc/source/usertasks/kubernetes/nodeport-usage-restrictions.rst

@@ -6,7 +6,8 @@
 NodePort Usage Restrictions
 ===========================
 
-This sections lists the usage restrictions of NodePorts for your |prod-long| product.
+This sections lists the usage restrictions of NodePorts for your 
+|prod-long| product.
 
 The following usage restrictions apply when using NodePorts:
 
@@ -19,4 +20,4 @@ The following usage restrictions apply when using NodePorts:
 
 .. only:: partner
 
-    .. include:: ../_includes/nodeport-usage-restrictions.rest
+    .. include:: ../../_includes/nodeport-usage-restrictions.rest

doc/source/vnf_integration/accelerated-virtual-interfaces.rst

@@ -0,0 +1,29 @@
+
+.. xyo1466098370729
+.. _accelerated-virtual-interfaces:
+
+==============================
+Accelerated Virtual Interfaces
+==============================
+
+|VNFs| can be configured to use |org| |AVP| to improve throughput when
+compared to emulated virtual drivers.
+
+The |prod-os| |AVP| virtual |NIC| is a shared memory based high performance networking
+device. Its potential maximum throughput is higher than other emulated virtual
+|NIC| devices \(for example, e1000\). For more information, see
+:ref:`wrs-avp-pmd—Accelerated DPDK Network Drivers
+<wrs-avp-pmd-accelerated-dpdk-network-drivers>`.
+
+.. seealso::
+
+    -   :ref:`Standard Virtio - Backed with Vhost Support
+        <standard-virtio-backed-with-vhost-support>`
+
+    -   :ref:`wrs-avp-pmd—Accelerated DPDK Network Drivers
+        <wrs-avp-pmd-accelerated-dpdk-network-drivers>`
+
+    -   :ref:`Using a VIF Model when Creating Ports
+        <use-a-vif-model-when-creating-ports>`
+
+

doc/source/vnf_integration/bootstrap-data.rst

@@ -0,0 +1,32 @@
+
+.. aiq1466089940954
+.. _bootstrap-data:
+
+==============
+Bootstrap Data
+==============
+
+You can use one or more mechanisms to pass information to a new |VNF| when it
+is originally launched. The |VNF| can use this information for system
+configuration purposes or to determine running options for the services it
+provides.
+
+The mechanisms used to convey information from the Cloud OS to the |VNF| are
+the metadata server and config drive.
+
+
+.. _bootstrap-data-ul-aw2-l2d-3w:
+
+-   User data is made available to the |VNF| through either the metadata
+    service or the configuration drive.
+
+-   The cloud-init package reads information from either the metadata 
+    server or the configuration drive.
+
+
+Detailed information about the OpenStack metadata server, config drive, and
+cloud-init is available online.
+
+For more information, see `http://docs.openstack.org
+<http://docs.openstack.org>`__.
+

doc/source/vnf_integration/configuration-using-metadata.rst

@@ -0,0 +1,160 @@
+
+.. rst1450732770531
+.. _configuration-using-metadata:
+
+============================
+Configuration Using Metadata
+============================
+
+Boot configuration user data can be passed to a virtual machine during
+startup.
+
+.. contents:: |minitoc|
+   :local:
+   :depth: 1
+
+For example, an |EMS| may be used in cloud environments for |VM|
+configuration, but the |VM| may require some bootstrap information to
+successfully communicate with the |EMS|.
+
+|prod-os| provides three mechanisms to accomplish this:
+
+---------
+User Data
+---------
+
+This is a mechanism for passing a local file to an instance when it is
+launched. This method is typically used to pass a shell script or
+configuration file.
+
+To send user data when calling nova boot, use the ``--user-data
+/path/to/filename`` option, or use the Heat service and set the
+``user\_data`` property and ``user\_data\_format`` to RAW.
+
+On initialization, the |VM| queries the metadata service through either
+the EC2 compatibility API. For example:
+
+.. code-block:: none
+
+    $ curl http://169.254.169.254/2012-08-10/user_data
+
+or the OpenStack metadata API. For example:
+
+.. code-block:: none
+
+    $ curl http://169.254.169.254/openstack/2009-04-04/user_data
+
+In either case, text is returned to the |VM| and can be used for
+bootstrap configuration.
+
+Access to the metadata server at 169.254.169.254 is provided by a
+virtual router attached to the project network on which the access
+request is made. Virtual routers are automatically configured as
+proxies to the metadata service.
+
+----------
+cloud-init
+----------
+
+This is an open-source package available from
+`https://cloudinit.readthedocs.org/en/latest/
+<https://cloudinit.readthedocs.org/en/latest/>`__ that supports a
+variety of guests. It expects a particular file format for user data,
+retrieves the user data from the metadata server, and takes action
+based on the contents of the data.
+
+Two commonly used input formats are:
+
+**shell scripts**
+    You can configure an instance at boot time by passing a shell
+    script as user data. The script file must begin with
+
+    .. code-block:: none
+
+        #!
+
+    for **cloud-init** to recognize it as a shell script.
+
+**Cloud config files**
+    A configuration format based on |YAML| that you can use to configure
+    a large number of options on a system. For example, to set the
+    hostname:
+
+    .. code-block:: none
+
+        #cloud-config
+        hostname: mynode
+        fqdn: mynode.example.com
+        manage_etc_hosts: true
+
+    See `https://cloudinit.readthedocs.org/en/latest
+    <https://cloudinit.readthedocs.org/en/latest>`__ for a complete
+    list of capabilities.
+
+------------
+Config drive
+------------
+
+|prod-os| can be configured to use a special-purpose configuration
+drive \(abbreviated config drive\) to store metadata \(including
+injected files\). Metadata is written to the drive, which is attached
+to the instance when it boots. The instance can retrieve information
+normally available through the metadata service by reading from the
+mounted drive.
+
+The config drive can be enabled by using the ``--config-drive=true``
+option with nova boot.
+
+The following example enables the config drive and passes user data,
+injecting two files and two key/value metadata pairs. These can be read
+from the config drive.
+
+.. code-block:: none
+
+    $ openstack server create --config-drive true --image my-image-name --flavor 1 --key-name mykey --user-data ./my-user-data.txt --property role=webservers --property essential=false MYINSTANCE
+
+From within the instance, the config drive volume is labeled
+**config-2**. You can mount the config drive as the
+/dev/disk/by-label/config-2 device if your guest OS supports accessing
+disks by label. For example:
+
+.. code-block:: none
+
+    # mkdir -p /mnt/config
+    # mount /dev/disk/by-label/config-2 /mnt/config
+
+The contents of the config drive depend on the options passed to nova
+boot. The contents of the config drive for the example above are:
+
+.. code-block:: none
+
+    ec2/2009-04-04/meta-data.json
+    ec2/2009-04-04/user-data
+    ec2/latest/meta-data.json
+    ec2/latest/user-data
+    openstack/2012-08-10/meta_data.json
+    openstack/2012-08-10/user_data
+    openstack/content
+    openstack/content/0000
+    openstack/content/0001
+    openstack/latest/meta_data.json
+    openstack/latest/user_data
+
+For file format details and full details on config-drive, refer to the
+public OpenStack documentation.
+
+.. caution::
+    If a VM uses config-drive for user data or file injection, VM
+    evacuations due to a compute node failure and VM live migrations to
+    another compute node will cause the config drive to be rebuilt on
+    the new compute node and metadata to be populated, but user data
+    and injected files are not populated in the evacuated or
+    live-migrated config drive of the VM.
+
+    For a VM using **config-file** with file injection, it is
+    recommended to copy the injected files to the root disk of the VM
+    on initial boot, and to set a flag to prevent the use of injected
+    files on subsequent boots.
+
+    File injection is disabled when using a Ceph backend.
+

doc/source/vnf_integration/index.rst

@@ -0,0 +1,45 @@
+=========================
+OpenStack VNF Integration
+=========================
+
+---------------------------
+Overview of VNF Integration
+---------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   overview-of-vnf-integration
+
+--------------
+Bootstrap Data
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   bootstrap-data
+   configuration-using-metadata
+
+------------------------------
+Accelerated Virtual Interfaces
+------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   accelerated-virtual-interfaces
+
+************************************
+About Accelerated Virtual Interfaces
+************************************
+
+.. toctree::
+   :maxdepth: 2
+
+   standard-virtio-backed-with-vhost-support
+   wrs-avp-pmd-accelerated-dpdk-network-drivers
+   use-a-vif-model-when-creating-ports
+
+
+

doc/source/vnf_integration/overview-of-vnf-integration.rst

@@ -0,0 +1,40 @@
+
+.. rsk1463498549284
+.. _overview-of-vnf-integration:
+
+===========================
+Overview of VNF Integration
+===========================
+
+The |VNF| Integration document contains information specific to |VNF| or 
+|VM| application writers that assists them with integrating their 
+application on |prod-os|.
+
+The following |VNF|-related integration topics are included in this document:
+
+
+.. _overview-of-vnf-integration-ul-xbz-yds-zv:
+
+-   Bootstrap Data Integration
+
+
+    -   User Data
+
+    -   Config Drive
+
+
+        -   Injected Files
+
+
+
+    See :ref:`Bootstrap Data <bootstrap-data>`.
+
+-   Use |org| |AVPs| to improve throughput when compared to emulated
+    virtual drivers. See :ref:`Accelerated Virtual Interfaces
+    <accelerated-virtual-interfaces>`.
+
+    .. note::
+        |AVP|-|PMD| information is available in the following repository, for
+        more information, see `http://dpdk.org/ <http://dpdk.org/>`__.
+
+

doc/source/vnf_integration/standard-virtio-backed-with-vhost-support.rst

@@ -0,0 +1,21 @@
+
+.. gzn1477524672918
+.. _standard-virtio-backed-with-vhost-support:
+
+===========================================
+Standard Virtio - Backed with Vhost Support
+===========================================
+
+Unmodified guests can use Linux networking and virtio drivers. This provides a
+mechanism to bring existing applications into the production environment
+immediately.
+
+For virtio interfaces, |prod-os| supports vhost-user transparently by default.
+This allows QEMU and AVS to share virtio queues through shared memory,
+resulting in improved performance over standard virtio. The transparent
+implementation provides a simplified alternative to the open-source |AVP|
+kernel and |AVP|-|PMD| drivers. For more about these drivers, see
+:ref:`Accelerated Virtual Interfaces <accelerated-virtual-interfaces>`. The
+availability of vhost-user also offers additional performance enhancements
+through optional multi-queue support for virtio interfaces.
+

doc/source/vnf_integration/use-a-vif-model-when-creating-ports.rst

@@ -0,0 +1,55 @@
+
+.. pey1602790994826
+.. _use-a-vif-model-when-creating-ports:
+
+=====================================
+Using a VIF Model when Creating Ports
+=====================================
+
+For any non Virtio |NIC|, you must create a port beforehand using the VIF
+model.
+
+For example, to set up two |AVPs|, the heat template's binding:profile
+would contain definitions similar to the following.
+
+.. code-block:: yaml
+
+       port_tenant_net_tenant1_avp:
+          type: OS::Neutron::Port
+          properties:
+             name: heat_port_port-tenant-net-tenant1-avp
+             network: tenant1-net1
+             value_specs: {"binding:profile": {"vif_model":"avp"}}
+
+       port_internal_net_tenant1_avp:
+          type: OS::Neutron::Port
+          properties:
+             name: heat_port_port-internal-net-tenant1-avp
+             network: internal0-net1
+             value_specs: {"binding:profile": {"vif_model":"avp"}}
+
+       tenant1_avp:
+          type: OS::Nova::Server
+          properties:
+            name: tenant1-avp4
+            flavor: small
+            block_device_mapping:
+            - {device_name: vda, volume_id: { get_resource: vol_tenant1_avp } }
+            networks:
+            - {network: tenant1-mgmt-net}
+            - {port: { get_resource: port_tenant_net_tenant1_avp } }
+            - {port: { get_resource: port_internal_net_tenant1_avp } }
+
+
+Alternatively, you can use the command line. For example:
+
+.. code-block:: none
+
+    ~(keystone_admin)$ openstack port create --network ${NETWORKID} --binding-profile vif_model=${VIF_MODEL} ${NAME}
+
+For more information about port related commands, see
+`https://docs.openstack.org/python-openstackclient/train/cli/command-objects/
+port.html
+<https://docs.openstack.org/python-openstackclient/train/cli/command-objects/
+port.html>`__.
+

doc/source/vnf_integration/wrs-avp-pmd-accelerated-dpdk-network-drivers.rst

@@ -0,0 +1,22 @@
+
+.. aca1426867398719
+.. _wrs-avp-pmd-accelerated-dpdk-network-drivers:
+
+=============================================
+wrs-avp-pmd--Accelerated DPDK Network Drivers
+=============================================
+
+This component contains AVS-compatible |DPDK| drivers for high-performance
+DPDK-based networking |VNFs|.
+
+The |prod-os| |AVP| virtual |NIC| is a high-performance networking device.
+It can provide line rate throughput \(depending on the guest and AVS
+configuration\). This package provides the Intel |DPDK| compatible |PMD|. It
+can be compiled as a component of an Intel |DPDK| distribution.
+
+The |prod-os| |AVP|-|PMD| driver is available at `http://dpdk.org/
+<http://dpdk.org/>`__.
+
+.. note::
+    |org| no longer publishes |AVP|-|PMD| drivers on GitHub.
+