From 8471eaa0e7dabb618ad51ce24bd01ed9b2169767 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 29 Jan 2026 13:51:54 -0600 Subject: [PATCH] docs(influxdb3): Add Docker Compose and CI/CD examples for preconfigured tokens --- .../admin/tokens/resource/preconfigured.md | 121 ++++++++++++++++- .../tokens/admin/preconfigured.md | 126 +++++++++++++++++- content/shared/influxdb3-get-started/setup.md | 7 +- 3 files changed, 250 insertions(+), 4 deletions(-) diff --git a/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md b/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md index a5e2e140b1..62cc8ca29f 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md @@ -10,7 +10,6 @@ menu: name: Use preconfigured resource tokens weight: 202 related: - - /influxdb3/enterprise/admin/tokens/admin/preconfigured/ - /influxdb3/enterprise/reference/config-options/#permission-tokens-file, Configuration options > permission-tokens-file - /influxdb3/enterprise/reference/cli/influxdb3/create/token/permission/ --- @@ -22,6 +21,10 @@ specified in the provided permission (resource) tokens file. - [Generate an offline permissions (resource) tokens file](#generate-an-offline-permissions-resource-tokens-file) - [Offline permission tokens file schema](#offline-permission-tokens-file-schema) - [Start InfluxDB with the preconfigured permission tokens](#start-influxdb-with-the-preconfigured-permission-tokens) +- [Use Docker Compose with preconfigured resource tokens](#use-docker-compose-with-preconfigured-resource-tokens) + - [Create a permission tokens file](#create-a-permission-tokens-file) + - [Configure Docker Compose with secrets](#configure-docker-compose-with-secrets) + - [CI/CD setup](#cicd-setup) ## Generate an offline permissions (resource) tokens file @@ -170,3 +173,119 @@ influxdb3 serve \ When the server starts, you can use the preconfigured permission (resource) tokens to write data to and query data from with your {{% product-name %}} instance or cluster. + +## Use Docker Compose with preconfigured resource tokens + +For containerized deployments, you can use Docker Compose with Docker secrets to securely manage your preconfigured resource tokens. + +### Create a permission tokens file + +Create a JSON file with your resource tokens using the +[offline permission tokens file schema](#offline-permission-tokens-file-schema): + +```json +{ + "create_databases": [ + "sensors", + "metrics" + ], + "tokens": [ + { + "token": "apiv3_your_token_here", + "name": "app-writer", + "permissions": [ + "db:sensors,metrics:read,write" + ] + }, + { + "token": "apiv3_another_token_here", + "name": "dashboard-reader", + "permissions": [ + "db:sensors,metrics:read" + ] + } + ] +} +``` + +For security, restrict file permissions: + +```bash +chmod 600 path/to/permission-tokens.json +``` + +### Configure Docker Compose with secrets + +Use Docker secrets to securely provide the permission tokens file to your container: + +```yaml +# compose.yaml +services: + influxdb3-enterprise: + image: influxdb:3-enterprise + ports: + - 8181:8181 + command: + - influxdb3 + - serve + - --node-id=node0 + - --cluster-id=cluster0 + - --object-store=file + - --data-dir=/var/lib/influxdb3/data + - --permission-tokens-file=/run/secrets/permission-tokens + environment: + - INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com + secrets: + - permission-tokens + volumes: + - type: bind + source: ~/.influxdb3/data + target: /var/lib/influxdb3/data + +secrets: + permission-tokens: + file: path/to/permission-tokens.json +``` + +Start the service: + + + +```bash +docker compose up -d +``` + +> [!Important] +> #### Docker secrets security benefits +> +> Docker secrets provide better security than bind mounts for sensitive data: +> - Secrets are stored encrypted in memory +> - Not visible in `docker inspect` output +> - Not exposed in environment variables or logs +> - Follow Docker and Kubernetes security best practices + +### CI/CD setup + +For CI/CD pipelines and automated environments, create the permission tokens file from +environment variables: + + + +```bash +# Create permission tokens file from CI/CD environment variables +cat > permission-tokens.json << EOF +{ + "create_databases": ["$INFLUXDB3_DATABASE"], + "tokens": [ + { + "token": "$INFLUXDB3_RESOURCE_TOKEN", + "name": "app-token", + "permissions": ["db:$INFLUXDB3_DATABASE:read,write"] + } + ] +} +EOF +chmod 600 permission-tokens.json +``` + +Then use the file in your Docker Compose configuration as shown above. diff --git a/content/shared/influxdb3-admin/tokens/admin/preconfigured.md b/content/shared/influxdb3-admin/tokens/admin/preconfigured.md index 00c1f1130b..73b98859f9 100644 --- a/content/shared/influxdb3-admin/tokens/admin/preconfigured.md +++ b/content/shared/influxdb3-admin/tokens/admin/preconfigured.md @@ -7,6 +7,10 @@ Offline tokens are designed to help with automated deployments. - [Generate an offline admin token file](#generate-an-offline-admin-token-file) - [Offline admin token file schema](#offline-admin-token-file-schema) - [Start InfluxDB with the preconfigured admin token](#start-influxdb-with-the-preconfigured-admin-token) +- [Use Docker Compose with preconfigured admin tokens](#use-docker-compose-with-preconfigured-admin-tokens) + - [Create an admin token file](#create-an-admin-token-file) + - [Configure Docker Compose with secrets](#configure-docker-compose-with-secrets) + - [CI/CD setup](#cicd-setup) ## Generate an offline admin token file @@ -65,13 +69,14 @@ object with the following fields: - **token**: The raw token string (must begin with `apiv3_`) - **name**: The token name (default is `_admin`) -- **expiry_millis**: (Optional) Token expiration time as a - millisecond Unix timestamp +- **description**: (Optional) A description of the token +- **expiry_millis**: (Optional) Token expiration time as a millisecond Unix timestamp ```json { "token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...", "name": "_admin", + "description": "Admin token for InfluxDB 3", "expiry_millis": 1756400061529 } ``` @@ -113,3 +118,120 @@ influxdb3 serve \ When the server starts, you can use the preconfigured admin token to interact with your {{% product-name %}}{{% show-in "enterprise" %}} cluster or{{% /show-in %}} instance. + +## Use Docker Compose with preconfigured admin tokens + +For containerized deployments, you can use Docker Compose with Docker secrets to securely manage your preconfigured admin token. + +### Create an admin token file + +Create a JSON file with your admin token using the +[offline admin token file schema](#offline-admin-token-file-schema): + +```json +{ + "token": "apiv3_your_token_here", + "name": "admin", + "description": "Admin token for automated deployment" +} +``` + +For security, restrict file permissions: + +```bash +chmod 600 path/to/admin-token.json +``` + +### Configure Docker Compose with secrets + +Use Docker secrets to securely provide the admin token file to your container: + +{{% show-in "core" %}} +```yaml +# compose.yaml +services: + influxdb3-core: + image: influxdb:3-core + ports: + - 8181:8181 + command: + - influxdb3 + - serve + - --node-id=node0 + - --object-store=file + - --data-dir=/var/lib/influxdb3/data + - --admin-token-file=/run/secrets/admin-token + secrets: + - admin-token + volumes: + - type: bind + source: ~/.influxdb3/data + target: /var/lib/influxdb3/data + +secrets: + admin-token: + file: path/to/admin-token.json +``` +{{% /show-in %}} +{{% show-in "enterprise" %}} +```yaml +# compose.yaml +services: + influxdb3-enterprise: + image: influxdb:3-enterprise + ports: + - 8181:8181 + command: + - influxdb3 + - serve + - --node-id=node0 + - --cluster-id=cluster0 + - --object-store=file + - --data-dir=/var/lib/influxdb3/data + - --admin-token-file=/run/secrets/admin-token + environment: + - INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com + secrets: + - admin-token + volumes: + - type: bind + source: ~/.influxdb3/data + target: /var/lib/influxdb3/data + +secrets: + admin-token: + file: path/to/admin-token.json +``` +{{% /show-in %}} + +Start the service: + + + +```bash +docker compose up -d +``` + +> [!Important] +> #### Docker secrets security benefits +> +> Docker secrets provide better security than bind mounts for sensitive data: +> - Secrets are stored encrypted in memory +> - Not visible in `docker inspect` output +> - Not exposed in environment variables or logs +> - Follow Docker and Kubernetes security best practices + +### CI/CD setup + +For CI/CD pipelines and automated environments, create the admin token file from +environment variables: + + + +```bash +# Create token file from CI/CD environment variable +echo "{\"token\": \"$INFLUXDB3_ADMIN_TOKEN\", \"name\": \"admin\", \"description\": \"CI/CD admin token\"}" > admin-token.json +chmod 600 admin-token.json +``` + +Then use the file in your Docker Compose configuration as shown above. diff --git a/content/shared/influxdb3-get-started/setup.md b/content/shared/influxdb3-get-started/setup.md index c2c6e0db78..1502edaf17 100644 --- a/content/shared/influxdb3-get-started/setup.md +++ b/content/shared/influxdb3-get-started/setup.md @@ -482,7 +482,12 @@ commands and HTTP API requests. {{% product-name %}} supports _admin_ tokens, which grant access to all CLI actions and API endpoints. {{% /show-in %}} -For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/). + +> [!Tip] +> ### Preconfigured admin tokens for automated deployments +> +> For CI/CD pipelines or automated deployments, you can start {{% product-name %}} with a preconfigured admin token file instead of creating tokens manually after startup. +> For more information, see [Use a preconfigured admin token](/influxdb3/version/admin/tokens/admin/preconfigured/). ### Create an operator token