Add a site update guide

The guide describes how to apply changes on already running
cluster. Describe the flow, from config change to deployment start.

Change-Id: I6be24794d570ca6b42db36f2a10b065b8e16f428

doc/source/config_update_guide.rst

@@ -0,0 +1,187 @@
+Configuration Update Guide
+==========================
+
+The guide contains the instructions for updating the configuration of
+a deployed Airship environment. Please refer to
+`Site Authoring and Deployment Guide <https://airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html>`__
+if you do not have an Airship environment already deployed.
+
+Update of an Airship environment consists of the following stages:
+
+1. **Prepare the configuration**: before deploying any changes, a user
+   should prepare and validate the manifests on a build node using
+   `Airship Pegleg <https://airship-pegleg.readthedocs.io/en/latest/>`__.
+2. **Deploy the changes**: during this stage, a user uploads the
+   configuration to the Airship environment and starts the deployment using
+   `Airship Shipyard <https://airship-shipyard.readthedocs.io/en/latest/>`__.
+
+.. note::
+
+    This guide assumes you have
+    `Airship Pegleg <https://airship-pegleg.readthedocs.io/en/latest/>`__ and
+    `Airship Shipyard <https://airship-shipyard.readthedocs.io/en/latest/>`__
+    tools installed and configured; please refer to
+    `Site Authoring and Deployment Guide <https://airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html>`__
+    for the details.
+
+Configuring Airship CLI
+-----------------------
+
+Clone the Airship Treasuremap repository and switch to correct version.
+
+::
+
+    git clone https://opendev.org/airship/treasuremap
+    cd treasuremap/
+    # List available tags.
+    git tag --list
+    # Switch to the version your site is using.
+    git checkout {your-tag}
+    # Go back to a previous directory.
+    cd ..
+
+Configure environment variables with the name of your site, and specify a path
+to the directory where site configuration is stored; for this example, we use
+`Airship Seaworthy <https://airship-treasuremap.readthedocs.io/en/latest/seaworthy.html>`__
+site:
+
+::
+
+    export SITE=airship-seaworthy
+    export SITE_PATH=treasuremap/site/airship-seaworthy
+
+Updating the manifests
+----------------------
+
+Changing the configuration consists of the following steps:
+
+1. Change site manifests.
+2. Lint the manifests.
+3. Collect the manifests.
+4. Copy the manifests to the Airship environment.
+
+Linting and collecting the manifests is done using
+`Airship Pegleg <https://airship-pegleg.readthedocs.io/en/latest/>`__.
+
+For this example, we are going to update a debug level for keystone logs
+in a site layer.
+
+.. note::
+
+    It is also possible to update the configuration in a global layer;
+    for more details on Airship layering mechanism see
+    `Pegleg Definition Artifact Layout <https://airship-pegleg.readthedocs.io/en/latest/artifacts.html>`__
+    documentation.
+
+Create an override file
+``${SITE_PATH}/software/charts/osh/openstack-keystone/keystone.yaml``
+with the following content:
+
+::
+
+    ---
+    schema: armada/Chart/v1
+    metadata:
+      schema: metadata/Document/v1
+      name: keystone
+      replacement: true
+      layeringDefinition:
+        abstract: false
+        layer: site
+        parentSelector:
+          name: keystone-global
+        actions:
+          - method: merge
+            path: .
+      storagePolicy: cleartext
+    data:
+      values:
+        conf:
+          logging:
+            logger_keystone:
+              level: DEBUG
+    ...
+
+Check that the configuration is valid:
+
+::
+
+    sudo ./treasuremap/tools/airship pegleg site -r treasuremap/ \
+      lint ${SITE}
+
+Collect the configuration:
+
+::
+
+    sudo ./treasuremap/tools/airship pegleg site \
+      -r treasuremap/ collect $SITE -s ${SITE}_collected
+
+Copy the configuration to a node that has the access to the site's
+Shipyard API, if the current node does not; this node can be one
+of your controllers:
+
+::
+
+    scp -r ${SITE}_collected {genesis-ip}:/home/{user-name}/${SITE}_collected
+
+
+Deploying the changes
+---------------------
+
+After you copied the manifests, there are just a few steps needed to start
+the deployment:
+
+1. Upload the changes to
+   `Airship Deckhand <https://airship-deckhand.readthedocs.io/en/latest/>`__.
+2. Start the deployment using
+   `Airship Shipyard <https://airship-shipyard.readthedocs.io/en/latest/>`__.
+
+Install Airship CLI as described in `Configuring Airship CLI`_ section.
+
+Set the name of your site:
+
+::
+    export SITE=airship-seaworthy
+
+Configure credentials for accessing Shipyard; the password is stored
+in ``ucp_shipyard_keystone_password`` secret, you can find it in
+``site/airship-seaworthy/secrets/passphrases/ucp_shipyard_keystone_password.yaml``
+configuration file of your site.
+
+::
+
+    export OS_USERNAME=shipyard
+    export OS_PASSWORD={shipyard_password}
+
+Upload the changes to `Airship Deckhand <https://airship-deckhand.readthedocs.io/en/latest/>`__:
+
+::
+
+    # Upload the configuration.
+    sudo -E ./treasuremap/tools/airship shipyard \
+        create configdocs ${SITE} --replace --directory=${SITE}_collected
+
+    # Commit the configuration.
+    sudo -E ./treasuremap/tools/airship shipyard commit configdocs
+
+Run the deployment:
+
+::
+
+    sudo -E ./treasuremap/tools/airship shipyard create action update_site
+
+You can also run ``update_software`` instead of ``update_site`` which skips
+hardware configuration and only applies the changes to services that are running
+on top of Kubernetes.
+
+Now you can track the deployment progress using the following commands:
+
+::
+
+    # Get all actions that were executed on you environment.
+    sudo -E ./treasuremap/tools/airship shipyard get actions
+
+    # Show all the steps within the action.
+    sudo -E ./treasuremap/tools/airship shipyard describe action/{action_id}
+
+All steps will have status ``success`` when the update finishes.

doc/source/index.rst

@@ -193,6 +193,7 @@ Process Flows
    :maxdepth: 2
 
    authoring_and_deployment
+   config_update_guide
    troubleshooting_guide
    seaworthy
    airskiff

doc/source/troubleshooting_guide.rst

@@ -25,7 +25,7 @@ how to get it configured on your environment.
     cd treasuremap/
     # List available tags.
     git tag --list
-    # Switch to the version of your site.
+    # Switch to the version your site is using.
     git checkout {your-tag}
     # Go back to a previous directory.
     cd ..