docs(aio): adds quick start guide

This puts in a quick start guide for the all-in-one setup.
Removed unused indexes on Welcome page.
Fixed nit.

Signed-off-by: Tin Lam <tin@irrational.io>
Change-Id: Icd1e47157c7a60d85655baf4b7fcd6089766dd33

doc/source/index.rst

@@ -3,18 +3,11 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to airship-charts's documentation!
+Welcome to Airship Chart's documentation!
-==========================================
+=========================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-
+   install/index
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/source/install/cicd/aio-detail.rst

@@ -0,0 +1,37 @@
+==================
+All-In-One Details
+==================
+
+Override-able Variables
+=======================
+
+The all-in-one script provides a number of environment variables that users
+can alter the behavior.
+
+- ``DEPLOY_K8S``. Default value: ``true``. Setting this value to ``false`` will
+  cause the script to not execute the Kubernetes deployment script. User is
+  expected to have a Kubernetes cluster running, with ``kubectl`` and ``helm``
+  (version 3) available that interact with said cluster.
+- **Namespaces**: the Kubernetes and helm namespaces the charts will deploy to.
+
+  - ``TEKTON_NS``. Default value: ``tekton-pipelines``.
+  - ``HARBOR_NS``. Default value: ``harbor``.
+  - ``LOKI_NS``. Default value: ``loki-stack``.
+  - ``GRAFANA_NS``. Default value: ``grafana``.
+  - ``NFS_NS``. Default value: ``nfs``.
+
+- ``HARBOR_VERSION``. Default value: ``1.5.2``. The version of the upstream
+  goharbor helm chart is pinned to a specific version to avoid unintended
+  upgrade conflict.
+- ``CHART_ROOT_PATH``. Default value: ``./charts`` This specify the path
+  of the charts. If this path is relative, it is relative the root
+  of the cloned repository.
+- Chart installation override variables. The following are provided:
+
+  - ``EXTRA_HELM_ARGS_NFS``
+  - ``EXTRA_HELM_ARGS_HARBOR``
+  - ``EXTRA_HELM_ARGS_TEKTON_PIPELINES``
+  - ``EXTRA_HELM_ARGS_TEKTON_TRIGGERS``
+  - ``EXTRA_HELM_ARGS_TEKTON_DASHBOARD``
+  - ``EXTRA_HELM_ARGS_GRAFANA``
+  - ``EXTRA_HELM_ARGS_LOKI_STACK``

doc/source/install/cicd/aio-proxy.rst

@@ -0,0 +1,38 @@
+===============================
+All-In-One Behind HTTP(S) Proxy
+===============================
+
+.. note::
+  If you are **not** deploying the All-In-One (AIO) behind a proxy, you
+  can skip this page.
+
+.. hint::
+  Set the environment variables: ``HTTP_PROXY``, ``HTTPS_PROXY``, and ``NO_PROXY``.
+
+By default, AIO will use Google DNS Server IPs (``8.8.8.8`` and ``8.8.4.4``)
+and will update ``/etc/resolv.conf`` as a result. If those IPs are blocked by
+your proxy, running the AIO script will result in the inability to connect to
+anything on the network.
+
+.. literalinclude:: ../../../../tools/gate/deploy-k8s.sh
+    :language: shell
+    :lines: 33-43
+    :caption: ``resolv.conf`` setting
+
+In the case this is run behind a proxy, specifying the proxy informatin
+in the environment variable ``$HTTP_PROXY`` will reserve the nameserver
+in ``/etc/resolv.conf``.
+
+To ensure minikube has the appropriate proxy information, set the environment
+variables: ``HTTP_PROXY``, ``HTTPS_PROXY``, and ``NO_PROXY`` with the
+appropriate strings. Minikube would be started with the correct docker
+environment variable set.
+
+.. literalinclude:: ../../../../tools/gate/deploy-k8s.sh
+    :language: shell
+    :lines: 112-118
+    :caption: minikube proxy setting
+
+.. note::
+  Depending on your specific proxy, ``https_proxy`` may be the same as ``http_proxy``.
+  Refer to your specific proxy documentation.

doc/source/install/cicd/aio-quick-start.rst

