Updated AIAP documentation for infra-builder

Documentation to :

 * Update and infra-builder docker image.
 * Deploy using changes
 * Debug changes.

Closes: #651
Change-Id: I4e85f438b13c1215bbb524dab5ecb743dd13b63a

tools/airship-in-a-pod/README.md

@@ -180,3 +180,115 @@ caching:
 * If using a cached ephemeral iso, the iso must first be contained in a tarball named `iso.tar.gz`, must be stored in the
   `$CACHE_DIR/` directory, and the developer must have set
   `USE_CACHED_ISO` to `true`.
+
+## Infra-builder
+
+Airship-in-a-Pod uses the infra-builder container, which sets up 3 VMs by default:
+
+1) Ephemeral node
+2) Target node(s) **note:** Later assigned control plane
+3) Worker node(s)
+
+###  Directory structure
+
+Display of `tree` program at `airshipctl/tools/airship-in-a-pod`:
+```
+├── infra-builder
+│   ├── Dockerfile
+│   └── assets
+│       ├── entrypoint.sh
+│       └── opt
+│           └── ansible
+│               └── playbooks
+│                   ├── build-infra.yaml
+│                   └── roles
+│                       ├── build-infra
+│                       │   ├── defaults
+│                       │   │   └── main.yaml
+│                       │   ├── tasks
+│                       │   │   ├── create-vm.yaml
+│                       │   │   ├── create-worker-nodes.yaml
+│                       │   │   └── main.yaml
+│                       │   └── templates
+│                       │       ├── air_nat.xml.j2
+│                       │       ├── air_prov.xml.j2
+│                       │       ├── default.xml.j2
+│                       │       └── default_network.xml.j2
+│                       └── install-kustomize
+│                           ├── defaults
+│                           │   └── main.yaml
+│                           └── tasks
+│                               └── main.yaml
+```
+The infra-builder container is based on a container image that can be updated to specify what you would like the services and VM's to look like by editing the defaults file:
+
+`airshipctl/tools/airship-in-a-pod/infra-builder/assets/opt/ansible/playbooks/roles/build-infra/defaults/main.yaml`
+
+This is the default configuration:
+
+```
+ephemeral_node:
+  name: air-ephemeral
+  cpu: 4
+  ram: 6144
+  nat_mac_address: [ "52:54:00:9b:27:02" ]
+  prov_mac_address: [ "52:54:00:b6:ed:02" ]
+  block:
+    - 30G
+
+target_nodes:
+  count: 1
+  name: air-target
+  cpu: 2
+  ram: 7168
+  nat_mac_address: [ "52:54:00:9b:27:4c" ]
+  prov_mac_address: [ "52:54:00:b6:ed:31" ]
+  block:
+    - 30G
+
+worker_nodes:
+  count: 1
+  name: air-worker
+  cpu: 2
+  ram: 7168
+  nat_mac_address: [ "52:54:00:9b:27:07" ]
+  prov_mac_address: [ "52:54:00:b6:ed:23" ]
+  block:
+    - 30G
+
+```
+
+### Alternative configurations
+
+The default configuration above is sufficient for basic testing. However, if you need a different VM configuration, you can change the defaults as described below. (e.g. 3 target nodes and 2 worker nodes).
+
+#### Prerequisites :
+
+  * If you are using Azure, make sure you select a resource size capable of creating VM's required. The default size `Standard_D8s_v3` may not be large enough depending on your specification. You can update the `aiap-in-aks.sh` script : `az aks create --name ${CLUSTER} --resource-group ${GROUP} --node-count 1 --node-vm-size Standard_D8s_v3`
+
+#### Steps to reconfigure infra-builder
+
+**Note:** If using Azure, make sure to select "build images" on the AIAP pipeline.
+
+1) Update `default configuration` file to include alternative configuration.
+
+  * Update count to match the desired number.
+  * Add new mac addresses for 2nd or third devices.
+
+2) Run the pipeline or airship-in-a-pod build script.
+
+  * Ansible will create vm step by step using configuration files.
+
+  **Note:** This output is not the order you will see on the logs
+
+```
+TASK [build-infra : Create ephemeral node] *************************************
+included: /opt/ansible/playbooks/roles/build-infra/tasks/create-vm.yaml for localhost
+
+TASK [build-infra : Create target nodes] ***************************************
+included: /opt/ansible/playbooks/roles/build-infra/tasks/create-vm.yaml for localhost => (item=1)
+
+TASK [build-infra : Create worker nodes] ***************************************
+included: /opt/ansible/playbooks/roles/build-infra/tasks/create-vm.yaml for localhost => (item=1)
+```
+You should see output for each VM you specify under each `build-infra` step in ansible logs in the infra-builder container.