Huge refactoring and update to the documentation

docs/dictionary/en-custom.txt

@@ -80,6 +80,8 @@ ctx
 dataplane
 dataplanenodeset
 dd'd
+ddr
+deepscrub
 delorean
 deployer
 deps
@@ -112,6 +114,7 @@ enp
 env
 envfile
 epel
+epyc
 eth
 ezzmy
 favorit
@@ -201,13 +204,15 @@ ldp
 libguestfs
 libvirt
 libvirtd
+libvirterror
 libvirt's
 ljaumtawojy
 ljaumtaxojy
 ljaumtayojy
 lkid
 lmxpynzpcnrdcmfkbwluihnvy
 localhost
+localnet
 logserver
 loopback
 losetup
@@ -238,6 +243,7 @@ namespace
 namespaces
 ncia
 ndczmditnzbhni
+netmask
 networkconfig
 networkmanager
 networktype
@@ -258,10 +264,13 @@ nopasswd
 nsawvudc
 ntp
 num
+nvme
 nwy
 oauth
 oc
 ocp
+ocpbm
+ocppr
 odkvmf
 okd
 ol
@@ -275,6 +284,7 @@ openstack
 openstackcontrolplane
 openstackdataplane
 openstackdataplanenodeset
+openstackdataplanenodesets
 openstackprovisioner
 operatorgroup
 opn
@@ -340,12 +350,14 @@ rhsm
 rhy
 rnkhwaejdughvnuzsdz
 ro
+rolename
 rootdevicehints
 rpms
 rpmss
 rsa
 rsync
 runtime
+scp
 selinux
 sha
 skbg
@@ -355,9 +367,14 @@ spxzvbhvtzxmsihbyb
 src
 sshkey
 ssl
+sso
+stderr
+stdout
+stp
 str
 stricthostkeychecking
 subnet
+subnets
 sudo
 sudoers
 svg
@@ -375,6 +392,7 @@ tmp
 tmux
 toctree
 todo
+traceback
 tripleo
 txt
 uefi
@@ -398,6 +416,7 @@ vcpus
 vda
 venv
 vexxhost
+virbr
 virsh
 virt
 virthosts
@@ -408,6 +427,7 @@ virtualmedia
 virtuser
 visudo
 vlan
+vlans
 vlc
 vm
 vms

docs/source/architecture/00_general_facts.md

