Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add task-based database and token management instructions for Dedicated (#5094) 

* add task-based instructions for dedicated db and token admin

* fixed latest shortcode, ported 1.x rp definition to serverless and dedicated
pull/5096/head
Scott Anderson 2023-08-21 10:15:09 -06:00 committed by GitHub
parent a89a869d83
commit 83b4839c82
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 409 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
content/influxdb/cloud-dedicated/admin/databases/_index.md
View File

@ -38,12 +38,20 @@ The _minimum_ retention period for and InfluxDB database is 1 hour.
The _maximum_ retention period is infinite meaning data does not expire and will
never be removed by the retention enforcement service.
{{% warn %}}
#### Retention periods cannot be updated
## Table and column limits
Retention periods cannot be changed after a database is created.
To move to a different retention period, create a new database with the retention
period you want and migrate existing data to the new database.
In {{< cloud-name >}}, table (measurement) and column limits can be
custom configured when [creating](#create-a-database) or
[updating a database](#update-a-database).
Each measurement is represented by a table.
Time, fields, and tags are each represented by a column.
**Default maximum number of tables**: 500
**Default maximum number of columns**: 250
{{% warn %}}
Setting table and column limits above the default limits may adversely affect
database performance.
{{% /warn %}}
---

46
content/influxdb/cloud-dedicated/admin/databases/create.md
View File

@ -10,8 +10,14 @@ menu:
weight: 201
list_code_example: |
```sh
influxctl database create --retention-period 30d <DATABASE_NAME>
influxctl database create \
--retention-period 30d \
--max-tables 500 \
--max-columns 250 \
<DATABASE_NAME>
```
related:
- /influxdb/cloud-dedicated/reference/cli/influxctl/database/create/
---
Use the [`influxctl database create` command](/influxdb/cloud-dedicated/reference/cli/influxctl/database/create/)
@ -20,25 +26,26 @@ to create a database in your InfluxDB Cloud Dedicated cluster.
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
2. Run the `influxctl database create` command and provide the following:
- _(Optional)_ Database [retention period](/influxdb/cloud-dedicated/admin/databases/#retention-periods)
(default is infinite)
- _Optional:_ Database [retention period](/influxdb/cloud-dedicated/admin/databases/#retention-periods)
_(default is infinite)_
- _Optional_: Database table (measurement) limit _(default is 500)_
- _Optional_: Database column limit _(default is 250)_
- Database name _(see [Database naming restrictions](#database-naming-restrictions))_
{{% code-placeholders "DATABASE_NAME|30d|500|200" %}}
```sh
influxctl database create --retention-period 30d <DATABASE_NAME>
influxctl database create \
--retention-period 30d \
--max-tables 500 \
--max-columns 250 \
DATABASE_NAME
```
{{% warn %}}
#### Retention periods cannot be updated
Retention periods cannot be changed after a database is created.
To move to a different retention period, create a new database with the retention
period you want and migrate existing data to the new database.
{{% /warn %}}
{{% /code-placeholders %}}
- [Retention period syntax](#retention-period-syntax)
- [Database naming restrictions](#database-naming-restrictions)
- [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
- [Table and column limits](#table-and-column-limits)
## Retention period syntax
@ -110,3 +117,18 @@ database_name/retention_policy_name
| db | rp | db/rp |
| telegraf | autogen | telegraf/autogen |
| webmetrics | 1w-downsampled | webmetrics/1w-downsampled |
## Table and column limits
In {{< cloud-name >}}, table (measurement) and column limits can be
configured using the `--max-tables` and `--max-columns` flags.
Each measurement is represented by a table.
Time, fields, and tags are each represented by a column.
**Default maximum number of tables**: 500
**Default maximum number of columns**: 250
{{% warn %}}
Setting table and column limits above the default limits may adversely affect
database performance.
{{% /warn %}}

12
content/influxdb/cloud-dedicated/admin/databases/delete.md
View File

@ -12,6 +12,8 @@ list_code_example: |
```sh
influxctl database delete <DATABASE_NAME>
```
related:
- /influxdb/cloud-dedicated/reference/cli/influxctl/database/delete/
---
Use the [`influxctl database delete` command](/influxdb/cloud-dedicated/reference/cli/influxctl/database/delete/)
@ -22,12 +24,14 @@ to delete a database from your InfluxDB Cloud Dedicated cluster.
- Name of the database to delete
```sh
influxctl database delete <DATABASE_NAME>
```
3. Confirm that you want to delete the database.
{{% code-placeholders "DATABASE_NAME" %}}
```sh
influxctl database delete DATABASE_NAME
```
{{% /code-placeholders %}}
{{% warn %}}
#### Deleting a database cannot be undone

37
content/influxdb/cloud-dedicated/admin/databases/list.md
View File

@ -11,6 +11,8 @@ list_code_example: |
```sh
influxctl database list
```
related:
- /influxdb/cloud-dedicated/reference/cli/influxctl/database/list/
---
Use the [`influxctl database list` command](/influxdb/cloud-dedicated/reference/cli/influxctl/database/list/)
@ -42,14 +44,45 @@ with your command to format the database list as JSON.
{{% code-tab-content %}}
```sh
# Insert table output
+---------------+------------------+------------+-----------------------+
| DATABASE NAME | RETENTION PERIOD | MAX TABLES | MAX COLUMNS PER TABLE |
+---------------+------------------+------------+-----------------------+
| mydb1 | infinite | 500 | 250 |
| mydb2 | infinite | 500 | 200 |
| mydb3 | 24h | 100 | 200 |
+---------------+------------------+------------+-----------------------+
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```json
// Insert json output
[
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"database_name": "mydb1",
"retention_period_ns": 0,
"max_tables": 500,
"max_columns_per_table": 250
},
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"database_name": "mydb2",
"retention_period_ns": 0,
"max_tables": 500,
"max_columns_per_table": 200
},
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"database_name": "mydb3",
"retention_period_ns": 86400000000000,
"max_tables": 100,
"max_columns_per_table": 200
},
]
```
{{% /code-tab-content %}}

138
content/influxdb/cloud-dedicated/admin/databases/update.md Normal file
View File

@ -0,0 +1,138 @@
---
title: Update a database
description: >
Use the [`influxctl database update` command](/influxdb/cloud-dedicated/reference/cli/influxctl/database/update/)
to update a database in your InfluxDB Cloud Dedicated cluster.
menu:
influxdb_cloud_dedicated:
parent: Manage databases
weight: 201
list_code_example: |
```sh
influxctl database update DATABASE_NAME \
--retention-period 30d \
--max-tables 500 \
--max-tables 250
```
related:
- /influxdb/cloud-dedicated/reference/cli/influxctl/database/update/
---
Use the [`influxctl database update` command](/influxdb/cloud-dedicated/reference/cli/influxctl/database/update/)
to update a database in your {{< cloud-name >}} cluster.
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
2. Run the `influxctl database update` command and provide the following:
- Database name
- _Optional_: Database [retention period](/influxdb/cloud-dedicated/admin/databases/#retention-periods)
_(default is infinite)_
- _Optional_: Database table (measurement) limit _(default is 500)_
- _Optional_: Database column limit _(default is 250)_
{{% code-placeholders "DATABASE_NAME|30d|500|200" %}}
```sh
influxctl database update DATABASE_NAME \
--retention-period 30d \
--max-tables 500 \
--max-tables 250
```
{{% /code-placeholders %}}
{{% warn %}}
#### Database names can't be updated
The `influxctl database update` command uses the database name to identify which
database to apply updates to. The database name itself can't be updated.
{{% /warn %}}
- [Retention period syntax](#retention-period-syntax)
- [Database naming restrictions](#database-naming-restrictions)
- [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
- [Table and column limits](#table-and-column-limits)
## Retention period syntax
Use the `--retention-period` flag to define a specific
[retention period](/influxdb/cloud-dedicated/admin/databases/#retention-periods)
for the database.
The retention period value is a time duration value made up of a numeric value
plus a duration unit. For example, `30d` means 30 days.
A zero duration retention period is infinite and data will not expire.
The retention period value cannot be negative or contain whitespace.
{{< flex >}}
{{% flex-content %}}
##### Valid durations units include
- **m**: minute
- **h**: hour
- **d**: day
- **w**: week
- **mo**: month
- **y**: year
{{% /flex-content %}}
{{% flex-content %}}
##### Example retention period values
- `0d`: infinite/none
- `3d`: 3 days
- `6w`: 6 weeks
- `1mo`: 1 month (30 days)
- `1y`: 1 year
- `30d30d`: 60 days
- `2.5d`: 60 hours
{{% /flex-content %}}
{{< /flex >}}
## Database naming restrictions
Database names must adhere to the following naming restrictions:
- Must contain two or more characters
- Cannot start with an underscore (`_`)
- Cannot contain whitespace characters, double quotes (`"`), or percent signs (`%`)
## InfluxQL DBRP naming convention
In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database)
and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
In InfluxDB Cloud Dedicated, databases and retention policies have been merged into
_databases_, where databases have a retention period, but retention policies
are no longer part of the data model.
Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
database and retention policy (DBRP) to be queryable with InfluxQL.
**When naming a database that you want to query with InfluxQL**, use the following
naming convention to automatically map v1 DBRP combinations to a database:
```sh
database_name/retention_policy_name
```
##### Database naming examples
| v1 Database name | v1 Retention Policy name | New database name |
| :--------------- | :----------------------- | :------------------------ |
| db | rp | db/rp |
| telegraf | autogen | telegraf/autogen |
| webmetrics | 1w-downsampled | webmetrics/1w-downsampled |
## Table and column limits
In {{< cloud-name >}}, table (measurement) and column limits can be
configured using the `--max-tables` and `--max-columns` flags.
Each measurement is represented by a table.
Time, fields, and tags are each represented by a column.
**Default maximum number of tables**: 500
**Default maximum number of columns**: 250
{{% warn %}}
Setting table and column limits above the default limits may adversely affect
database performance.
{{% /warn %}}

37
content/influxdb/cloud-dedicated/admin/tokens/create.md
View File

@ -57,9 +57,19 @@ 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).
{{% /note %}}
#### Example token creation commands
### 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-a-database)
- [Create a token with read-only access to a database](#create-a-token-with-read-only-access-to-a-database)
- [Create a token with read-only access to multiple databases](#create-a-token-with-read-only-access-to-multiple-databases)
- [Create a token with mixed permissions to multiple databases](#create-a-token-with-mixed-permissions-to-multiple-databases)
In the examples below, replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
#### Create a token with read and write access to a database
{{% code-placeholders "DATABASE_NAME" %}}
```sh
@ -70,11 +80,7 @@ influxctl token create \
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
##### 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
@ -84,7 +90,7 @@ influxctl token create \
```
{{% /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
@ -95,12 +101,7 @@ influxctl token create \
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
##### 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
@ -111,11 +112,3 @@ influxctl token create \
"Read-only on DATABASE_NAME, read/write on DATABASE2_NAME"
```
{{% /code-placeholders %}}
{{% note %}}
#### Tokens cannot be updated
Once created, token permissions cannot be updated.
If you need a token with different permissions, create a new token with the
appropriate permissions.
{{% /note %}}

10
content/influxdb/cloud-dedicated/admin/tokens/delete.md
View File

@ -32,12 +32,14 @@ all permissions associated with the token.
- Token ID to delete
```sh
influxctl token delete <TOKEN_ID>
```
4. Confirm that you want to delete the token.
{{% code-placeholders "TOKEN_ID" %}}
```sh
influxctl token delete TOKEN_ID
```
{{% /code-placeholders %}}
{{% warn %}}
#### Deleting a token is immediate and cannot be undone

34
content/influxdb/cloud-dedicated/admin/tokens/list.md
View File

@ -19,7 +19,7 @@ to list database tokens in your InfluxDB Cloud Dedicated cluster.
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
2. Run `influxctl token list` with the following:
- _(Optional)_ [Output format](#output-formats)
- _Optional_: [Output format](#output-formats)
```sh
influxctl token list --format table
@ -42,14 +42,42 @@ with your command to format the token list as JSON.
{{% code-tab-content %}}
```sh
# Insert table output
+--------------------------------------+----------------------+
| ID | DESCRIPTION |
+--------------------------------------+----------------------+
| 000x0000-000x-0000-X0x0-X0X00000x000 | read/write for mydb1 |
| 000x000X-Xx0X-0000-0x0X-000xX000xx00 | read-only for mydb2 |
| 00XXxXxx-000X-000X-x0Xx-00000xx00x00 | write-only for myb3 |
+--------------------------------------+----------------------+
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```json
// Insert json output
[
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"id": "000x0000-000x-0000-X0x0-X0X00000x000",
"description": "read/write for mydb1",
"permissions": {}
},
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"id": "000x000X-Xx0X-0000-0x0X-000xX000xx00",
"description": "read-only for mydb2",
"permissions": {}
},
{
"account_id": "0x0x0x00-0Xx0-00x0-x0X0-00x00XX0Xx0X",
"cluster_id": "X0x0xxx0-0XXx-000x-00x0-0X000Xx00000",
"id": "00XXxXxx-000X-000X-x0Xx-00000xx00x00",
"description": "write-only for myb3",
"permissions": {}
}
]
```
{{% /code-tab-content %}}

109
content/influxdb/cloud-dedicated/admin/tokens/update.md Normal file
View File

@ -0,0 +1,109 @@
---
title: Update a token
description: >
Use the [`influxctl token update` command](/influxdb/cloud-dedicated/reference/cli/influxctl/token/update/)
to update a database token's permissions in your InfluxDB Cloud Dedicated cluster.
menu:
influxdb_cloud_dedicated:
parent: Manage tokens
weight: 201
list_code_example: |
```sh
influxctl token update \
--read-database <DATABASE1_NAME> \
--read-database <DATABASE2_NAME> \
--write-database <DATABASE2_NAME> \
<TOKEN_ID>
```
alt_engine: /influxdb/cloud-serverless/admin/tokens/update-tokens/
---
Use the [`influxctl token update` command](/influxdb/cloud-dedicated/reference/cli/influxctl/token/update/)
to update a database token's permissions in your {{< cloud-name >}} cluster.
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/#download-and-install-influxctl).
2. 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.
- Token ID
{{% code-placeholders "DATABASE_NAME|TOKEN_ID" %}}
```sh
influxctl token create \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
TOKEN_ID
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`TOKEN ID`{{% /code-placeholder-key %}}: ID of the token to update
{{% note %}}
#### Existing permissions are replaced on update
When updating token permissions, the existing permissions are replaced by the
new permissions specified in the update command.
To retain existing permissions, include them in the update command.
{{% /note %}}
### Examples
- [Update a token with read and write access to a database](#update-a-token-with-read-and-write-access-to-a-database)
- [Update a token with read-only access to a database](#update-a-token-with-read-only-access-to-a-database)
- [Update a token with read-only access to multiple databases](#update-a-token-with-read-only-access-to-multiple-databases)
- [Update a token with mixed permissions to multiple databases](#update-a-token-with-mixed-permissions-to-multiple-databases)
In the examples below, Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE2_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`TOKEN ID`{{% /code-placeholder-key %}}: ID of the token to update
#### Update a token with read and write access to a database
{{% code-placeholders "DATABASE_NAME|TOKEN_ID" %}}
```sh
influxctl token update \
--read-database DATABASE_NAME \
--write-database DATABASE_NAME \
TOKEN_ID
```
{{% /code-placeholders %}}
#### Update a token with read-only access to a database
{{% code-placeholders "DATABASE_NAME|TOKEN_ID" %}}
```sh
influxctl token update \
--read-database DATABASE_NAME \
TOKEN_ID
```
{{% /code-placeholders %}}
#### Update a token with read-only access to multiple databases
{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME|TOKEN_ID" %}}
```sh
influxctl token update \
--read-database DATABASE_NAME \
--read-database DATABASE2_NAME \
TOKEN_ID
```
{{% /code-placeholders %}}
#### Update a token with mixed permissions to multiple databases
{{% code-placeholders "DATABASE_NAME|DATABASE2_NAME|TOKEN_ID" %}}
```sh
influxctl token update \
--read-database DATABASE_NAME \
--read-database DATABASE2_NAME \
--write-database DATABASE2_NAME \
TOKEN_ID
```
{{% /code-placeholders %}}

14
content/influxdb/cloud-dedicated/reference/glossary.md
View File

@ -746,11 +746,15 @@ Related entries:
### retention policy (RP)
Retention policy is an InfluxDB 1.x concept that represents the duration of time
that each data point in the retention policy persists.
The equivalent is [retention period](#retention-period) however retention periods
are not part of the InfluxDB Cloud Dedicated data model.
The retention period describes the behavior of a database.
A retention policy is part of the InfluxDB 1.x data model that describes how long
InfluxDB keeps data (duration), how many copies of the data to store when in a
in the cluster (replication factor), and the time range covered by shard groups
(shard group duration). RPs are unique per database and along with the measurement
and tag set define a series.
In {{< cloud-name >}} the equivalent is [retention period](#retention-period),
however retention periods are not part of the data model.
The retention period describes the data persistence behavior of a database.
Related entries:
[retention period](#retention-period),

14
content/influxdb/cloud-serverless/reference/glossary.md
View File

@ -753,11 +753,15 @@ Related entries:
### retention policy (RP)
Retention policy is an InfluxDB 1.x concept that represents the duration of time
that each data point in the retention policy persists.
The equivalent is [retention period](#retention-period), however retention periods
are not part of the {{% cloud-name %}} data model.
The retention period describes the behavior of a bucket.
A retention policy is part of the InfluxDB 1.x data model that describes how long
InfluxDB keeps data (duration), how many copies of the data to store when in a
in the cluster (replication factor), and the time range covered by shard groups
(shard group duration). RPs are unique per database and along with the measurement
and tag set define a series.
In {{< cloud-name >}} the equivalent is [retention period](#retention-period),
however retention periods are not part of the data model.
The retention period describes the data persistence behavior of a database.
Related entries:
[retention period](#retention-period),

4
layouts/shortcodes/latest.html
View File

@ -5,9 +5,9 @@
{{- $scratch.Set "latestVersion" (index .Site.Data.products $product).latest -}}
{{- if gt (len $majorVersion) 0 -}}
{{- if eq $majorVersion "v1" -}}
{{- $scratch.Set "latestVersion" (index (last 1 (findRE `v1\.[0-9]{1,2}` (delimit $minorVersions " "))) 0) -}}
{{- $scratch.Set "latestVersion" (index (first 1 (findRE `v1\.[0-9]{1,2}` (delimit $minorVersions " "))) 0) -}}
{{- else if eq $majorVersion "v2" -}}
{{- $scratch.Set "latestVersion" (index (last 1 (findRE `v2\.[0-9]{1,2}` (delimit $minorVersions " "))) 0) -}}
{{- $scratch.Set "latestVersion" (index (first 1 (findRE `v2\.[0-9]{1,2}` (delimit $minorVersions " "))) 0) -}}
{{- end -}}
{{- end -}}
{{- $latestVersion := $scratch.Get "latestVersion" -}}