From 2670d67dcf98d5aa13167dcc327d753f09839eeb Mon Sep 17 00:00:00 2001 From: Scott Hussey Date: Fri, 9 Aug 2019 13:11:07 -0500 Subject: [PATCH] (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 | 167 +++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 1 deletion(-) diff --git a/tools/multi_nodes_gate/README.rst b/tools/multi_nodes_gate/README.rst index 1083527a..68279464 100644 --- a/tools/multi_nodes_gate/README.rst +++ b/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