diff --git a/content/v2.0/security/secrets/_index.md b/content/v2.0/security/secrets/_index.md new file mode 100644 index 000000000..dba43f9a8 --- /dev/null +++ b/content/v2.0/security/secrets/_index.md @@ -0,0 +1,36 @@ +--- +title: Store and use secrets +description: +v2.0/tags: [secrets, security] +menu: + v2_0: + parent: Security & authorization +weight: 102 +--- + +There are two options for storing secrets with InfluxDB: + +- By default, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, [BoltDB](https://github.com/boltdb/bolt). +- You can also set up Vault to store secrets. For details, see [Store secrets in Vault](/v2.0/security/secrets/use-vault). + +## Use secrets in a query +Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function +to populate sensitive data in queries with secrets from your secret store. + +```js +import "influxdata/influxdb/secrets" +import "sql" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` + +## Add, list, and delete secrets + +See [Manage secrets](/v2.0/security/secrets/manage-secrets). diff --git a/content/v2.0/security/secrets/manage-secrets.md b/content/v2.0/security/secrets/manage-secrets.md new file mode 100644 index 000000000..9b4054267 --- /dev/null +++ b/content/v2.0/security/secrets/manage-secrets.md @@ -0,0 +1,69 @@ +--- +title: Manage secrets +description: Manage secrets in InfluxDB with the InfluxDB API. +v2.0/tags: [secrets, security] +menu: + v2_0: + parent: Store and use secrets +weight: 201 +--- + + +Manage secrets using the InfluxDB `/org/{orgID}/secrets` API endpoint. +All secrets belong to an organization and are stored in your [secret-store](/v2.0/security/secrets/). +Include your [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id) +and [authentication token](/v2.0/security/tokens/view-tokens/) with each request. + +### Add a secret +Use the `PATCH` request method to add a new secret to your organization. +Pass the secret key-value pair in the request body. + +```sh +curl -XPATCH http://localhost:9999/api/v2/orgs//secrets \ + -H 'authorization: Token YOURAUTHTOKEN' \ + -H 'Content-type: application/json' \ + --data '{ + "": "" +}' +``` + +### View secret keys +Use the `GET` request method to view your organization's secrets keys. + +```sh +curl -XGET http://localhost:9999/api/v2/orgs//secrets \ + -H 'authorization: Token YOURAUTHTOKEN' +``` + +### Delete a secret +Use the `POST` request method and the `orgs/{orgID}/secrets/delete` API endpoint +to delete one or more secrets. +Include an array of secret keys to delete in the requests body in the following format. + +```bash +curl -XGET http://localhost:9999/api/v2/orgs//secrets/delete \ + --H 'authorization: Token YOURAUTHTOKEN' + --data '{ + "secrets": [ + "" + ] +}' +``` + +## Use secrets in a query +Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function +to populate sensitive data in queries with secrets from your secret store. + +```js +import "influxdata/influxdb/secrets" +import "sql" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` diff --git a/content/v2.0/security/secrets/use-vault.md b/content/v2.0/security/secrets/use-vault.md new file mode 100644 index 000000000..6302787f0 --- /dev/null +++ b/content/v2.0/security/secrets/use-vault.md @@ -0,0 +1,64 @@ +--- +title: Store secrets in Vault +description: Manage secrets in InfluxDB using the InfluxDB UI or the influx CLI. +v2.0/tags: [secrets, security] +menu: + v2_0: + parent: Store and use secrets +weight: 201 +--- + +[Vault](https://www.vaultproject.io/) secures, stores, and tightly controls access +to tokens, passwords, certificates, and other sensitive secrets. +Store sensitive secrets in Vault using the InfluxDB built-in Vault integration. + +## Start a Vault server + +Start a Vault server and ensure InfluxDB has network 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) +- [Start a Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server) +- [Deploy Vault](https://learn.hashicorp.com/vault/getting-started/deploy) + +{{% note %}} +InfluxDB supports the [Vault KV Secrets Engine Version 2 API](https://www.vaultproject.io/api/secret/kv/kv-v2.html) only. +When you create a secrets engine, enable the `kv-v2` version by running: + +```js +vault secrets enable kv-v2 +``` +{{% /note %}} + +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 +``` diff --git a/content/v2.0/security/use-vault.md b/content/v2.0/security/use-vault.md deleted file mode 100644 index 5fc8bc3bd..000000000 --- a/content/v2.0/security/use-vault.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Store 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. -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, -[BoltDB](https://github.com/boltdb/bolt). -{{% /note %}} - -## Start a Vault server -Start a Vault server and ensure InfluxDB has network 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) -- [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](/v2.0/organizations/view-orgs/#view-your-organization-id) -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 YOURAUTHTOKEN' - -# 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 YOURAUTHTOKEN' \ - --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 YOURAUTHTOKEN' - -# should return -# { -# "links": { -# "org": "/api/v2/orgs/031c8cbefe101000", -# "secrets": "/api/v2/orgs/031c8cbefe101000/secrets" -# }, -# "secrets": [ -# "foo", -# "hello" -# ] -# } -``` - -## Vault secrets storage -For each organization, InfluxDB creates a [secrets engine](https://learn.hashicorp.com/vault/getting-started/secrets-engines) -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 -```