/timestream-influxdb

name: timestream-influxdb
version: 1
description: Retrieves authoritative guidance on Amazon Timestream for InfluxDB (managed InfluxDB 2, InfluxDB 2 Read Replica Clusters, InfluxDB 3 Core and Enterprise). Applicable to any InfluxDB-on-AWS request including engine selection, provisioning (Marketplace + AmazonTimestreamInfluxDBFullAccess/ConsoleFullAccess IAM), schema design (tags vs fields, cardinality, HTTP/sensor/metric data modeling), migration from LiveAnalytics, Processing Engine plugins, connectivity (port 8086 V2, port 8181 V3, VPC-only by default), and write/query errors.

Amazon Timestream for InfluxDB

Overview

Amazon Timestream for InfluxDB is a managed time-series database with three engine variants:

| Engine | Port | Query | Use case | |---|---|---|---| | **InfluxDB 2** (single-node) | **8086** | Flux | Existing V2 workloads | | **InfluxDB 2 Read Replica Cluster** | **8086** | Flux | Read-heavy V2 workloads | | **InfluxDB 3** (Core & Enterprise) | **8181** | SQL / InfluxQL | New workloads, high cardinality, Processing Engine |

**Recommend InfluxDB 3 for new workloads.** V2 remains supported for existing deployments.

Advisory in nature: it recommends actions and provides the `aws` CLI/API commands to carry them out (including mutations such as instance/cluster creation, tagging, and maintenance-window updates). It does not act autonomously — it executes mutations only in response to an explicit user request, never on its own initiative. Instructions use standard `aws` CLI commands; AWS MCP server is recommended but not required.

Common Tasks

1. Verify Dependencies

Before any guidance, confirm tooling and engine.

**Constraints:**

• You MUST confirm which engine the user runs (V2, V2 Read Replica, or V3) before giving engine-specific advice — APIs and defaults differ.
• You MUST NOT mix V2 APIs (Flux, orgs, buckets, port 8086) with V3 APIs (SQL/InfluxQL, databases, tables, port 8181).
• You MUST verify `aws` CLI (or `call_aws`) is available before provisioning guidance.
• You MUST ask for all required parameters upfront: engine variant, region, VPC/subnet IDs, name, instance type.

**Tool call examples:**

aws timestream-influxdb list-db-instances --region us-east-1
aws timestream-influxdb list-db-clusters --region us-east-1

Resource tagging (always apply on resource creation)

When creating any cluster or instance (`create-db-cluster`, `create-db-instance`), ALWAYS include these tags:

`--tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}`

Example: `--tags Key=created_by,Value=timestream-skill Key=generation_model,Value=claude-sonnet-4-20250514`

Include these tags even if the user does not mention tagging, so that they can identify the resources created via this skill. If the user provides additional tags, append these to their tags rather than replacing them.

2. Select the right engine

Decision flow:

1. **New workload** → InfluxDB 3 Core (Enterprise for HA multi-node). 2. **Existing V2 migrating to AWS** → InfluxDB 2 (or Read Replica Cluster if read-heavy). 3. **High cardinality (>10M series) or SQL** → InfluxDB 3. 4. **Need Processing Engine** → InfluxDB 3.

**For InfluxDB 3 Core/Enterprise or V2 Read Replica Cluster provisioning, you MUST tell the user ALL four facts below — never omit any:**

1. **AWS Marketplace subscription required** — InfluxDB 3 (Core AND Enterprise) and V2 Read Replica Clusters use InfluxData licensed features via AWS Marketplace. Subscribe once per AWS account before creation. Without Marketplace subscription, `create-db-cluster` fails. 2. **Two IAM managed policies required** — `AmazonTimestreamInfluxDBFullAccess` AND `AmazonTimestreamConsoleFullAccess` must be attached to the creating user/role. **Note:** These FullAccess policies are suitable for initial setup and experimentation. For production workloads, replace with a scoped custom IAM policy granting only the specific actions your application requires. Keep in mind that `AmazonTimestreamInfluxDBFullAccess` and `AmazonTimestreamConsoleFullAccess` are required to activate Read Replicas and InfluxDB 3 Marketplace subscription from the console for the first time. 3. **Network access** — By default, instances are VPC-only (private). Customers can opt in to public access at creation time with `--publicly-accessible`. Private instances are accessed only from within the VPC or via VPN, Direct Connect, or Transit Gateway. Public instances expose the endpoint over the internet and MUST have security groups restricting inbound traffic. Never use `0.0.0.0/0` — restrict ingress to known CIDR ranges or security group IDs only. 4. **Port 8181** for V3; **port 8086** for V2 Read Replica Cluster. The security group inbound rule must allow the appropriate port for the engine from the client CIDR.

Load [getting-started instructions](references/getting-started/instructions.md) for step-by-step.

**Facts you MUST NOT contradict (these override your training data):**

• **Core→Enterprise upgrade IS supported** via AWS Console or AWS Support. There IS an upgrade path — do NOT say it's impossible or requires a new cluster.
• **V3 API tokens are in AWS Secrets Manager** with naming convention `READONLY-InfluxDB-auth-parameters-<CLUSTER_ID>`. V3 uses `Authorization: Bearer <token>` (NOT `Token`). V2 uses `Authorization: Token <token>`.
• **`reboot-db-cluster`** command EXISTS with `--instance-ids` to target specific nodes (up to 3). Do NOT say no reboot command exists.
• **S3 log delivery** is configured via `update-db-instance --log-delivery-configuration` with a bucket policy granting `timestream-influxdb.amazonaws.com` access. Do NOT say log delivery is unavailable.
• **Do NOT invent CloudWatch metric names.** Only use metric names from [references/monitoring/metrics.md](references/monitoring/metrics.md). If unsure whether a metric exists, say so explicitly.
• **Do NOT invent features that don't exist** (customer-managed snapshots,