From e16405282dae65d354186d32caf4c0b7566eaae6 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 May 2024 14:38:35 -0500 Subject: [PATCH] chore(v3): increase suggested wait for token activation - part of https://github.com/influxdata/DAR/issues/425 - Tokens currently can take minutes to sync - Add Notable behaviors to guides and references --- .../cloud-dedicated/management/openapi.yml | 16 +++++- .../admin/tokens/database/create.md | 32 +++++++----- .../reference/cli/influxctl/token/create.md | 20 +++++++- .../clustered/admin/tokens/database/create.md | 51 ++++++++++++++----- .../reference/cli/influxctl/token/create.md | 10 +++- 5 files changed, 98 insertions(+), 31 deletions(-) diff --git a/api-docs/cloud-dedicated/management/openapi.yml b/api-docs/cloud-dedicated/management/openapi.yml index d7c1ae645..4e05a682c 100644 --- a/api-docs/cloud-dedicated/management/openapi.yml +++ b/api-docs/cloud-dedicated/management/openapi.yml @@ -1006,9 +1006,21 @@ paths: description: | Create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) for a cluster. - The access token returned on the `accessToken` property in the response can be used to authenticate query and write requests to the cluster. + The token returned on the `accessToken` property in the response can be used to authenticate query and write requests to the cluster. + + ### Notable behaviors + + - InfluxDB might take some time--from a few seconds to a few minutes-- to activate and synchronize new tokens. If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try your request again. + + - Token strings are viewable _only_ on token creation and aren't stored by InfluxDB; you can't recover a lost token. + + #### Store secure tokens in a secret store + + We recommend storing database tokens in a **secure secret store**. + For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os). + + If you lose a token, [delete the token from InfluxDB](/influxdb/cloud-dedicated/admin/tokens/database/delete/) and create a new one. - The access token is never stored by InfluxDB and is only returned once when the token is created. If the access token is lost, a new token must be created. parameters: - name: accountId in: path diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md index 5c7df26be..d096e2524 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md @@ -61,7 +61,7 @@ or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) to create Use the [`influxctl token create` command](/influxdb/cloud-dedicated/reference/cli/influxctl/token/create/) -to create a token that grants access to databases in your InfluxDB Cloud Dedicated cluster. +to create a token that grants access to databases in your {{% product-name omit="Clustered" %}} cluster. 1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl), and then [configure an `influxctl` connection profile](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) for your cluster. 2. In your terminal, run the `influxctl token create` command and provide the following: @@ -91,7 +91,7 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) -The command returns the token string. +The output is the token ID and the token string. **This is the only time the token string is available in plain text.** @@ -157,24 +157,30 @@ Replace the following in your request: - {{% code-placeholder-key %}}`MANAGEMENT TOKEN`{{% /code-placeholder-key %}}: a [management token](/influxdb/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: a {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) that the token will have read or write permission to +The response body contains the token ID and the token string. +**This is the only time the token string is available in plain text.** {{% /tab-content %}} {{< /tabs-wrapper >}} -InfluxDB might take some time to synchronize new tokens. -If a new token doesn't immediately work for querying or writing, wait a few seconds and try again. +## Notable behaviors + +- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens. +If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again. +- Token strings are viewable _only_ on token creation. {{% note %}} + #### Store secure tokens in a secret store -Token strings are returned _only_ on token creation and aren't stored by InfluxDB. +Token strings are viewable _only_ on token creation and aren't stored by InfluxDB. We recommend storing database tokens in a **secure secret store**. For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os). -If you lose a token, [delete the token](/influxdb/cloud-dedicated/admin/tokens/database/delete/) and create a new one. +If you lose a token, [delete the token from InfluxDB](/influxdb/cloud-dedicated/admin/tokens/database/delete/) and create a new one. {{% /note %}} -### Output format +## Output format The `influxctl token create` command supports the `--format json` option. By default, the command outputs the token string. @@ -183,7 +189,7 @@ with your command to format the output as JSON. The Management API outputs JSON format in the response body. -### Examples +## Examples - [Create a token with read and write access to a database](#create-a-token-with-read-and-write-access-to-a-database) - [Create a token with read and write access to all databases](#create-a-token-with-read-and-write-access-to-all-databases) @@ -199,7 +205,7 @@ In the examples below, replace the following: - {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the ID of the {{% product-name %}} [cluster](/influxdb/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database token for - {{% code-placeholder-key %}}`MANAGEMENT TOKEN`{{% /code-placeholder-key %}}: a [management token](/influxdb/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster -#### Create a token with read and write access to a database +### Create a token with read and write access to a database {{% code-placeholders "DATABASE_NAME|ACCOUNT_ID|CLUSTER_ID|MANAGEMENT_TOKEN" %}} {{% code-tabs-wrapper %}} @@ -244,7 +250,7 @@ curl \ {{< /code-tabs-wrapper >}} {{% /code-placeholders %}} -#### Create a token with read and write access to all databases +### Create a token with read and write access to all databases {{% code-tabs-wrapper %}} {{% code-tabs %}} @@ -288,7 +294,7 @@ curl \ {{% /code-tab-content %}} {{% /code-tabs-wrapper %}} -#### Create a token with read-only access to a database +### Create a token with read-only access to a database {{% code-tabs-wrapper %}} {{% code-tabs %}} @@ -332,7 +338,7 @@ curl \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -#### Create a token with read-only access to multiple databases +### Create a token with read-only access to multiple databases {{% code-tabs-wrapper %}} {{% code-tabs %}} @@ -379,7 +385,7 @@ curl \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -#### Create a token with mixed permissions to multiple databases +### Create a token with mixed permissions to multiple databases {{% code-tabs-wrapper %}} {{% code-tabs %}} diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/token/create.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/token/create.md index cb7075b48..52fc5ef14 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/token/create.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/token/create.md @@ -21,13 +21,22 @@ The `--format` flag lets you print the output in other formats. The `json` format is available for programmatic parsing by other tooling. Default: `table`. +## Notable behaviors + +- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens. +If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again. +- Token strings are viewable _only_ on token creation. + {{% note %}} + #### Store secure tokens in a secret store -Token strings are returned _only_ on token creation. +Token strings are viewable _only_ on token creation and aren't stored by InfluxDB. We recommend storing database tokens in a **secure secret store**. + {{% /note %}} + ## Usage ```sh @@ -56,6 +65,15 @@ influxctl token create \ _Also see [`influxctl` global flags](/influxdb/cloud-dedicated/reference/cli/influxctl/#global-flags)._ {{% /caption %}} +{{% note %}} + +#### Using a new token + +InfluxDB might take some time to synchronize new tokens. +If a new database token doesn't immediately work for querying or writing, wait a few seconds and try again. + +{{% /note %}} + ## Examples - [Create a token with read and write access to a database](#create-a-token-with-read-and-write-access-to-a-database) diff --git a/content/influxdb/clustered/admin/tokens/database/create.md b/content/influxdb/clustered/admin/tokens/database/create.md index f0309aab3..fa97d01e7 100644 --- a/content/influxdb/clustered/admin/tokens/database/create.md +++ b/content/influxdb/clustered/admin/tokens/database/create.md @@ -24,11 +24,10 @@ alt_links: --- Use the [`influxctl token create` command](/influxdb/clustered/reference/cli/influxctl/token/create/) -to create a token that grants access to databases in your InfluxDB cluster. +tto create a token that grants access to databases in your {{% product-name omit="Clustered" %}} cluster. 1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/#download-and-install-influxctl). -2. Run the `influxctl token create` command and provide the following: - +2. In your terminal, run the `influxctl token create` command and provide the following: - Token permissions (read and write) - `--read-database`: Grants read permissions to the specified database. Repeatable. - `--write-database`: Grants write permissions to the specified database. Repeatable. @@ -40,33 +39,49 @@ to create a token that grants access to databases in your InfluxDB cluster. - Token description {{% code-placeholders "DATABASE_NAME|TOKEN_DESCRIPTION" %}} + ```sh influxctl token create \ --read-database DATABASE_NAME \ --write-database DATABASE_NAME \ "Read/write token for DATABASE_NAME" ``` + {{% /code-placeholders %}} Replace the following: -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/clustered/admin/databases/) -The command returns the token ID and the token string. +The output is the token ID and the token string. **This is the only time the token string is available in plain text.** -InfluxDB might take some time to synchronize new tokens. -If a new token doesn't immediately work for querying or writing, wait a few seconds and try again. +## Notable behaviors + +- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens. +If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again. +- Token strings are viewable _only_ on token creation. {{% note %}} + #### Store secure tokens in a secret store -Token strings are returned _only_ on token creation. +Token strings are viewable _only_ on token creation and aren't stored by InfluxDB. We recommend storing database tokens in a **secure secret store**. For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os). + +If you lose a token, [delete the token from InfluxDB](/influxdb/clustered/admin/tokens/database/delete/) and create a new one. + {{% /note %}} -#### Examples +## Output format + +The `influxctl token create` command supports the `--format json` option. +By default, the command outputs the token string. +For token details and easier programmatic access to the command output, include `--format json` +with your command to format the output as JSON. + +## Examples - [Create a token with read and write access to a database](#create-a-token-with-read-and-write-access-to-a-database) - [Create a token with read and write access to all databases](#create-a-token-with-read-and-write-access-to-all-databases) @@ -79,18 +94,20 @@ In the examples below, replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} database - {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{< product-name >}} database -#### Create a token with read and write access to a database +### Create a token with read and write access to a database {{% code-placeholders "DATABASE_NAME" %}} + ```sh influxctl token create \ --read-database DATABASE_NAME \ --write-database DATABASE_NAME \ "Read/write token for DATABASE_NAME" ``` + {{% /code-placeholders %}} -#### Create a token with read and write access to all databases +### Create a token with read and write access to all databases ```sh influxctl token create \ @@ -99,30 +116,35 @@ influxctl token create \ "Read/write token for all databases" ``` -#### Create a token with read-only access to a database +### Create a token with read-only access to a database {{% code-placeholders "DATABASE_NAME" %}} + ```sh influxctl token create \ --read-database DATABASE_NAME \ "Read-only token for DATABASE_NAME" ``` + {{% /code-placeholders %}} -#### Create a token with read-only access to multiple databases +### Create a token with read-only access to multiple databases {{% code-placeholders "DATABASE_NAME|DATABASE2_NAME" %}} + ```sh influxctl token create \ --read-database DATABASE_NAME \ --read-database DATABASE2_NAME \ "Read-only token for DATABASE_NAME and DATABASE2_NAME" ``` + {{% /code-placeholders %}} -#### Create a token with mixed permissions to multiple databases +### Create a token with mixed permissions to multiple databases {{% code-placeholders "DATABASE_NAME|DATABASE2_NAME" %}} + ```sh influxctl token create \ --read-database DATABASE_NAME \ @@ -130,4 +152,5 @@ influxctl token create \ --write-database DATABASE2_NAME \ "Read-only on DATABASE_NAME, read/write on DATABASE2_NAME" ``` + {{% /code-placeholders %}} diff --git a/content/influxdb/clustered/reference/cli/influxctl/token/create.md b/content/influxdb/clustered/reference/cli/influxctl/token/create.md index f4739a756..09119ab54 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/token/create.md +++ b/content/influxdb/clustered/reference/cli/influxctl/token/create.md @@ -21,11 +21,19 @@ The `--format` flag lets you print the output in other formats. The `json` format is available for programmatic parsing by other tooling. Default: `table`. +## Notable behaviors + +- InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens. +If a new database token doesn't immediately work (you receive a `401 Unauthorized` error) for querying or writing, wait and then try again. +- Token strings are viewable _only_ on token creation. + {{% note %}} + #### Store secure tokens in a secret store -Token strings are returned _only_ on token creation. +Token strings are viewable _only_ on token creation and aren't stored by InfluxDB. We recommend storing database tokens in a **secure secret store**. + {{% /note %}} ## Usage