@@ -0,0 +1,115 @@
+======================
+All-In-One Quick Start
+======================
+
+Initial Setup
+=============
+
+It is strongly recommended that the following be performed in a virtual
+machine (VM).
+
+Run AIO Setup Script
+====================
+
+Clone the `Airship Charts repository <https://opendev.org/airship/charts>`_ by:
+
+.. code:: bash
+
+   git clone https://opendev.org/airship/charts.git airship-charts
+
+Go into the directory and run:
+
+.. code:: bash
+
+   ./tools/utils/aio-setup.sh
+
+.. note:: You can set ``DEPLOY_K8S`` environment variable to ``false`` if you
+   have a Kubernetes cluster and do not wish to deploy a new cluster when
+   running the script.
+
+.. note:: The script sets up a ``none``-driver minikube Kubernetes cluster and
+   installs a version 3 ``helm`` executable. If you want to use your own cluster
+   by setting ``DEPLOY_K8S`` to ``false``, you will need to ensure ``kubectl``
+   and ``helm`` are available.
+
+
+Script Completion
+=================
+
+The script should deploy a minikube Kubernetes node with Calico support enabled.
+Further, it should deploy the following charts into its respective namespace:
+
++------------------------+-----------------------------+
+| Chart                  | Namespace                   |
++========================+=============================+
+| ``harbor``             | harbor                      |
++------------------------+-----------------------------+
+| ``tekton-pipelines``   | tekton-pipelines            |
++------------------------+-----------------------------+
+| ``tekton-dashboard``   | tekton-pipelines            |
++------------------------+-----------------------------+
+| ``tekton-triggers``    | tekton-pipelines            |
++------------------------+-----------------------------+
+| ``nfs-provisioner``    | nfs                         |
++------------------------+-----------------------------+
+| ``grafana``            | grafana                     |
++------------------------+-----------------------------+
+| ``loki``               | loki-stack                  |
++------------------------+-----------------------------+
+
+.. code:: bash
+
+   $ helm ls -A
+   NAME            	NAMESPACE       	REVISION	UPDATED                                	STATUS  	CHART                 	APP VERSION
+   grafana         	grafana         	1       	2020-12-18 10:05:44.266366139 -0600 CST	deployed	grafana-6.1.15        	7.3.3
+   harbor          	harbor          	1       	2020-12-17 16:22:37.606705989 -0600 CST	deployed	harbor-1.5.2          	2.1.2
+   loki            	loki-stack      	1       	2020-12-18 10:04:17.473045347 -0600 CST	deployed	loki-stack-2.2.0      	v2.0.0
+   nfs-provisioner 	nfs             	1       	2020-12-17 16:22:34.450821264 -0600 CST	deployed	nfs-provisioner-0.1.1 	v2.2.1
+   tekton-dashboard	tekton-pipelines	1       	2020-12-17 16:22:42.038851986 -0600 CST	deployed	tekton-dashboard-0.1.0	v0.10.1
+   tekton-pipelines	tekton-pipelines	1       	2020-12-17 16:22:39.78742555 -0600 CST 	deployed	tekton-pipelines-0.1.0	v0.16.3
+   tekton-triggers 	tekton-pipelines	1       	2020-12-17 16:22:40.750189048 -0600 CST	deployed	tekton-triggers-0.1.0 	v0.9.1
+
+You can also inspect the pods and ensure they are all running:
+
+.. code:: bash
+
+   $ kubectl get pod -A
+   NAMESPACE          NAME                                           READY   STATUS      RESTARTS   AGE
+   grafana            grafana-58485fc6d5-s45d6                       1/1     Running     0          74s
+   harbor             harbor-harbor-chartmuseum-5f7dccc958-kqq6n     1/1     Running     0          17h
+   harbor             harbor-harbor-clair-b56498fcd-2tfl4            2/2     Running     4          17h
+   harbor             harbor-harbor-core-7ccc475687-n9cbh            1/1     Running     0          17h
+   harbor             harbor-harbor-database-0                       1/1     Running     0          17h
+   harbor             harbor-harbor-jobservice-ddc4f6b49-c9cdz       1/1     Running     0          17h
+   harbor             harbor-harbor-notary-server-6fd6567fc8-nb7zf   1/1     Running     1          17h
+   harbor             harbor-harbor-notary-signer-7895b57c78-gw2tm   1/1     Running     1          17h
+   harbor             harbor-harbor-portal-7d69b5598f-mj99d          1/1     Running     0          17h
+   harbor             harbor-harbor-redis-0                          1/1     Running     0          17h
+   harbor             harbor-harbor-registry-6755d8586b-p5mtp        2/2     Running     0          17h
+   harbor             harbor-harbor-trivy-0                          1/1     Running     0          17h
+   kube-system        calico-kube-controllers-675b7c9569-lntn4       1/1     Running     0          3d19h
+   kube-system        calico-node-kpt5k                              1/1     Running     0          3d19h
+   kube-system        coredns-f9fd979d6-zl5gp                        1/1     Running     0          3d19h
+   kube-system        etcd-minikube                                  1/1     Running     0          3d19h
+   kube-system        kube-apiserver-minikube                        1/1     Running     0          3d19h
+   kube-system        kube-controller-manager-minikube               1/1     Running     0          3d19h
+   kube-system        kube-proxy-pdpd9                               1/1     Running     0          3d19h
+   kube-system        kube-scheduler-minikube                        1/1     Running     0          3d19h
+   kube-system        storage-provisioner                            1/1     Running     0          3d19h
+   loki-stack         loki-0                                         1/1     Running     0          2m41s
+   loki-stack         loki-promtail-lmh7s                            1/1     Running     0          2m41s
+   nfs                nfs-provisioner-7d749795c6-nbdzj               1/1     Running     0          17h
+   tekton-pipelines   tekton-dashboard-5f8947b4cc-xhq4l              1/1     Running     0          17h
+   tekton-pipelines   tekton-pipelines-controller-57866c7f56-4wkzt   1/1     Running     0          17h
+   tekton-pipelines   tekton-pipelines-webhook-84c5494b44-cwmjx      1/1     Running     0          17h
+   tekton-pipelines   tekton-triggers-controller-5f5dd8c885-jsv9k    1/1     Running     0          17h
+   tekton-pipelines   tekton-triggers-webhook-55c6579868-8gcbf       1/1     Running     0          17h
+
+Testing
+=======
+
+A basic suite of tests and helm tests can be executed by running:
+
+.. code:: bash
+
+   ./tools/gate/pipelines/run-test.sh

