From 4314d1e68efa808db9981ac1380c104125353576 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 17 Apr 2019 11:00:40 -0600 Subject: [PATCH 1/6] initial draft of vault secret storage doc --- content/v2.0/security/use-vault.md | 130 +++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 content/v2.0/security/use-vault.md diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md new file mode 100644 index 000000000..dda5f8ac2 --- /dev/null +++ b/content/v2.0/security/use-vault.md @@ -0,0 +1,130 @@ +--- +title: Store InfluxDB secrets in Vault +description: Manage authentication tokens in InfluxDB using the InfluxDB UI or the influx CLI. +v2.0/tags: [tokens, security] +menu: + v2_0: + parent: Security & authorization +weight: 102 +--- + +[Vault](https://www.vaultproject.io/) secures, stores, and tightly controls access +to tokens, passwords, certificates, and other sensitive secrets. +InfluxDB provides a built-in Vault integration that lets you store sensitive +InfluxDB secrets in Vault. + +{{% note %}} +When not using Vault, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, +[BoltDB](https://github.com/boltdb/bolt). +{{% /note %}} + +## Start a Vault server +Start a Vault server and ensure InfluxDB has network access to it. +The following links provide information about running Vault in both development and production: + +- [Install Vault](https://learn.hashicorp.com/vault/getting-started/install) +- [Start a Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server) +- [Deploy Vault](https://learn.hashicorp.com/vault/getting-started/deploy) + +For this example, install Vault on your local machine and start a Vault dev server. + +```sh +vault server -dev +``` + +## Define Vault environment variables +Use [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables) +to provide connection credentials and other important Vault-related information to InfluxDB. + +#### Required environment variables +- `VAULT_ADDR`: The API address of your Vault server _(provided in the Vault server output)_. +- `VAULT_TOKEN`: The [Vault token](https://learn.hashicorp.com/vault/getting-started/authentication) + required to access your Vault server. + +_Your Vault server configuration may require other environment variables._ + +```sh +export VAULT_ADDR='http://127.0.0.1:8200' VAULT_TOKEN='s.0X0XxXXx0xXxXXxxxXxXxX0x' +``` + +## Start InfluxDB +Start the [`influxd` service](/v2.0/reference/cli/influxd/) with the `--secret-store` +option set to `vault`. + +```bash +influxd --secret-store vault +``` + +## Test Vault storage +With Vault and InfluxDB servers running, use the InfluxDB API to test Vault: + +{{% note %}} +Replace `` with your [organization ID](#) and `` +with your [InfluxDB authentication token](/v2.0/security/tokens/). +{{% /note %}} + +##### Retrieve an organization's secrets +```sh +curl --request GET \ + --url http://localhost:9999/api/v2/orgs//secrets \ + --header 'authorization: Token ' + +# should return +# { +# "links": { +# "org": "/api/v2/orgs/031c8cbefe101000", +# "secrets": "/api/v2/orgs/031c8cbefe101000/secrets" +# }, +# "secrets": [] +# } +``` + +##### Add secrets to an organization +```sh +curl --request PATCH \ + --url http://localhost:9999/api/v2/orgs//secrets \ + --header 'authorization: Token ' \ + --header 'content-type: application/json' \ + --data '{ + "foo": "bar", + "hello": "world" +}' + +# should return 204 no content +``` + +##### Retrieve the added secrets +```bash +curl --request GET \ + --url http://localhost:9999/api/v2/orgs//secrets \ + --header 'authorization: Token ' + +# should return +# { +# "links": { +# "org": "/api/v2/orgs/031c8cbefe101000", +# "secrets": "/api/v2/orgs/031c8cbefe101000/secrets" +# }, +# "secrets": [ +# "foo", +# "hello" +# ] +# } +``` + +## Vault secrets storage +InfluxDB creates a [secrets engine](https://learn.hashicorp.com/vault/getting-started/secrets-engines) +for each organization using the following pattern: + +``` +/secret/data/ +``` + +Secrets are stored in Vault as key value pairs in their respective secrets engines. + +``` +/secret/data/031c8cbefe101000 -> + this_key: foo + that_key: bar + a_secret: key +``` From 9b0a7bb3637d2791ef1a9b11de1a5f27cdb86d40 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 17 Apr 2019 11:10:11 -0600 Subject: [PATCH 2/6] added instructions for viewing your org id, resolves #165 --- content/v2.0/organizations/view-orgs.md | 23 +++++++++++++++++++++++ content/v2.0/security/use-vault.md | 4 ++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/content/v2.0/organizations/view-orgs.md b/content/v2.0/organizations/view-orgs.md index f6f9ec896..96fbecdad 100644 --- a/content/v2.0/organizations/view-orgs.md +++ b/content/v2.0/organizations/view-orgs.md @@ -33,3 +33,26 @@ influx org find Filtering options such as filtering by name or ID are available. See the [`influx org find` documentation](/v2.0/reference/cli/influx/org/find) for information about other available flags. + +## View your organization ID +Use the InfluxDB UI or `influx` CLI to see your organization ID. + +### Organization ID in the UI +Your organization ID is in the InfluxDB UI URL after logging in. + +```sh +# Pattern +http://localhost:9999/orgs/ + +# Example +http://localhost:9999/orgs/03a2bbf46249a000 +``` + +### Organization ID in the CLI +View your organization ID in the output [`influx org find`](#view-organizations-using-the-influx-cli). + +```sh +ID Name +03a2bbf46249a000 org-1 +03ace3a859669000 org-2 +``` diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md index dda5f8ac2..92cbb8956 100644 --- a/content/v2.0/security/use-vault.md +++ b/content/v2.0/security/use-vault.md @@ -59,8 +59,8 @@ influxd --secret-store vault With Vault and InfluxDB servers running, use the InfluxDB API to test Vault: {{% note %}} -Replace `` with your [organization ID](#) and `` -with your [InfluxDB authentication token](/v2.0/security/tokens/). +Replace `` with your [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id) +and `` with your [InfluxDB authentication token](/v2.0/security/tokens/). {{% /note %}} ##### Retrieve an organization's secrets From db4bb9aae272915c2b671756e226b279ee941125 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 17 Apr 2019 11:11:41 -0600 Subject: [PATCH 3/6] minor update to vault secrets doc, resolves #157 --- content/v2.0/security/use-vault.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md index 92cbb8956..0bace2ef3 100644 --- a/content/v2.0/security/use-vault.md +++ b/content/v2.0/security/use-vault.md @@ -10,8 +10,7 @@ weight: 102 [Vault](https://www.vaultproject.io/) secures, stores, and tightly controls access to tokens, passwords, certificates, and other sensitive secrets. -InfluxDB provides a built-in Vault integration that lets you store sensitive -InfluxDB secrets in Vault. +InfluxDB provides a built-in Vault integration that lets you store sensitive secrets in Vault. {{% note %}} When not using Vault, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, From 0f3e41bafc004125b4d069282e00f8339180c3ba Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 18 Apr 2019 09:05:56 -0600 Subject: [PATCH 4/6] updated auth token placeholders in api examples to be consistent with others --- content/v2.0/security/use-vault.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md index 0bace2ef3..10ef0bdea 100644 --- a/content/v2.0/security/use-vault.md +++ b/content/v2.0/security/use-vault.md @@ -59,14 +59,14 @@ With Vault and InfluxDB servers running, use the InfluxDB API to test Vault: {{% note %}} Replace `` with your [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id) -and `` with your [InfluxDB authentication token](/v2.0/security/tokens/). +and `YOURAUTHTOKEN` with your [InfluxDB authentication token](/v2.0/security/tokens/). {{% /note %}} ##### Retrieve an organization's secrets ```sh curl --request GET \ --url http://localhost:9999/api/v2/orgs//secrets \ - --header 'authorization: Token ' + --header 'authorization: Token YOURAUTHTOKEN' # should return # { @@ -82,7 +82,7 @@ curl --request GET \ ```sh curl --request PATCH \ --url http://localhost:9999/api/v2/orgs//secrets \ - --header 'authorization: Token ' \ + --header 'authorization: Token YOURAUTHTOKEN' \ --header 'content-type: application/json' \ --data '{ "foo": "bar", @@ -96,7 +96,7 @@ curl --request PATCH \ ```bash curl --request GET \ --url http://localhost:9999/api/v2/orgs//secrets \ - --header 'authorization: Token ' + --header 'authorization: Token YOURAUTHTOKEN' # should return # { From b3ae9a6fc52db9f0d64165ffe6a423356904a003 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 18 Apr 2019 11:55:45 -0600 Subject: [PATCH 5/6] updated vault doc and view org doc to address PR feedback --- content/v2.0/organizations/view-orgs.md | 23 +++++++++++------------ content/v2.0/security/use-vault.md | 6 +++--- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/content/v2.0/organizations/view-orgs.md b/content/v2.0/organizations/view-orgs.md index 96fbecdad..c253d8ee7 100644 --- a/content/v2.0/organizations/view-orgs.md +++ b/content/v2.0/organizations/view-orgs.md @@ -35,24 +35,23 @@ See the [`influx org find` documentation](/v2.0/reference/cli/influx/org/find) for information about other available flags. ## View your organization ID -Use the InfluxDB UI or `influx` CLI to see your organization ID. +Use the InfluxDB UI or `influx` CLI to view your organization ID. ### Organization ID in the UI -Your organization ID is in the InfluxDB UI URL after logging in. +After logging in to the InfluxDB UI, your organization ID appears in the URL. -```sh -# Pattern -http://localhost:9999/orgs/ +
+http://localhost:9999/orgs/03a2bbf46249a000/...
+
-# Example -http://localhost:9999/orgs/03a2bbf46249a000 -``` ### Organization ID in the CLI -View your organization ID in the output [`influx org find`](#view-organizations-using-the-influx-cli). +Use [`influx org find`](#view-organizations-using-the-influx-cli) to view your organization ID. ```sh -ID Name -03a2bbf46249a000 org-1 -03ace3a859669000 org-2 +> influx org find + +ID Name +03a2bbf46249a000 org-1 +03ace3a859669000 org-2 ``` diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md index 10ef0bdea..c39ab8adb 100644 --- a/content/v2.0/security/use-vault.md +++ b/content/v2.0/security/use-vault.md @@ -10,7 +10,7 @@ weight: 102 [Vault](https://www.vaultproject.io/) secures, stores, and tightly controls access to tokens, passwords, certificates, and other sensitive secrets. -InfluxDB provides a built-in Vault integration that lets you store sensitive secrets in Vault. +Store sensitive secrets in Vault using the InfluxDB built-in Vault integration. {{% note %}} When not using Vault, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, @@ -112,8 +112,8 @@ curl --request GET \ ``` ## Vault secrets storage -InfluxDB creates a [secrets engine](https://learn.hashicorp.com/vault/getting-started/secrets-engines) -for each organization using the following pattern: +For each organization, InfluxDB creates a [secrets engine](https://learn.hashicorp.com/vault/getting-started/secrets-engines) +using the following pattern: ``` /secret/data/ From 157d921b6d888e75bab6982ae19ed9e15d28069b Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 18 Apr 2019 12:01:33 -0600 Subject: [PATCH 6/6] added clarification about vault network access --- content/v2.0/security/use-vault.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md index c39ab8adb..fd7339857 100644 --- a/content/v2.0/security/use-vault.md +++ b/content/v2.0/security/use-vault.md @@ -18,7 +18,7 @@ When not using Vault, secrets are Base64-encoded and stored in the InfluxDB embe {{% /note %}} ## Start a Vault server -Start a Vault server and ensure InfluxDB has network access to it. +Start a Vault server and ensure InfluxDB has network (HTTP) access to the server. The following links provide information about running Vault in both development and production: - [Install Vault](https://learn.hashicorp.com/vault/getting-started/install)