Vault
=====

This feature deploys Vault, a tool for securely managing secrets used in
modern computing (e.g. passwords, certificates, API keys).

Enabling Vault
--------------

To enable Vault, run the following command:

::

   sunbeam enable vault

Vault units will be in blocked state after this step.

Initializing Vault
------------------

To initialize Vault, run the following command:

::

   sunbeam vault init KEY_SHARES KEY_THRESHOLD

KEY_SHARES - Number of key shares to be generated by vault

KEY_THRESHOLD - Minimal number of key shares to be used to unseal vault

Output of the above command with 5 key shares and 3 key threshold looks like:

::

   Unseal keys:
   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
   cccccccccccccccccccccccccccccccccccccccccccc
   dddddddddddddddddddddddddddddddddddddddddddd
   eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

   Root token: fff.ffffffffffffffffffffffff

It is recommended to store each of the unseal keys and root token into different files
and keep them secure.

Unsealing Vault
---------------

To unseal Vault, run the following command:

::

   cat <key file> | sunbeam vault unseal -

Unsealing the Vault requires minimum KEY_THRESHOLD keys to be provided to vault.
So the unseal command should be executed KEY_THRESHOLD times. This will unseal
the vault leader unit.

To unseal the non-leader units, repeat the unseal commands again.

For example, the process to unseal the Vault with 3 units, initialized with
5 key shares and 3 key threshold looks like:

Unseal with the first key:

::

   $ cat <aaa.. key file> | sunbeam vault unseal -
   Vault unseal operation status: 2 key shares required to unseal

Unseal with the second key:

::

   $ cat <bbb.. key file> | sunbeam vault unseal -
   Vault unseal operation status: 1 key shares required to unseal

Unseal with the third key:

::

   $ cat <ccc.. key file> | sunbeam vault unseal -
   Vault unseal operation status: completed for leader unit.
   Rerun `sunbeam vault unseal` command to unseal non-leader units.

The leader unit gets unsealed and non-leader units are in sealed state.

Now repeat the process to unseal non-leader units.
Unseal with the first key:

::

   $ cat <aaa.. key file> | sunbeam vault unseal -
   Vault unseal operation status:
   vault/1 : 2 key shares required to unseal
   vault/2 : 2 key shares required to unseal

Unseal with the second key:

::

   $ cat <bbb.. key file> | sunbeam vault unseal -
   Vault unseal operation status:
   vault/1 : 1 key shares required to unseal
   vault/2 : 1 key shares required to unseal

Unseal with the third key:

::

   $ cat <ccc.. key file> | sunbeam vault unseal -
   Vault unseal operation status: completed

Unsealing vault process completed.

Authorizing Vault charm
-----------------------

To authorize vault charm, run the following command:

::

   $ cat <root token file> | sunbeam vault authorize-charm -
   Vault charm is authorized.

After 5 minutes (update-status-interval time), Juju status should show all units as active.

::

   $ juju status -m openstack vault
   Model      Controller          Cloud/Region               Version  SLA          Timestamp
   openstack  sunbeam-controller  immune-drum-k8s/localhost  3.5.4    unsupported  07:12:02Z

   SAAS       Status  Store  URL
   microceph  active  local  admin/controller.microceph

   App    Version  Status   Scale  Charm      Channel      Rev  Address         Exposed  Message
   vault           active       3  vault-k8s  1.16/stable  280  10.152.183.222  no

   Unit      Workload  Agent  Address       Ports  Message
   vault/0*  active    idle   10.1.183.201
   vault/1   active    idle   10.1.183.234
   vault/2   active    idle   10.1.183.235

   Offer                  Application            Charm                     Rev  Connected  Endpoint              Interface             Role
   cert-distributor       keystone               keystone-k8s              211  2/2        send-ca-cert          certificate_transfer  provider
   certificate-authority  certificate-authority  self-signed-certificates  155  1/1        certificates          tls-certificates      provider
   cinder-ceph            cinder-ceph            cinder-ceph-k8s           94   1/1        ceph-access           cinder-ceph-key       provider
   keystone-credentials   keystone               keystone-k8s              211  1/1        identity-credentials  keystone-credentials  provider
   keystone-endpoints     keystone               keystone-k8s              211  1/1        identity-service      keystone              provider
   nova                   nova                   nova-k8s                  106  1/1        nova-service          nova                  provider
   ovn-relay              ovn-relay              ovn-relay-k8s             95   1/1        ovsdb-cms-relay       ovsdb-cms             provider
   rabbitmq               rabbitmq               rabbitmq-k8s              34   1/1        amqp                  rabbitmq              provider
   traefik-rgw            traefik-rgw            traefik-k8s               218  1/1        traefik-route         traefik_route         provider

Vault status
------------

To see status of Vault, run the following command:

::

   sunbeam vault status

Sample output of the above command looks like:

::

              Vault Status
   +---------+-------------+-----------+
   | Unit    | Initialized | Sealed    |
   +=========+=============+===========+
   | vault/0 | True        | False     |
   | vault/1 | True        | False     |
   | vault/2 | True        | False     |
   +---------+-------------+-----------+

Disabling Vault
---------------

To disable Vault, run the following command:

::

   sunbeam disable vault

.. caution::
   Disabling Vault will completely remove it from the infrastructure,
   all secrets will be lost.