Browse Source

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
Evgeny L 1 year ago
3 changed files with 189 additions and 1 deletions
  1. +187
  2. +1
  3. +1

+ 187
- 0
doc/source/config_update_guide.rst View File

@@ -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 <>`__
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 <>`__.
2. **Deploy the changes**: during this stage, a user uploads the
configuration to the Airship environment and starts the deployment using
`Airship Shipyard <>`__.

.. note::

This guide assumes you have
`Airship Pegleg <>`__ and
`Airship Shipyard <>`__
tools installed and configured; please refer to
`Site Authoring and Deployment Guide <>`__
for the details.

Configuring Airship CLI

Clone the Airship Treasuremap repository and switch to correct version.


git clone
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 <>`__


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 <>`__.

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

Create an override file
with the following content:


schema: armada/Chart/v1
schema: metadata/Document/v1
name: keystone
replacement: true
abstract: false
layer: site
name: keystone-global
- method: merge
path: .
storagePolicy: cleartext
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 <>`__.
2. Start the deployment using
`Airship Shipyard <>`__.

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
configuration file of your site.


export OS_USERNAME=shipyard
export OS_PASSWORD={shipyard_password}

Upload the changes to `Airship Deckhand <>`__:


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

+ 1
- 0
doc/source/index.rst View File

@@ -193,6 +193,7 @@ Process Flows
:maxdepth: 2


+ 1
- 1
doc/source/troubleshooting_guide.rst View File

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