Update documentation for Vault+InfluxDB

CHANGELOG.md

@@ -1,3 +1,21 @@
+# PR [#39](https://github.com/theplant/appkit/pull/39)
+
+* Add monitoring InfluxDB client that sources InfluxDB credentials
+  from Vault.
+
+* Allow creation of InfluxDB-backed monitoring client with custom
+  InfluxDB transport client.
+
+* Introduce public Vault client interface (instead of using
+  `github.com/hashicorp/vault/api.Client` directly)
+
+* Make Vault client available from service context
+
+* Allow subscription to Vault (re-)authentication via
+  `appkit/credentials/vault.Client.OnAuth`
+
+* Revoke Vault auth lease when service context is closed
+
 # PR [#38](https://github.com/theplant/appkit/pull/38)
 
 * Add support for `VAULT_AUTHN_DISABLED` to stop appkit/service

README.md

@@ -136,8 +136,16 @@ back-end.
 
 # Credentials
 
-Package to provide single interface for acquiring AWS (-only, for now)
-credentials for apps running on different platforms.
+Package to provide single interface for acquiring credentials for apps
+running on different platforms. Credentials that can be sourced:
+
+* AWS
+* InfluxDB
+
+Places to source credentials from:
+
+* [Vault](https://www.vaultproject.io)
+* Local environment
 
 # [Service](service/README.md)
 

credentials/README.md

@@ -1,7 +1,9 @@
 # Credentials
 
-Package to provide single interface for acquiring AWS (-only, for now)
-credentials for apps running on different platforms:
+Package to provide single interface for acquiring credentials for apps
+running on different platforms.
+
+# AWS
 
 * Use k8s service-account-based authentication with Vault when running
   on k8s. This will automatically renew Vault and AWS credetials as
@@ -57,6 +59,39 @@ result, err := svc.GetCallerIdentity(nil)
 // ...
 ```
 
+# InfluxDB
+
+A [`monitoring`](../monitoring/README.md) client that uses an internal
+InfluxDB client with credentials sourced from Vault.
+
+The client handles Vault credential expiry (to be more precise, *renewal*):
+
+1. When the client is initially created with `NewInfluxDBMonitor`, it
+   starts with a "null" internal client that responds to all requests
+   with an error (because we have no Vault credentials yet, we can't
+   fetch any InfluxDB credentials).
+
+2. When the passed Vault client authenticates (signalled via
+   `appkit/credentials/vault.Client.OnAuth`), the monitoring client
+   fetches new InfluxDB credentials and swaps out the internal
+   InfluxDB HTTP client for a new one with the updated credentials.
+
+3. Whenever the Vault client-reauthenticates in the future, step 2 is
+   repeated.
+
+Assumptions and constraints:
+
+* `https` is hardcoded, the scheme of URL passed to
+  `NewInfluxDBMonitor` is ignored.
+
+* The path of the URL is used as the database name. All query
+  attributes used by the InfluxDB monitor are respected.
+
+* Vault has a database role for InfluxDB credentials at
+  `database/creds/<name-from-path>-influxdb`,
+  (eg. `vault://influxdb.example.com/the-database` =>
+  `database/creds/the-database-influxdb`).
+
 # Terraform Module
 
 A Terraform module is provided to create the necessary resources for

service/README.md

@@ -121,6 +121,16 @@ interface/IP address using `[interface]:port` syntax.
 (via `appkit/log` monitor will be used instead of sending data to
 InfluxDB.
 
+If `INFLUXDB_URL`'s scheme is `vault` (vs `http` or `https`), then the
+client will source InfluxDB credentials from Vault. In this case,
+`INFLUXDB_URL` does not need any credentials. See the Vault+InfluxDB
+client documentation in the [`credentials`
+README](../credentials/README.md) for information about configuration
+constraints.
+
+If `INFLUXDB_URL` has no (or blank) `service-name` query parameter,
+the parameter will be set to `SERVICE_NAME`.
+
 ## Error Notifier
 
 * `AIRBRAKE_PROJECTID`