more work on wiriging diagram design, and install section

docs/install-upgrade/build-wiring.md

@@ -3,7 +3,9 @@
 !!! warning ""
     Under construction.
 
-You can find more details in the User Guide including [switch features and port naming](../user-guide/profiles.md). It's mandatory to for all switches to reference a `SwitchProfile` in the `spec.profile` of the `Switch` object. Only port naming defined by switch profiles could be used in the wiring diagram, NOS (or any other) port names aren't supported.
+## Overview
+
+A wiring diagram is a yaml file that is a digital representation of your network. You can find more yaml level details in the User Guide section [switch features and port naming](../user-guide/profiles.md) and the [api](../reference/api.md). It's mandatory to for all switches to reference a `SwitchProfile` in the `spec.profile` of the `Switch` object. Only port naming defined by switch profiles could be used in the wiring diagram, NOS (or any other) port names aren't supported.
 
 In the meantime, to have a look at working wiring diagram for Hedgehog Fabric, run the sample generator that produces
 VLAB-compatible wiring diagrams:
@@ -26,18 +28,18 @@ OPTIONS:
    --help, -h  show help
 ```
 
-# Design Discussion
-This section is meant to help the reader understand how to assemble the primitives presented by the Fabric API into a functional fabric. This discussion starts with the primary building block, a VPC
+## Design Discussion
+This section is meant to help the reader understand how to assemble the primitives presented by the Fabric API into a functional fabric. This discussion starts with the primary building block of your design, a VPC.
 
-## VPC
+### VPC
 
-A VPC allows for isolation at layer 3. This is the main building block for users when creating their architecture. Hosts inside of a VPC will see each other but nothing else, the hosts inside of a VPC will likely need to connect to other VPCs or the outside world. To communicate between two VPC a *peering* will need to be created. A VPC can be a logical separation of workloads. By separating these workloads additional controls are available. The logical separation doesn't have to be the traditional database, web, and compute layers it could be development teams who need isolation, it could tenants inside of an office building, or any separation that allows for better control of the network. Once your VPCs are decided, the rest of the fabric will come together. With the VPCs decided traffic can be prioritized, security can be put into place, and the wiring can begin. The fabric allows for the VPC to exist beyond a single switch, which gives flexibility when the physical world meets the digital.  
+A VPC allows for isolation at layer 3. This is the main building block for users when creating their architecture. Hosts inside of a VPC will see each other but nothing else. The hosts inside of a VPC will likely need to connect to other VPCs or the outside world. To communicate between two VPC a *peering* will need to be created. A VPC can be a logical separation of workloads. By separating these workloads additional controls are available. The logical separation doesn't have to be the traditional database, web, and compute layers it could be development teams who need isolation, it could tenants inside of an office building, or any separation that allows for better control of the network. Once your VPCs are decided, the rest of the fabric will come together. With the VPCs decided traffic can be prioritized, security can be put into place, and the wiring can begin. The fabric allows for the VPC to exist beyond a single switch, which gives flexibility when the physical world meets the digital.
 
-## Connection
+### Connection
 
 A connection represents the physical wires in your data center. They connect switches to other switches or switches to servers.
 
-### Server Connections
+#### Server Connections
 
 A server connection will require server side configuration as the Fabric configuration abilities do not reach into the end hosts. A server connection can be one of: 
 
@@ -46,7 +48,29 @@ A server connection will require server side configuration as the Fabric configu
 - *MCLAG* -  two cables going to two different switches, also called dual homing. The switches will need a fabric link between them
 - *ESLAG* - two to four cables going to different switches, also called multi-homing. If four links are used there will be four switches connected to a single server with four NIC ports
 
-### Fabric Connections
+#### Fabric Connections
+
+These serve as connection between switches, their beautiful weave comprises the fabric of the network.
+
+
+### VPC Peering
+
+This is what is needed for VPCs to talk to each other. There are two varieties local and remote.
+
+#### Local VPC Peering
+
+When the VPCs that need to communicate are both on the same switch. An example would be if your database and web front end servers are in the same rack and are able to be physically cabled to the same switch.
+
+#### Remote VPC Peering
+
+When the VPCs that need to communicate are on different switches. An example would be if your storage and compute servers are in opposite ends of the data center and need to be cabled to different switches.
+
+
+
+## Design Examples
+
+### TODO - show the wiring diagram for a leaf-spine
 
-These serve as connection between switches, their beautiful weave comprise the fabric of the network.
+### TODO - show how to connect to an AWS cloud connection
 
+### TODO - show how to connect to a provider ISP like equinix

docs/install-upgrade/overview.md

@@ -7,7 +7,7 @@
 
 * A machine with access to the Internet to use Fabricator and build installer
 * An 8 GB USB flash drive, if you are not using virtual media
-* Have a machine to function as the Fabric Control Node.[System Requirements](./requirements.md)) as well as IPMI access to it to install
+* Have a machine to function as the Fabric Control Node. [System Requirements](./requirements.md) as well as IPMI access to it to install
   the OS.
 * Have a management switch with at least 1 10GbE port
 * Have enough [Supported Switches](./supported-devices.md) for your Fabric
@@ -35,20 +35,21 @@ The main steps to install Fabric are:
     1. Boot them into ONIE Install Mode to have them automatically provisioned
 
 ## Build Control Node configuration and Installer
-Hedgehog has created a command line utility, called `hhfab`, that will help generate the wiring diagram, validate the supplied configurations, and generate an installation image (.img) suitable for writing to a disk. 
+Hedgehog has created a command line utility, called `hhfab`, that will help generate the wiring diagram, validate the supplied configurations, and generate an installation image (.img) suitable for writing to a USB flash drive or mounting via IPMI virtual media.
 
 ### HHFAB commands to make a bootable image
 1. `hhfab init --wiring wiring-lab.yaml`
 1. edit the `fab.yaml` file for your needs
     1. ensure the correct boot disk (eg `/dev/sda`) and control node NIC names are supplied
 1. `hhfab validate`
-1. `hhfab build --usb`
+1. `hhfab build`
 
-The installer for the fabric will be generated in `$WORKDIR/result`. This installation image is 7.5 GB in size.
+The installer for the fabric will be generated in `$WORKDIR/result/`. This installation image is 7.5 GB in size. It is named control-1-usb.img
 
 ### Burn USB image to disk
 !!! warning ""
     This will erase data on the usb disk.
+
 - Insert the usb to your machine
 - Identify the path to your usb stick for example `/dev/sdc`
 - Issue the command to write the image to the usb drive
@@ -72,6 +73,8 @@ This control node should be given a static IP address. Either a lease or statica
 
 1. Once the install is complete the system will automatically reboot
 
+1. After the system has shutdown but before it boots up, remove the usb image from the system. Doing this during the uefi boot screen is acceptable.
+
 1. Upon booting into the freshly installed system, the fabric installation will automatically begin
     1. Optionally this can be monitored with `journalctl -f -u fabric-install.service`
 
@@ -81,6 +84,11 @@ This control node should be given a static IP address. Either a lease or statica
 
 [Move on to the next step](#fabric-manages-switches)
 
+
+### Configure Management Network
+
+The control node is dual homed. It has a 10GbE interface that connects to the managment network. The other link called `external` in the `fab.yaml` file is for the customer to access the control node.
+
 ### Fabric Manages Switches
 
 Now that the install has finished, you can start interacting with the Fabric using `kubectl`, `kubectl fabric` and `k9s`, all pre-installed as part of the Control Node installer.