From e12bcd9a4d8de71ecde0a178feee0e5083a46105 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Mon, 26 Nov 2018 18:44:45 +0000
Subject: [PATCH] Document a backup procedure for the seed

Adds instructions for a database backup.

Change-Id: I97c4bdb4e5d7d28c06a03ceb1cc290db9b1dccb5
Story: 2004359
Task: 27959
---
 doc/source/administration/seed.rst | 91 ++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/doc/source/administration/seed.rst b/doc/source/administration/seed.rst
index ef17dd136..9d99e3bb7 100644
--- a/doc/source/administration/seed.rst
+++ b/doc/source/administration/seed.rst
@@ -31,3 +31,94 @@ To only install updates that have been marked security related::
 
 Note that these commands do not affect packages installed in containers, only
 those installed on the host.
+
+Examining the Bifrost Container
+===============================
+
+The seed host runs various services required for a standalone Ironic
+deployment. These all run in a single ``bifrost_deploy`` container.
+
+It can often be helpful to execute a shell in the bifrost container for
+diagnosing operational issues::
+
+    $ docker exec -it bifrost_deploy bash
+
+Services are run via Systemd::
+
+    (bifrost_deploy) systemctl
+
+Logs are stored in ``/var/log/kolla/``, which is mounted to the ``kolla_logs``
+Docker volume.
+
+Accessing the Seed Services
+===========================
+
+The Ironic API can be accessed via the ``openstack`` command line interface::
+
+    (bifrost_deploy) $ source env-vars
+    (bifrost_deploy) $ openstack baremetal node list
+
+Ironic inspector API requires some environment variables to be set::
+
+    (bifrost_deploy) $ unset OS_CLOUD
+    (bifrost_deploy) $ export OS_URL=http://localhost:5050
+    (bifrost_deploy) $ export OS_TOKEN=fake-token
+    (bifrost_deploy) $ openstack baremetal introspection list
+
+Backup & Restore
+================
+
+There are two main approaches to backing up and restoring data on the seed.  A
+backup may be taken of the Ironic databases. Alternatively, a Virtual Machine
+backup may be used if running the seed services in a VM.  The former will
+consume less storage. Virtual Machine backups are not yet covered here, neither
+is scheduling of backups. Any backup and restore procedure should be tested in
+advance.
+
+Database Backup & Restore
+-------------------------
+
+A backup may be taken of the database, using one of the many tools that exist
+for backing up MariaDB databases.
+
+A simple approach that should work for the typically modestly sized seed
+database is ``mysqldump``.  The following commands should all be executed on
+the seed.
+
+Backup
+^^^^^^
+
+It should be safe to keep services running during the backup, but for maximum
+safety they may optionally be stopped::
+
+    docker exec -it bifrost_deploy \
+    systemctl stop ironic-api ironic-conductor ironic-inspector
+
+Then, to perform the backup::
+
+    docker exec -it bifrost_deploy \
+    mysqldump --all-databases --single-transaction --routines --triggers > seed-backup.sql
+
+If the services were stopped prior to the backup, start them again::
+
+    docker exec -it bifrost_deploy \
+    systemctl start ironic-api ironic-conductor ironic-inspector
+
+Restore
+^^^^^^^
+
+Prior to restoring the database, the Ironic and Ironic Inspector services
+should be stopped::
+
+    docker exec -it bifrost_deploy \
+    systemctl stop ironic-api ironic-conductor ironic-inspector
+
+The database may then safely be restored::
+
+    docker exec -i bifrost_deploy \
+    mysql < seed-backup.sql
+
+Finally, start the Ironic and Ironic Inspector services again::
+
+    docker exec -it bifrost_deploy \
+    systemctl start ironic-api ironic-conductor ironic-inspector