@@ -0,0 +1,28 @@
+# General considerations
+
+## Overlays instead of images
+
+The infrastructure is based on [image overlays](https://www.libvirt.org/kbase/backing_chains.html)
+instead of actual base qcow2. This allows for a faster redeployment, and saves disk capacities.
+
+It also allows to modify one base image, and get multiple VMs based on that single image - this is what
+we're doing for the compute and controller: they share the same base image.
+
+CRC, on the other hand, consumes an already deployed CRC image - same goes for the OCP cluster.
+
+In that case, the first run will deploy the OpenShift service you want (CRC or dev-scripts based),
+then stop the involved VM(s), undefine all the resources in libvirt, and create overlays.
+
+That way, you're in a "deploy once, use many times", with the capacity to get a clean environment in a
+matter of minutes instead of hours.
+
+## Lightweight vs Validated Architecture
+
+The Lightweight layout, consuming CRC as an OpenShift provider, is mostly targeted for light CI and dev usage.
+CRC doesn't have HA, since it's a single-node deployment, and has a lot of hacks embedded to make it work like that.
+
+The Validated Architecture wants to be closer to an actual production infrastructure, allowing to test more features,
+especially related to HA.
+
+The OCP cluster as deployed by dev-scripts still presents some hacks, but they are really light compared to CRC. It's
+a really good way to test the product against a "close to reality" infrastructure.

docs/source/architecture/01_lightweight.md

@@ -0,0 +1,39 @@
+# Lightweight infrastructure
+
+The lightweight infrastructures involves [CRC](https://crc.dev/crc/getting_started/getting_started/introducing/),
+by default 2 other virtual machines, and 2 networks.
+
+## Layout overview
+
+The following schema will help understanding the lightweight layout:
+
+```
+.__________________________________________.
+|              Hypervisor                  |
+|                                          |
+|  [controller-0]  [crc-0]  [compute-0]    |
+|       |   |        |  |     |   |        |
+|       |   '--------'--|-----'   |        |
+|       |    osp_trunk  |         |        |
+|       '---------------'---------'--------|---{Internet/external resources}
+|             public                       |
+|__________________________________________|
+```
+
+### Networks description
+
+- `osp_trunk` is the "usual" private network that will be used to deploy with network isolation (vlans).
+- `public` is bridged to the outside, allowing the installer to fetch the needed packages, operators and container images.
+
+## Images and overlays
+
+The layout is consuming two kind of resources for the VMs: base images, being the original QCOW2 disk images, and overlays.
+
+When you run the playbook, it will fetch the base image from the location you set in the variable file (by default CentOS mirrors)
+for the controller and computes, bootstrap the CRC service, and stop it once it's ready.
+
+Then, it will create image overlays based on the base image as well as from the generated CRC image. That way,
+a second deployment will be far, far quicker, allowing you to iterate over and over.
+
+Of course, in the best possible world, you shouldn't need to redeploy the infra in order to iterate developments, but having
+this possibility is a real help, especially when times come to start over a fresh, clean environment.

docs/source/cookbooks/zuul-job-nodeset.md

@@ -1,5 +1,7 @@
 # Consume ci-framework zuul base jobs
+
 ## Existing jobs
+
 The CI Framework defines a small subset of jobs.
 
 The one you may be interested in is the multinode layout, ensuring CRC is running

docs/source/index.rst

@@ -1,6 +1,5 @@
 ..  documentation master file
 
-============
 ci-framework
 ============
 
@@ -10,6 +9,39 @@ possible. We'll walk you through everything from setting up your development
 environment to understanding our code structure and contributing to the
 project.
 
+Project purpose
+###############
+
+CI-Framework is a way to bootstrap development and CI environments for RHOSO_.
+It is not intended for a production use, and should not be treated as a persistent deployment.
+
+.. _RHOSO: https://www.redhat.com/en/blog/red-hat-openstack-services-openshift-next-generation-red-hat-openstack-platform
+
+Found a bug?
+############
+
+The project is under constant development, bugs happen.
+
+If you have such a bad encounter, please fill an `issue in Jira`_.
+
+Chose **OSPRH**  project, add **cifmw** label, and set the Workstream to **CI Framework** and the Team to **OSP CI Framework**.
+
+Please provide the following information:
+
+- your environment (OS version, ``ansible --version``)
+- commit hash of the ci-framework repository you're using (``git log -1``)
+- your environment files (yes, *all* of them - you may want to ensure the **security** field of the issue is properly set to not leak internal data)
+- the command you issued
+- task name raising the error
+- the error itself (please use the internal pastebin if it's too long)
+
+In case of emergency, or if we didn't come back to you in a reasonable time (expect a couple of days), you can ping us on our `Slack channel`_.
+
+
+.. _`issue in Jira`: https://issues.redhat.com/
+.. _`Slack channel`: https://redhat.enterprise.slack.com/archives/C04SKQ5KSJ0
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Quickstart
@@ -19,10 +51,10 @@ project.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Usage
+   :caption: Architecture
    :glob:
 
-   usage/*
+   architecture/*
 
 .. toctree::
    :maxdepth: 1
@@ -33,17 +65,18 @@ project.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Cookbooks
+   :caption: Usage
    :glob:
 
-   cookbooks/*
+   usage/*
+
 
 .. toctree::
    :maxdepth: 1
-   :caption: Internals
+   :caption: Cookbooks
    :glob:
 
-   internals/*
+   cookbooks/*
 
 .. toctree::
    :maxdepth: 1