summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorJames Gu <james.gu@att.com>2020-01-21 21:39:45 -0800
committerJames Gu <james.gu@att.com>2020-01-22 11:14:04 -0800
commit12230e534d4c2f74f2aa002ccb7b3d741a3f8d2e (patch)
tree180d0a91f53aa81eb36c01e9278a3a1f8cc7b961 /docs
parent46d2b7ebe2bd64b92b6384d0bcfd98f86e1c8ba9 (diff)
Added installation document
Moved the Airship deployment guide from wiki to the repo and integrated into the opnfvdocs project. Also integratred release notes into the opnfvdocs build. Signed-off-by: James Gu <james.gu@att.com> Change-Id: I40a4c56d659e843fb9d677e00986fb8e9013f3bc
Diffstat (limited to 'docs')
-rw-r--r--docs/index.rst16
-rw-r--r--docs/release/installation/index.rst16
-rw-r--r--docs/release/installation/installation.instruction.rst177
-rw-r--r--docs/release/release-notes/index.rst8
-rw-r--r--docs/release/release-notes/release-notes.rst5
5 files changed, 191 insertions, 31 deletions
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 <https://www.airshipit.org>`_, `OpenStack Helm <https://wiki.openstack.org/wiki/Openstack-helm>`_, `Treasuremap <https://opendev.org/airship/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 <https://airship-deckhand.readthedocs.io/en/latest/overview.html#layering>`_ 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 <https://airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html>`_
+• Code comments in the manifests themselves, for example `common-addresses.yaml <https://github.com/opnfv/airship/blob/master/site/intel-pod17/networks/common-addresses.yaml#L14>`_
+• As well as each individual chart of components, for example, Deckhand chart `values.yaml <https://github.com/airshipit/deckhand/blob/master/charts/deckhand/values.yaml>`_
+
+Global
+^^^^^^
+
+Global manifests, defined in Airship `Treasuremap <https://github.com/airshipit/treasuremap/tree/master/global>`_, contain base configurations common to all sites.
+The versions of all Helm charts and Docker images, for example, are specified in `versions.yaml <https://github.com/airshipit/deckhand/blob/master/charts/deckhand/values.yaml>`_.
+
+Type
+^^^^
+
+The type `cntt` will eventually support specifications published by the CNTT community. See `CNTT type <https://github.com/opnfv/airship/tree/master/type/cntt>`_.
+
+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 <https://github.com/opnfv/airship/tree/master/site/intel-pod17>`_.
+
+The `site-definition.yaml <https://github.com/opnfv/airship/blob/master/site/intel-pod17/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 <https://github.com/opnfv/airship/blob/master/tools/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 <deploy_site|update_site>
+
+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
---------------