Add initial documentation for automation framework
This change together with other changes on same Gerrit topic
have been deployed to Nordix Docs website in order to bring
the docs site up while the changes are under review. Docs
site will be updated once the changes are merged.
You can see these changes live on https://docs.nordix.org.
Change-Id: Ibba765758596514626afe2997e06be4e5a5ad3d2
diff --git a/docs/cicd-guide.rst b/docs/cicd-guide.rst
new file mode 100644
index 0000000..9cc5898
--- /dev/null
+++ b/docs/cicd-guide.rst
@@ -0,0 +1,10 @@
+.. _framework-cicd-guide:
+
+============================================
+Cloud Infra Automation Framework CI/CD Guide
+============================================
+
+Introduction
+============
+
+TBD
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index c4fd171..6b2f017 100644
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1,8 +1,8 @@
-.. _developer-guide:
+.. _framework-developer-guide:
-======================
-Engine Developer Guide
-======================
+================================================
+Cloud Infra Automation Framework Developer Guide
+================================================
Introduction
============
diff --git a/docs/index.rst b/docs/index.rst
index e23868e..517a43d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@
overview.rst
user-guide.rst
developer-guide.rst
+ cicd-guide.rst
Indices and Tables
==================
diff --git a/docs/overview.rst b/docs/overview.rst
index 245c78c..b8b256a 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -1,10 +1,103 @@
-.. _overview:
+.. _framework-overview:
-===============
-Engine Overview
-===============
+=========================================
+Cloud Infra Automation Framework Overview
+=========================================
Introduction
============
-TBD
+Developers taking part in Nordix Community contribute to various open source
+communities such as OpenStack, Kubernetes, and ONAP. Automation is crucial
+for developers to easily bring up and tear down latest and greatest versions
+of the open source technologies. Cloud Infra Automation Framework is developed
+to address the needs of the developers and the Nordix Community at large.
+
+Apart from enabling developers to access the technologies they need, Nordix
+Community sees Continuous Integration (CI) and Continuous Delivery (CD) as
+prerequisites for sustainable development. Cloud Infra Automation Framework
+helps establishing CI/CD pipelines from the upstream communities in to Nordix.
+
+Approach to Supporting Different Technologies and Compositions
+==============================================================
+
+There are very many different cloud and network automation technologies
+Nordix Community members contribute to and this framework aims to provide
+support for these technologies.
+
+Cloud Infra Automation Framework uses a concept named *scenario*. A scenario
+is a composition of different technologies, the features, and the
+configurations that constitue the stack. An example to this could be Kubernetes
+using Kata Containers as runtime and Flannel as network plugin. Another example
+could be OpenStack using OVS DPDK and OpenDaylight as SDN Controller.
+
+Current scenarios supported by the framework can be seen in the User Guide.
+
+Technical Details of the Framework
+==================================
+
+Cloud Infra Automation Framework is written in Ansible. Bash scripts are
+used as necessary in order to setup the environment for Ansible. More
+details are available in the User Guide. If you intend to contribute to
+the development of the framework to add new features or issue bugfixes,
+you can take a look at Developer Guide which contains extensive information
+about how things are structured.
+
+Capabilities of the Framework
+=============================
+
+Cloud Infra Automation Framework has various capabilities which help developers
+and users to develop, deploy, test and use what they need when they need it. These
+capabilities include
+
+* provisioning of the target nodes (baremetal nodes, libvirt VMs or instances
+ on OpenStack depending on the scenario)
+* installation of the stack with different compositions (platform, features,
+ configurations)
+* testing of the installed stacks
+
+Apart from the basic capabilities, the framework makes it possible for developers
+and users to deploy majority of the scenarios on their personal computers due
+to conservative use of resources.
+
+Please consult :ref:`User Guide <framework-user-guide>` to see how you can use the
+framework.
+
+Framework and CI/CD
+===================
+
+As noted in previous sections, the framework is heavily utilized by Nordix CI/CD
+pipelines to deploy, test, and promote various scenarios. The idea with this
+is that Nordix aims to do deployment and testing of various technologies
+exactly the same way as its fellow contributers. So the framework is constantly
+tested and verified.
+
+How to Use This Documentation
+=============================
+
+The way we suggest you to use this documentation is actually trying things while
+reading them.
+
+* :ref:`User Guide <framework-user-guide>`: This is where the details of what is
+ supported by the framework and steps to use it from most basic scenario to
+ more complex ones.
+* :ref:`CI/CD Guide <framework-cicd-guide>`: This guide describes cloud infra CI/CD
+ pipelines which uses the framework. This could give you an idea about Nordix
+ approach to CI/CD and what type and level of testing the framework is subject to.
+ Apart from this, Nordix CI/CD is a working example of how to use the framework.
+* :ref:`Developer Guide <framework-developer-guide>`: This is the most detailed guide
+ which goes into the details of how to hack the framework in order to develop new
+ features, fix bugs, and introduce new technologies.
+
+Communication
+=============
+
+Cloud Infra Automation Framework is developed by Nordix Infra Team. The team uses
+`Nordix Discuss Maillist <https://lists.nordix.org/mailman/listinfo/discuss>`_ so
+if you experience any issues, we suggest you to send an email to the maillist,
+describing the issue you face accompanied by any logs you can collect and put on
+on paste sharing services such as `hastebin <https://hastebin.com/>`_ or
+`pastebin <https://pastebin.com/>`_. Please make sure not to include any private
+information such as passwords or SSH keys in the logs you upload to these services
+since they are public and the private information you include unintentially can
+be used for malicious purposes.
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 4ff50e2..0bc0173 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -1,10 +1,229 @@
-.. _user-guide:
+.. _framework-user-guide:
-=================
-Engine User Guide
-=================
+===========================================
+Cloud Infra Automation Framework User Guide
+===========================================
Introduction
============
+Cloud Infra Automation Framework provides one-command deployments
+of various open source cloud technologies and different configurations
+of those.
+
+This guide is structured in a way to give the users the most basic
+way to start using the framework. Later sections are structured after
+the technologies as they have differences such as the target environment
+support and so on.
+
+Running Your First Deployment
+=============================
+
+In order to give a quick try to framework and see its capabilities,
+you need to run **3** commands in total. Once the execution of the command
+is completed, you will have fully functional platform which you can play
+with or get rid of it and deploy another and perhaps different one
+that serves your needs better.
+
+Requirements
+------------
+
+Before proceeding with the steps, it is important to list the requirements
+for this simple stack. You need to have a decent Linux computer with
+the distro and specs below.
+
+* Linux Distribution: Ubuntu 1804
+* Minimum no of cores: 10
+* Minimum RAM: 14G
+* Minimum Disk Space: 150G
+
+If you do not have a computer which meets the minimum requirements, you can
+always reach out to Nordix Infra Team on `Nordix Discuss Maillist <https://lists.nordix.org/mailman/listinfo/discuss>`_
+and asks to borrow resources for trying things out.
+
+Deploy Now!
+-----------
+
+As promised above, here are the commands you need to run to get your
+first deployment started. We will start with cloning the Git repository
+where the framework is developed and version controlled followed by the
+actual command to initiate the deployment.
+
+1. Clone the repository from Nordix Gerrit
+
+ | ``git clone https://gerrit.nordix.org/infra/engine.git``
+
+2. Navigate to engine directory in your clone
+
+ | ``cd engine/engine``
+
+3. Issue the command to initiate the deployment
+
+ | ``./deploy.sh``
+
+and that's it. It will take approximately 40 to 50 minutes for deployment
+to complete.
+
+What Just Happened and What You Have There?
+-------------------------------------------
+
+When you issue *deploy.sh* command, the framework starts with preparing
+your machine by installing few requirements which you can see by looking
+into *engine/bindep.txt* followed by creating of Python virtualenv to
+install Python dependencies listed in *engine/requirements.txt*.
+
+Once the basic preparation is done, the next step is cloning the repositories
+that are needed for framework to continue with the rest.
+
+After completion of this step, framework creates 2 libvirt VMs and installs the
+provisioning tool `OpenStack Bifrost <https://docs.openstack.org/bifrost/latest/>`_.
+After the installation of the provisioning tool, the VMs are booted up
+and the provisioning process starts. The VMs will be PXE booted and they
+are supplied the operating system images which is Ubuntu 1804. They
+are remotely controlled by Bifrost to power cycle which the framework
+uses `OpenStack VirtualBMC <https://docs.openstack.org/virtualbmc/latest/user/index.html>`_.
+
+After the completion of the provisioning, the VMs have remote connectivity
+but their configuration is incomplete. At this step, the framework proceeds
+with various configuration steps on the VMs such as installing operating system
+packages network configuration and so on.
+
+Basic configuration of the VMs is followed by yet another clone operation
+which we pull down the installer for the platform we have chosen to install.
+The default configuration that gets deployed by the framework is Kubernetes
+with Calico Network Plugin. The framework uses another open source tool
+from CNCF named `Kubespray <https://github.com/kubernetes-sigs/kubespray>`_.
+Kubespray is a `CNCF certified Kubernetes Distribution <https://www.cncf.io/certification/software-conformance/>`_
+so what you get in the end is pretty solid. In addition to Kubernetes itself
+with Calico Network Plugin, the stack will have `Helm <https://helm.sh/>`_
+and `Prometheus <https://prometheus.io/>`_ so you can use this deployment
+for real development purposes.
+
+Once the installation of Kubernetes together with the components end, you
+will be presented with a summary and the script will exit successfully - at
+least this is what we hope at this point. You should have **kubectl** and
+**helm** client installed on your machine to operate against Kubernetes cluster.
+
+We already noted what you get in the end but we list them here as well to
+summarize the deployment you have.
+
+* Platform: Kubernetes
+* Network Plugin: Calico
+* Storage: CEPH installed using Rook
+* Application Development: Helm
+* Metrics/Monitoring: Prometheus
+
+Congratulations, you made it! \o/
+
+Scenarios Supported by Cloud Infra Automation Framework
+=======================================================
+
+As noted in earlier sections, the framework supports various scenarios. In
+this section, we will provide steps to deploy those scenarios and operate
+against them. This part of the guide is structured after the platforms
+as the scenarios are platform specific.
+
+OpenStack Scenarios
+-------------------
+
+Engine currently supports single OpenStack scenario with OVS and CEPH.
+Deployment of this scenario is same as the default scenario you deployed
+by following the steps documented in *Running Your First Deployment*
+with few additional parameters to set the right scenario.
+
+
+The machine requirements are same as the one you deployed earlier but
+putting them here as well for the sake of completion.
+
+
+* Linux Distribution: Ubuntu 1804
+* Minimum no of cores: 10
+* Minimum RAM: 14G
+* Minimum Disk Space: 150G
+
+
+What happens during the deployment process is nearly the same as the default
+scenario as well - the framework creates libvirt VMs, provisions them using
+Bifrost, and configures them. The main difference here is the configuration
+as the network setup for OpenStack deployments is different from Kubernetes
+deployments.
+
+
+Provisioning is followed by installation of OpenStack which is perhaps the
+biggest difference comparing to the deployment of the Kubernetes based default
+scenario. For OpenStack installation, framework utilizes OpenStack installer
+`Kolla-Ansible <https://docs.openstack.org/kolla-ansible/latest/>`_.
+
+
+Now the commands to issue.
+
+1. Clone the repository from Nordix Gerrit - *you can skip this step if you have the clone already*
+
+ | ``git clone https://gerrit.nordix.org/infra/engine.git``
+
+2. Navigate to engine directory in your clone
+
+ | ``cd engine/engine``
+
+3. Issue the command to initiate the deployment
+
+ | ``./deploy.sh -d kolla -s os-nosdn-nofeature -c``
+
+Once the installation of OpenStack together with the components end, you
+will be presented with a summary and the script will exit successfully.
+Your machine will have the OpenStack clients installed and openrc file
+so you can operate against your deployment. Please note that you may
+need to activate Python virtual environment to access them which you
+can do using the command below.
+
+ | ``source /opt/engine/.venv/bin/activate``
+
+We already noted what you get in the end but we list them here as well to
+summarize the deployment you have.
+
+
+* Platform: OpenStack
+* Networking: Neutron with OVS
+* Storage: CEPH
+
+
+Installed OpenStack components are
+
+* Keystone
+* Nova
+* Neutron
+
+ - OVS
+ - VXLAN
+
+* Heat
+* Glance
+* Cinder
+
+ - CEPH as volume backend
+ - NFS as backup backend
+
+* Horizon
+
+Installed infra services are
+
+* RabbitMQ
+* MariaDB
+* Memcached
+* Chrony
+* Fluentd
+
+Kubernetes Scenarios
+--------------------
+
+TBD
+
+ONAP Scenarios
+--------------
+
+TBD
+
+Testing Your Deployments
+========================
+
TBD