Review README

An HA section will be added that points to the upcoming HA guide
where Vault HA will be covered.

Change-Id: I6e67f217690f69f3d6f282aba0cba4634de70bee

src/README.md

@@ -1,27 +1,97 @@
 # Overview
 
-Vault secures, stores, and tightly controls access to tokens,
-passwords, certificates, API keys, and other secrets in modern
-computing. Vault handles leasing, key revocation, key rolling, and
-auditing. Through a unified API, users can access an encrypted
-Key/Value store and network encryption-as-a-service, or generate
-AWS IAM/STS credentials, SQL/NoSQL databases, X.509 certificates,
-SSH credentials, and more.
+[Vault][vault-upstream] secures, stores, and controls access to tokens,
+passwords, certificates, API keys, and other secrets in modern computing. Vault
+handles leasing, key revocation, key rolling, and auditing. Through a unified
+API, users can access an encrypted key/value store and network
+encryption-as-a-service, or generate AWS IAM/STS credentials, SQL/NoSQL
+databases, X.509 certificates, SSH credentials, and more.
 
-## About the Charm
+The charm installs Vault from a [snap][snap-upstream].
 
-This charm installs Vault from the Ubuntu Snap Store and
-supports the PostgreSQL and MySQL storage backends. Note that Vault itself
-does not support PostgreSQL 10, so neither does this charm. If you're
-deploying on bionic, you'll need to deploy a 9.x version of PostgreSQL.
+# Usage
 
-After deploying and relating the charm to postgresql, install
-the vault snap locally and use `vault operator init` to create the
-master key shards and the root token, and store them safely.
+## Configuration
 
-## Network Spaces support
+This section covers common configuration options. See file `config.yaml` for
+the full list of options, along with their descriptions and default values.
 
-The vault charm directly supports network binding via the 'access'
-extra-binding and the 'cluster' peer relation. These allow the Vault
-API and inter-unit Cluster addresses to be configured using Juju
-network spaces.
+#### `channel`
+
+The `channel` option sets the snap channel to use for deployment (e.g.
+'latest/edge'). The default value is 'latest/stable'.
+
+## Deployment
+
+Deploy a single vault unit in this way:
+
+    juju deploy vault
+
+Then relate it to either MySQL or PostgreSQL.
+
+For MySQL 5:
+
+    juju add-relation vault:shared-db percona-cluster:shared-db
+
+For MySQL 8:
+
+    juju deploy mysql-router vault-mysql-router
+    juju add-relation vault-mysql-router:db-router mysql-innodb-cluster:db-router
+    juju add-relation vault-mysql-router:shared-db vault:shared-db
+
+For PostgreSQL, its version and the underlying machine series must be
+compatible (e.g. 9.5/xenial or 10/bionic). Use configuration option `version`
+with the [postgresql][postgresql-charm] charm to select a version. For example,
+on Xenial:
+
+    juju deploy --config version=9.5 --series xenial postgresql
+    juju add-relation vault:db postgresql:db
+
+## Post-deployment tasks
+
+Once the vault application is deployed the following tasks must be performed:
+
+* Vault initialisation
+* Unsealing of Vault
+* Charm authorisation
+
+These tasks are covered in appendix [Vault][cdg-app-vault] of the
+[OpenStack Charms Deployment Guide][cdg].
+
+## Actions
+
+This section lists Juju [actions][juju-docs-actions] supported by the charm.
+Actions allow specific operations to be performed on a per-unit basis.
+
+* `authorize-charm`
+* `disable-pki`
+* `generate-root-ca`
+* `get-csr`
+* `get-root-ca`
+* `pause`
+* `refresh-secrets`
+* `reissue-certificates`
+* `resume`
+* `upload-signed-csr`
+
+To display action descriptions run `juju actions vault`. If the charm
+is not deployed then see file ``actions.yaml``.
+
+# Bugs
+
+Please report bugs on [Launchpad][lp-bugs-charm-vault].
+
+For general charm questions refer to the [OpenStack Charm Guide][cg].
+
+<!-- LINKS -->
+
+[cg]: https://docs.openstack.org/charm-guide
+[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/
+[lp-bugs-charm-vault]: https://bugs.launchpad.net/vault-charm/+filebug
+[juju-docs-actions]: https://jaas.ai/docs/actions
+[snap-upstream]: https://snapcraft.io/
+[vault-charm]: https://jaas.ai/vault
+[postgresql-charm]: https://jaas.ai/postgresql
+[vault-upstream]: https://www.vaultproject.io/docs/what-is-vault/
+[cdg-app-vault]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-vault.html
+[cdg-app-ha-vault]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ha.html#vault