From a46dfcaaece1493494216ca896ade18e0d4c7993 Mon Sep 17 00:00:00 2001 From: Tin Lam Date: Fri, 18 Dec 2020 11:26:30 -0600 Subject: [PATCH] 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 Change-Id: Icd1e47157c7a60d85655baf4b7fcd6089766dd33 --- doc/source/index.rst | 13 +-- doc/source/install/cicd/aio-detail.rst | 37 +++++++ doc/source/install/cicd/aio-proxy.rst | 38 +++++++ doc/source/install/cicd/aio-quick-start.rst | 115 ++++++++++++++++++++ doc/source/install/cicd/index.rst | 12 ++ doc/source/install/cicd/terms-and-def.rst | 18 +++ doc/source/install/index.rst | 9 ++ tools/gate/deploy-k8s.sh | 1 + tox.ini | 17 ++- 9 files changed, 249 insertions(+), 11 deletions(-) create mode 100644 doc/source/install/cicd/aio-detail.rst create mode 100644 doc/source/install/cicd/aio-proxy.rst create mode 100644 doc/source/install/cicd/aio-quick-start.rst create mode 100644 doc/source/install/cicd/index.rst create mode 100644 doc/source/install/cicd/terms-and-def.rst create mode 100644 doc/source/install/index.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index f7c6ccac..e34ec0eb 100644 --- a/doc/source/index.rst +++ b/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: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + install/index diff --git a/doc/source/install/cicd/aio-detail.rst b/doc/source/install/cicd/aio-detail.rst new file mode 100644 index 00000000..a0ddcb95 --- /dev/null +++ b/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`` diff --git a/doc/source/install/cicd/aio-proxy.rst b/doc/source/install/cicd/aio-proxy.rst new file mode 100644 index 00000000..15e540b2 --- /dev/null +++ b/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. diff --git a/doc/source/install/cicd/aio-quick-start.rst b/doc/source/install/cicd/aio-quick-start.rst new file mode 100644 index 00000000..5e0b441d --- /dev/null +++ b/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 `_ 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 diff --git a/doc/source/install/cicd/index.rst b/doc/source/install/cicd/index.rst new file mode 100644 index 00000000..89e32a9e --- /dev/null +++ b/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 diff --git a/doc/source/install/cicd/terms-and-def.rst b/doc/source/install/cicd/terms-and-def.rst new file mode 100644 index 00000000..18357e88 --- /dev/null +++ b/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. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..992a0fe7 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,9 @@ +============ +Installation +============ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + cicd/index diff --git a/tools/gate/deploy-k8s.sh b/tools/gate/deploy-k8s.sh index a82d487d..c5f18467 100755 --- a/tools/gate/deploy-k8s.sh +++ b/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 diff --git a/tox.ini b/tox.ini index 4618a237..6a8e74f6 100644 --- a/tox.ini +++ b/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