Add operation: unseal vault

Add a new cloud operation task page for unsealing Vault

Change-Id: I7a76468e2f8580fe06bc4f611d3cfb2ff30e39d0

deploy-guide/source/operational-tasks.rst

@@ -6,9 +6,6 @@ This page lists operational tasks that can be applied to a Charmed OpenStack
 cloud. Generally speaking, the cloud should be in a healthy state prior to
 having these operations applied to it.
 
-* `Change the Keystone admin password`_
+* :doc:`Change Keystone password <ops-change-keystone-password>`
-* `Scale down the nova-compute application`_
+* :doc:`Scale down the nova-compute application <ops-scale-down-nova-compute>`
-
+* :doc:`Unseal Vault <ops-unseal-vault>`
-.. LINKS
-.. _Change the Keystone admin password: ops-change-keystone-password.html
-.. _Scale down the nova-compute application: ops-scale-down-nova-compute.html

deploy-guide/source/ops-unseal-vault.rst

@@ -0,0 +1,75 @@
+:orphan:
+
+============
+Unseal Vault
+============
+
+Preamble
+--------
+
+The Vault service always starts in a sealed state. Unsealing is the process of
+obtaining the master key necessary to read the decryption key that decrypts the
+data stored within. Prior to unsealing, therefore, Vault cannot be accessed by
+the cloud.
+
+.. important::
+
+   Unsealing involves the input of special unseal keys, the number of which
+   depends on how Vault was originally initialised. Without these keys Vault
+   cannot be unsealed.
+
+Procedure
+---------
+
+.. note::
+
+   Ensure that the ``vault`` snap is installed on your Juju client host. You
+   will need it to manage the Vault that is deployed in your cloud.
+
+The output to :command:`juju status vault` should show that Vault is sealed:
+
+.. code-block:: console
+
+   Unit      Workload  Agent  Machine  Public address  Ports     Message
+   vault/0*  blocked   idle   3/lxd/3  10.0.0.204      8200/tcp  Unit is sealed
+
+Unseal **each** vault unit.
+
+.. COMMENT
+   If the Vault API is encrypted see operation :doc:`Configure TLS for the
+   Vault API <ops-config-tls-vault-api>` for extra information.
+
+For a single unit requiring three keys (``vault/0`` with IP address
+10.0.0.204):
+
+.. code-block:: none
+
+   export VAULT_ADDR="http://10.0.0.204:8200"
+
+   vault operator unseal <unseal-key-1>
+   vault operator unseal <unseal-key-2>
+   vault operator unseal <unseal-key-3>
+
+The output to :command:`juju status vault` should eventually contain:
+
+.. code-block:: console
+
+   Unit      Workload  Agent  Machine  Public address  Ports     Message
+   vault/0*  active    idle   0/lxd/0  10.0.0.204      8200/tcp  Unit is ready (active: true, mlock: disabled)
+
+.. note::
+
+   It can take a few minutes for the "ready" status to appear. To expedite,
+   force a status update: ``juju run -u vault/0 hooks/update-status``.
+
+For a Vault cluster the output should look similar to:
+
+.. code-block:: console
+
+   Unit                  Workload  Agent  Machine  Public address  Ports     Message
+   vault/0               active    idle   0/lxd/0  10.0.0.204      8200/tcp  Unit is ready (active: true, mlock: disabled)
+     vault-hacluster/1   active    idle            10.0.0.204                Unit is ready and clustered
+   vault/1*              active    idle   1/lxd/0  10.0.0.205      8200/tcp  Unit is ready (active: false, mlock: disabled)
+     vault-hacluster/0*  active    idle            10.0.0.205                Unit is ready and clustered
+   vault/2               active    idle   2/lxd/0  10.0.0.206      8200/tcp  Unit is ready (active: false, mlock: disabled)
+     vault-hacluster/2   active    idle            10.0.0.206                Unit is ready and clustered