USERDOCAP-351 Adding a new chapter Provider Scripts to the UG

2 files changed, 178 insertions, 0 deletions

diff --git a/book-enea-nfv-core-installation-guide/doc/book.xml b/book-enea-nfv-core-installation-guide/doc/book.xml
index 6744769..0308e84 100644
--- a/book-enea-nfv-core-installation-guide/doc/book.xml
+++ b/book-enea-nfv-core-installation-guide/doc/book.xml
@@ -16,5 +16,6 @@
   <xi:include href="tacker.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="high_availability.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="mixed_arch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="provider_scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!--  <xi:include href="use_cases_per_target_node.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 </book>
diff --git a/book-enea-nfv-core-installation-guide/doc/provider_scripts.xml b/book-enea-nfv-core-installation-guide/doc/provider_scripts.xml
new file mode 100644
index 0000000..2ba9b39
--- /dev/null
+++ b/book-enea-nfv-core-installation-guide/doc/provider_scripts.xml
@@ -0,0 +1,177 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="provider_scripts">
+  <title>Provider Scripts</title>
+
+  <para>INSERT INTRO TEXT HERE AND REPLACE THIS</para>
+
+  <section id="provider_net">
+    <title>Provider Networks</title>
+
+    <para>For the best results it is recommended to run this playbook as soon
+    as the deploy+provision segments in Fuel successfully finish or if there
+    are no modifications made to the networking/neutron/openvswitch components
+    on the POD.</para>
+
+    <para>Things to consider:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>All node types (computes and controllers) are viable and can
+        sustain a provider network.</para>
+      </listitem>
+
+      <listitem>
+        <para>DPDK is not mandatory. If a DPDK is not detected on a node, the
+        interface type will be <literal>OVSPort</literal> for the provider
+        network bridge, therefore DPDK is not checked during the pre-run
+        Ansible stages.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para><emphasis role="bold">How to run the Provider Networks
+    Playbook</emphasis></para>
+
+    <orderedlist>
+      <listitem>
+        <para>Log into the Fuel master.</para>
+      </listitem>
+
+      <listitem>
+        <para>Install ansible: <programlisting>yum install ansible</programlisting></para>
+      </listitem>
+
+      <listitem>
+        <para>Run the initial script: <programlisting>&gt; cd /opt/enea/postdeployscripts/provider-net
+&gt; ./init.sh</programlisting></para>
+
+        <para>This will create a hosts file that will be used by Ansible to
+        associate the nodes into groups and to access them. It will also
+        create a file named <filename>samplenetworks.json</filename>, which
+        will contain a single network in which all nodes (computes and
+        controllers) are plugged in.</para>
+
+        <para>The <filename>samplenetworks.json</filename> file will have the
+        following content:<programlisting>   {
+    "networks": [
+        {
+            "name": "prov-net",
+            "nodes": [
+                {
+                    "interfaces": [],
+                    "name": "node-1"
+                },
+                [...] # all other controller and compute nodes: node-X
+                ]
+        }
+   }</programlisting></para>
+
+        <note>
+          <para>The interface list is empty and has to be populated by the
+          user. If the interface lists are left empty the node will simply not
+          be processed, though it will attempt to pass any checks.</para>
+        </note>
+
+        <para>To use this file the user has to copy its contents into the
+        following location:<programlisting>mv samplenetworks.json /opt/enea/postdeployscripts/provider-net/files/networks.json</programlisting></para>
+      </listitem>
+
+      <listitem>
+        <para>Populate the <filename>networks.json</filename> file which is
+        located in
+        <literal>/opt/enea/postdeployscripts/provider-net/files/networks.json</literal>.</para>
+
+        <para>The <filename>networks.json</filename> file will be used in the
+        playbook to know which interfaces on which nodes are used in which
+        networks. Various checks are in place to minimize user error.</para>
+
+        <para>Below you can see a sample <filename>networks.json</filename>
+        file, similar to step 2, with some interfaces
+        included:<programlisting>   {  
+      "networks":[  
+         {  
+            "name":"prov-net",
+            "nodes":[  
+               {  
+                  "name":"node-4",
+                  "interfaces":[  
+                     "em2p1s0f5"
+                  ]
+               },
+               {  
+                  "name":"node-5",
+                  "interfaces":[  
+                     "em2p1s0f5"
+                  ]
+               }
+            ]
+         }
+      ]
+   }</programlisting>The snippet shown above infers the following:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>There is a provider network named
+            <filename>prov-net</filename>.</para>
+          </listitem>
+
+          <listitem>
+            <para>Two nodes (node-4 and node-5) are connected to this
+            network.</para>
+          </listitem>
+
+          <listitem>
+            <para>Each of these nodes have an interface plugged into said
+            network.</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>All of these components are <literal>lists</literal>, and can be
+        scaled accordingly, making it possible for there to be potentially X
+        networks with Y nodes with Z interfaces.</para>
+
+        <para>Make sure to check the following before the
+        <filename>networks.json</filename> file is populated:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Check that the node names in the file match the actual
+            hostnames of the nodes.</para>
+          </listitem>
+
+          <listitem>
+            <para>Check that the interfaces on the nodes in the file match the
+            ones on the actual machines and aren't using the DPDK
+            driver.</para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>Run the playbook:<programlisting>ansible-playbook deploy.yaml</programlisting><literal><filename>deploy.yaml</filename></literal>
+        is located:
+        <literal>/opt/enea/postdeployscripts/provider-net/deploy.yaml</literal>.</para>
+
+        <note>
+          <para>After the playbook is executed the nodes will be
+          rebooted.</para>
+        </note>
+
+        <para>On the processed nodes there should be new OVS bridges with the
+        following interface(s):<programlisting>Bridge br-prov-net
+     Controller "tcp:127.0.0.1:6633"
+         is_connected: true
+     fail_mode: secure
+     Port phy-br-prov-net
+         Interface phy-br-prov-net
+             type: patch
+             options: {peer=int-br-prov-net}
+     Port br-prov-net
+         Interface br-prov-net
+             type: internal
+ ovs_version: "2.9.0"</programlisting></para>
+      </listitem>
+    </orderedlist>
+  </section>
+</chapter>
\ No newline at end of file