airship/charts
Code Issues Proposed changes

docs(aio): adds quick start guide

Browse Source 
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
This commit is contained in:
Tin Lam 2020-12-18 11:26:30 -06:00 committed by Stacey Fletcher
parent cdb1710729
commit a46dfcaaec
9 changed files with 249 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/source/index.rst
View File

@ -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:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
install/index

37
doc/source/install/cicd/aio-detail.rst Normal file
View File

@ -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``

38
doc/source/install/cicd/aio-proxy.rst Normal file
View File

@ -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.

115
doc/source/install/cicd/aio-quick-start.rst Normal file
View File

@ -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

12
doc/source/install/cicd/index.rst Normal file
View File

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

18
doc/source/install/cicd/terms-and-def.rst Normal file
View File

@ -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.

9
doc/source/install/index.rst Normal file
View File

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

1
tools/gate/deploy-k8s.sh
View File

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

17
tox.ini
View File

@ -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