doc/source/install/cicd/index.rst

@@ -0,0 +1,12 @@
+CICD (Harbor, Tekton, Loki-Stack)
+=================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   aio-quick-start
+   aio-detail
+   aio-proxy
+   terms-and-def

doc/source/install/cicd/terms-and-def.rst

@@ -0,0 +1,18 @@
+===========================
+Terminology and Definitions
+===========================
+
+This page defines terms and their definitions used in this document.
+
+.. list-table::
+  :widths: 10 20
+  :header-rows: 1
+
+  * - Term
+    - Definition
+  * - CI
+    - **Continuous Integration**.
+  * - Gerrit
+    - Gerrit is a free, web-based team code collaboration tool. Developers can review each
+      other's modifications on their source code using a Web browser and approve or reject those
+      changes. It integrates closely with Git.

doc/source/install/index.rst

@@ -0,0 +1,9 @@
+============
+Installation
+============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   cicd/index

tools/gate/deploy-k8s.sh

@@ -9,6 +9,7 @@ set -ex
 
 : "${HTTP_PROXY:=""}"
 : "${HTTPS_PROXY:=""}"
+: "${NO_PROXY:=""}"
 
 export DEBCONF_NONINTERACTIVE_SEEN=true
 export DEBIAN_FRONTEND=noninteractive

tox.ini

@@ -10,9 +10,24 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
 
 [testenv:docs]
 basepython = python3
-whitelist_externals = rm
+whitelist_externals =
+  rm
 deps =
   -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/build
   sphinx-build -W -b html doc/source doc/build/html
+
+[testenv:pdf-docs]
+envdir = {toxworkdir}/doc
+whitelist_externals =
+  rm
+  make
+  mkdir
+deps =
+  -r{toxinidir}/doc/requirements.txt
+commands =
+  rm -rf doc/build/pdf
+  mkdir -p doc/build/pdf/_static
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf