From 3113c8c984a9749a14e56a2167ef19d5cb350f8a Mon Sep 17 00:00:00 2001 From: Matthew Irish Date: Mon, 3 Oct 2016 10:22:45 -0500 Subject: [PATCH 1/2] document the atlas listener --- website/source/docs/config/index.html.md | 38 +++++++++++++++++++++--- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/website/source/docs/config/index.html.md b/website/source/docs/config/index.html.md index 8505d64104..c0c0c3bdb5 100644 --- a/website/source/docs/config/index.html.md +++ b/website/source/docs/config/index.html.md @@ -47,7 +47,7 @@ sending a SIGHUP to the server process. These are denoted below. on the backend given in the `backend` parameter. * `listener` (required) - Configures how Vault is listening for API requests. - "tcp" is currently the only option available. A full reference for the + "tcp" and "atlas" are valid values. A full reference for the inner syntax is below. * `cache_size` (optional) - If set, the size of the read cache used @@ -91,9 +91,11 @@ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) ## Listener Reference -For the `listener` section, the only supported listener currently -is "tcp". Regardless of future plans, this is the recommended listener, -since it allows for HA mode. +For the `listener` section, the only required listener is "tcp". +Regardless of future plans, this is the recommended listener, +as it allows for HA mode. If you wish to use the Vault +Enterprise interface in HashiCorp Atlas, you may add an "atlas" listener block +in addition to the "tcp" one. The supported options are: @@ -125,6 +127,34 @@ The supported options are: are generally considered less secure; avoid using these if possible. +### Connecting to Vault Enterprise in HashiCorp Atlas + +Adding an "atlas" block will initiate a long-running connection to the +[SCADA](https://scada.hashicorp.com) service. The SCADA connection allows the +Vault Enterprise interface to securely communicate with and operate on your +Vault cluster. + +The "atlas" `listener` supports these options: + + * `endpoint` (optional) - The endpoint address used for Vault Enterprise interface + integration. Defaults to the public Vault Enterprise endpoints on Atlas. + + * `infrastructure` (required) - Used to provide the Atlas infrastructure name and + the SCADA connection. The format of this is `username/environment`. + + * `node_id` (required) - The identifier for an individual node—used in + the Vault Enterprise dashboard. + + * `token` (required) - A token from Atlas used to authenticate SCADA session. Generate + one in the [Atlas](https://atlas.hashicorp.com/settings/tokens). + +Additionally, the global `cluster_name` will be used to identify your cluster +inside of your infrastructure in the Vault Enterprise interface. This allows +the connection of multiple clusters to a single `infrastructure`. + +For more on Vault Enterprise, see the [help documentation](https://atlas.hashicorptest.com/help/vault/features). + + ## Telemetry Reference For the `telemetry` section, there is no resource name. All configuration From 61c88389ed524d84ab8955faede2954b6c02ba2c Mon Sep 17 00:00:00 2001 From: Matthew Irish Date: Mon, 3 Oct 2016 13:45:31 -0500 Subject: [PATCH 2/2] add documentation for cluster_name and link atlas listener docs --- website/source/docs/config/index.html.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/website/source/docs/config/index.html.md b/website/source/docs/config/index.html.md index c0c0c3bdb5..fa1b71d72c 100644 --- a/website/source/docs/config/index.html.md +++ b/website/source/docs/config/index.html.md @@ -46,6 +46,10 @@ sending a SIGHUP to the server process. These are denoted below. configuration options as documented below. If not set, HA will be attempted on the backend given in the `backend` parameter. +* `cluster_name` (optional) - An identifier for your Vault cluster. If omitted, + Vault will generate a value for `cluster_name`. If connecting to Vault + Enterprise, this value will be used in the interface. + * `listener` (required) - Configures how Vault is listening for API requests. "tcp" and "atlas" are valid values. A full reference for the inner syntax is below. @@ -94,7 +98,7 @@ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) For the `listener` section, the only required listener is "tcp". Regardless of future plans, this is the recommended listener, as it allows for HA mode. If you wish to use the Vault -Enterprise interface in HashiCorp Atlas, you may add an "atlas" listener block +Enterprise interface in HashiCorp Atlas, you may add an ["atlas" listener block](#connecting-to-vault-enterprise-in-hashicorp-atlas) in addition to the "tcp" one. The supported options are: @@ -148,9 +152,13 @@ The "atlas" `listener` supports these options: * `token` (required) - A token from Atlas used to authenticate SCADA session. Generate one in the [Atlas](https://atlas.hashicorp.com/settings/tokens). -Additionally, the global `cluster_name` will be used to identify your cluster -inside of your infrastructure in the Vault Enterprise interface. This allows -the connection of multiple clusters to a single `infrastructure`. +Additionally, the [`cluster_name`](#cluster_name) config option will be used to +identify your cluster members inside the infrastructure in the Vault Enterprise +interface. It is important for operators to use the same value for +`cluster_name` across cluster members because Vault overwrites this value +internally on instance instantiation. + +This allows the connection of multiple clusters to a single `infrastructure`. For more on Vault Enterprise, see the [help documentation](https://atlas.hashicorptest.com/help/vault/features).