(docs) Document manifest authoring

- Start documentation on crafting a framework scenario
  manifest now that the framework supports significant
  manifest-driven customization.

Change-Id: I7ed051238ce9262641615103ec73af3b0b1cc630

tools/multi_nodes_gate/README.rst

@@ -29,7 +29,7 @@ Setup and Use
 2. gate.sh is the starting point to run each of the named gates, found in
    ./airship_gate/manifests, e.g.::
 
-     $ ./gate.sh multinode_genesis
+     $ ./gate.sh multinode_deploy
 
    where the argument for the gate.sh script is the filename of the json file
    in ./airship_gate/manifests without the json extension.
@@ -39,6 +39,9 @@ Setup and Use
 
    then it will by default stand up a four-node Airship cluster.
 
+   If you'd like to bring your own manifest to drive the framework, you can
+   set and export the GATE_MANIFEST env var prior to running gate.sh
+
 Each of the defined manifests used for the gate defines a virtual machine
 configuration, and the steps to run as part of that gate. Additional
 information found in each file is a configuration that targets a particular
@@ -54,3 +57,165 @@ incorporating the necessary identifying information needed for a particular
 run of a gate. E.g.::
 
   $ ./airship_gate/bin/ssh.sh n0
+
+Writing Manifests
+-----------------
+
+Custom manifests can be used to drive this framework with testing outside
+the default virtual site deployment scenario. Here is some information on
+how to create a manifest to define custom network or VM configuration or
+run a custom stage pipeline. Manifest files are written in JSON and the
+documentation below will use dotted JSON paths when describing structure.
+Unless the root is otherwise defined, assume it is from the document root.
+
+Network Configuration
+#####################
+
+The ``.networking`` key defines the network topology of the site. Each
+subkey is the name of a network. Under each network name is a semi-recursive stanza
+defining the layer 2 and layer 3 attributes of the network:
+
+.. code-block: json
+
+  {
+    "roles": ['string'],
+    "layer2": {
+      "mtu": integer,
+      "address": 'mac_address'
+    },
+    "layer3": {
+       "cidr": "CIDR",
+       "address": "ip_address",
+       "gateway": "ip_address",
+       "routing": {
+         "mode": "nat"
+       }
+     }
+  }
+
+or
+
+.. code-block: json
+
+  {
+    "layer2": {
+      "mtu": integer,
+      "vlans": {
+        "integer": {
+          "layer2":...,
+          "layer3":...
+        },
+        "integer": {
+          "layer2":...,
+          "layer3":...
+        }
+      }
+    }
+  }
+
+
+  * roles - These strings are used to select the correct network for internal gate
+    functions - supported: "ssh", "dns", "bgp"
+  * layer2 - Define Layer 2 attributes
+  * layer3 - Valid if the ``layer2`` attribute is NOT defining VLANs, then define
+    Layer 3 attributes.
+
+Disk Layouts
+############
+
+The ``.disk_layouts`` key defines the various disk layouts that can be assigned
+to VMs being built. Each named layout key then defines one or more block devices
+that will be created as file-backed volumes.
+
+.. code-block: json
+
+  {
+    "simple": {
+      "vda": {
+        "size": 30,
+        "io_profile": "fast",
+        "bootstrap": true
+      }
+    },
+    "multi": {
+      "vda": {
+        "size": 15,
+        "io_profile": "fast",
+        "bootstrap": true
+      },
+      "vdb": {
+        "size": 15,
+        "io_profile": "fast",
+        "format": {"type": "ext4", "mountpoint": "/var"}
+      }
+    }
+  }
+
+
+  * size - Size of the volume in gigabytes
+  * io_profile - One of the below I/O configurations
+    * fast - In the case of a VM disruption, synchronous I/O may be lost. Better throughput.
+    * safe - Synchronous I/O fully written to disk, slower throughput.
+  * bootstrap - For VMs that are bootstrapped by the framework, not Airship, use this disk
+  * format - For VMs that are bootstrapped by the framework, describe how the disk should be
+    formatted and mounted when desired.
+    * type - Filesystem type (e.g. 'xfs' or 'ext4')
+    * mountpoint - Path to mountpoint
+
+VM Configuration
+################
+
+Under the ``.vm`` key is a mapping of all the VMs that will be created via virt-install.
+This can be a mix of VMs that are bootstrapped via virsh/cloud-init and those deployed
+via Airship. Each key is the name of a VM and value is a JSON object:
+
+.. code-block: json
+
+    {
+      "memory": integer,
+      "vcpus": integer,
+      "disk_layout": "simple",
+      "networking": {
+        "ens3": {
+          "mac": "52:54:00:00:be:31",
+          "pci": {
+            "slot": 3,
+            "port": 0
+          },
+          "attachment": {
+            "network": "pxe"
+          }
+        },
+        "addresses": {
+          "pxe": {
+             "ip": "172.24.1.9"
+          }
+        }
+      },
+      "bootstrap": true,
+      "userdata": "packages: [docker.io]"
+    }
+
+  * memory - VM RAM in megabytes
+  * vcpus - Number of VM CPUs
+  * disk_layout - A disk profile for the VM matching one defined under ``.disk_layouts``
+  * bootstrap - True/False for whether the framework should bootstrap the VM's OS
+  * userdata - Cloud-init userdata to feed the VM when bootstrapped for further customization
+  * networking - Network attachment and addressing configuration.  Every key but ``addresses``
+    is assumed to be a desired NIC on the VM. For each NIC stanza, the following fields are respected:
+
+      * mac - A MAC address for the NIC
+      * pci - A JSON object specifying ``slot`` and ``port`` specifying the PCI address for the NIC
+      * attachment - What network from ``.networking`` is attached to this NIC
+
+    The ``addresses`` key specifies the IP address for each layer 3 network that the VM is attached to.
+
+Stage Pipeline
+##############
+
+TODO
+
+External Access
+###############
+
+TODO