From e08cedd88c945449c6b7b57c4d353b7f00546e98 Mon Sep 17 00:00:00 2001 From: James Gu Date: Wed, 29 Jan 2020 13:38:15 -0800 Subject: Add local doc build Added local doc build. Change-Id: Ie2114b9f0c1ba308c42d10f3cf5c86d6849851cc Signed-off-by: James Gu --- .gitignore | 1 + docs/conf.py | 1 + docs/conf.yaml | 3 + docs/index.rst | 16 ++ docs/release/installation/index.rst | 16 +- .../installation/installation.instruction.rst | 177 ++++++++++++++++++++- docs/release/release-notes/index.rst | 8 +- docs/release/release-notes/release-notes.rst | 5 - docs/requirements.txt | 5 + tox.ini | 19 +++ 10 files changed, 220 insertions(+), 31 deletions(-) create mode 100644 .gitignore create mode 100644 docs/conf.py create mode 100644 docs/conf.yaml create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt create mode 100644 tox.ini diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..45e1b76 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.tox/ docs/_build/* diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..eb12e74 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1 @@ +from docs_conf.conf import * # noqa: F401,F403 diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..a6ba00c --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: opnfv +project: Airship diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..50c29ad --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. (c) Open Platform for NFV Project, Inc. and its contributors + +.. _airship: + +================= +Airship Installer +================= + +.. toctree:: + :numbered: + :maxdepth: 2 + + release/release-notes/index + release/installation/index.rst diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst index 08a289d..5c1027c 100644 --- a/docs/release/installation/index.rst +++ b/docs/release/installation/index.rst @@ -2,20 +2,8 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. (c) Bin Hu and Kaspars Skels (AT&T) - -============================== -Airship Installation Procedure -============================== - -:Abstract: - -This document provides the users with the concepts and installation -procedure for deploying an NFVi with Airship Installer in a hardware -infrastructure. .. toctree:: - :numbered: - :maxdepth: 4 + :maxdepth: 3 - ./installation.instruction.rst + installation.instruction.rst diff --git a/docs/release/installation/installation.instruction.rst b/docs/release/installation/installation.instruction.rst index d497cc0..fddc31a 100644 --- a/docs/release/installation/installation.instruction.rst +++ b/docs/release/installation/installation.instruction.rst @@ -1,11 +1,176 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. (c) Bin Hu and Kaspars Skels (AT&T) +.. (c) Open Platform for NFV Project, Inc. and its contributors -================================== -Deploy NFVi with Airship Installer -================================== +************************************** +OPNFV Airship Installation Instruction +************************************** -Please visit https://wiki.opnfv.org/display/AIR/Airship+Installer+Deployment+Guide -for how to deploy NFVi with Airship Installer. +Abstract +======== + +This document describes how to deploy NFVi with Airship Installer. + +Version history +^^^^^^^^^^^^^^^ + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2020-01-21 | 0.1.0 | James Gu | First draft based | +| | | | on Wiki content | ++--------------------+--------------------+--------------------+--------------------+ + +Introduction +============ + +This document provides concepts and procedures for deploying an NFVi with Airship Installer in a +hardware infrastructure. + +This document includes the following content: + +• Introduction to the upstream tool set used by the Airship Installer, for example, `Airship Project `_, `OpenStack Helm `_, `Treasuremap `_, and so on. +• Instructions for preparing a site manifest in declarative YAML, including hardware profile and +software stack, according to the hardware infrastructure and software component model specified in +the NFVi reference model and reference architecture. +• Instructions for customizing the settings in the site manifest. +• Instructions for running the deployment script. +• Instructions for setting up a CI/CD pipeline for automating deployment and testing. + +Intel Pod 17 is used to deploy reference NFVi. Therefore, the examples in this document are based on +the hardware profile of Intel Pod 17. Instructions are either referenced (to the upstream document) or +provided (in this document) so that the reader can modify the settings of the hardware profile and/or +software stack accordingly. + +Airship +^^^^^^^ + +Airship is a collection of loosely coupled and interoperable open source tools that declaratively +automate cloud provisioning. + +Airship is a robust delivery mechanism for organizations who want to embrace containers as the new +unit of infrastructure delivery at scale. Starting from raw bare metal infrastructure, Airship manages +the full lifecycle of data center infrastructure to deliver a production-grade Kubernetes cluster with +Helm deployed artifacts, including OpenStack-Helm. Airship allows operators to manage their +infrastructure deployments and lifecycle through the declarative YAML documents that describe an +Airship environment. + +For more information, see https://www.airshipit.org. + +OpenStack Helm +^^^^^^^^^^^^^^ + +OpenStack-Helm is a set of Helm charts that enable deployment, maintenance, and upgrading of loosely +coupled OpenStack services and their dependencies individually or as part of complex environments. +For more information, see https://wiki.openstack.org/wiki/Openstack-helm. + +Treasuremap +^^^^^^^^^^^ + +Treasuremap is a deployment reference as well as CI/CD project for Airship. + +Airship site deployments use the ``treasuremap`` repository as a ``global`` manifest set (YAML configuration +documents) that are then overridden with site-specific configuration details (networking, disk layout, +and so on). + +For more information, see https://airship-treasuremap.readthedocs.io. + +Manifests +========= + +Airship is a declarative way of automating the deployment of a site. Therefore, all the deployment +details are defined in the manifests. + +The manifests are divided into three layers: ``global``, ``type``, and ``site``. They are hierarchical and meant +as overrides from one layer to another. This means that `global` is baseline for all sites, `type` is a +subset of common overrides for a number of sites with common configuration patterns (such as similar +hardware, specific feature settings, and so on), and finally the `site` is the last layer of +site-specific overrides and configuration (such as specific IP addresses, hostnames, and so on). See +`Deckhand documentation `_ for more details on layering. + +The `global` and `type` manifests can be used *as is* unless any major differences from a reference +deployment are required. In the latter case, this may introduce a new type, or even contributions to +the `global` manifests. + +The site manifests are specific for each site and are required to be customized for each new +deployment. The specific documentation for customizing these documents is located here: + +• Airship `Site Authoring and Deployment Guide `_ +• Code comments in the manifests themselves, for example `common-addresses.yaml `_ +• As well as each individual chart of components, for example, Deckhand chart `values.yaml `_ + +Global +^^^^^^ + +Global manifests, defined in Airship `Treasuremap `_, contain base configurations common to all sites. +The versions of all Helm charts and Docker images, for example, are specified in `versions.yaml `_. + +Type +^^^^ + +The type `cntt` will eventually support specifications published by the CNTT community. See `CNTT type `_. + +Site +^^^^ + +The site documents reside under the `site` folder. While the folder already contains some sites, and +will contain more in the future, the `intel-pod17` site shall be considered the Airship OPNFV reference +site. See more at `POD17 manifests `_. + +The `site-definition.yaml `_ ties together site with the specific type and `global` manifests. + +.. code-block:: yaml + + data: + site_type: cntt + + repositories: + global: + revision: v1.7 + url: https://opendev.org/airship/treasuremap.git + +Deployment +========== + +As Airship is tooling to declaratively automate site deployment, the automation from the installer +side is light. See `deploy.sh `_. + +You will need to export environment variables that correspond to the new site (`keystone` URL, node +IPs, and so on). See the beginning of the deploy script for details on the required variables. + +Once the prerequisites that are described in the Airship deployment guide (such as setting up Genesis +node), and the manifests are created, you are ready to execute deploy.sh that supports Shipyard +actions: `deploy_site` and `update_site`. + +.. code-block:: console + + $ tools/deploy.sh + Usage: deploy.sh + +CI/CD +===== + +TODO: Describe pipelines and approach +https://build.opnfv.org/ci/view/airship/ + +OpenStack +========= + +The `treasuremap` repository contains a wrapper script for running OpenStack clients tools/openstack. +The wrapper uses `heat` image that already has OpenStack client installed. + +Clone latest ``treasuremap`` code + +.. code-block:: console + + $ git clone https://github.com/airshipit/treasuremap.git + +Setup the needed environment variables, and execute the script as OpenStack CLI + +.. code-block:: console + + $ export OSH_KEYSTONE_URL='http://identity-airship.intel-pod17.opnfv.org/v3' + $ export OS_REGION_NAME=intel-pod17 + $ treasuremap/tools/openstack image list diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst index c47bfb2..d3a2f05 100644 --- a/docs/release/release-notes/index.rst +++ b/docs/release/release-notes/index.rst @@ -4,11 +4,7 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) Bin Hu and Kaspars Skels (AT&T) -============================================= -OPNFV Airship Installer Project Release Notes -============================================= - .. toctree:: - :maxdepth: 1 + :maxdepth: 3 - ./release-notes + release-notes diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index ac521b4..752214b 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -8,11 +8,6 @@ OPNFV Airship Installer Project Release Notes This document provides the release notes for Airship Installer Project. -.. contents:: - :depth: 3 - :local: - - Version History --------------- diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..4408435 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +lfdocs-conf +sphinx_opnfv_theme +# Uncomment the following line if your project uses Sphinx to document +# HTTP APIs +# sphinxcontrib-httpdomain diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..840ce6a --- /dev/null +++ b/tox.ini @@ -0,0 +1,19 @@ +[tox] +minversion = 1.6 +envlist = + docs, + docs-linkcheck +skipsdist = true + +[testenv:docs] +basepython = python3 +deps = -rdocs/requirements.txt +commands = + sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = echo + +[testenv:docs-linkcheck] +basepython = python3 +deps = -rdocs/requirements.txt +commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck -- cgit 1.2.3-korg