timestream-influxdb

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 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. If unsure whether a metric exists, say so explicitly.
• Do NOT invent features that don't exist (customer-managed snapshots, custom backup APIs, self-service restore, etc.). Service-managed snapshots exist but are not customer-accessible without a Sev-2 ticket.
• --publicly-accessible is a supported option at instance/cluster creation time. Do NOT say the service is exclusively VPC-only — public access is an opt-in feature.

3. Design the schema (tags vs fields)

Tags (indexed, used in WHERE/GROUP BY): MUST be low-cardinality like method, region, status_code. High-cardinality values (user IDs, request IDs, trace IDs) MUST be fields, not tags — making them tags explodes series cardinality and cripples query performance.

Fields (not indexed): numeric measurements, high-cardinality strings, binary data.

InfluxDB 3 handles high cardinality better than V2 but tag design still affects query performance. Load schema-design instructions for patterns including deduplication and retention.

4. Migrate from LiveAnalytics

LiveAnalytics is in maintenance mode. For migration to InfluxDB 3:

• <1B records / <125GB: Use the certified LiveAnalytics Migration plugin with the migration client. Exports to S3 (Parquet), re-ingests into V3.
• >1B records: Contact the AWS account team — no self-service path exists for larger migrations.

Load migration instructions for the procedure.

5. Use Processing Engine plugins (V3 only)

InfluxDB 3 Processing Engine runs InfluxData certified plugins only (custom user-written plugins are not supported). ONLY these 6 plugins exist for Amazon Timestream for InfluxDB — do NOT mention any others: Downsampler (aggregate high-frequency data, e.g. 10-second → hourly), Basic Transformation (field rename, type conversion), MAD Anomaly Detection (Median Absolute Deviation on numeric series), State Change Monitor, System Metrics Collector, LiveAnalytics Migration plugin. Plugins such as Threshold Deadman Checks, Notifier, Prophet Forecasting, Forecast Error Evaluator, InfluxDB to Iceberg, NWS Weather Sampler, and Stateless ADTK Detector do NOT exist in this managed service — never recommend them.

Triggers: scheduled, on WAL flush, or on-request. Load processing-engine instructions for configuration.

6. Monitor and operate

CloudWatch metric coverage varies by engine and deployment type. Load references/monitoring/metrics.md for the authoritative metric name tables. Key points:

• V2 SAZ/MAZ: Rich CloudWatch coverage including CPUUtilization, VolumeBytesUsed, QueryRequestsTotal, SeriesCardinality
• V2 Read Replica: LIMITED CloudWatch — only CPUUtilization, MemoryUtilization, DiskUtilization, ReplicaLag
• V3 (all): LIMITED CloudWatch — only CPUUtilization, MemoryUtilization. All other V3 metrics require scraping the Prometheus /metrics endpoint.

Set alarms on CPU >80%, storage >80% of allocated (V2), and IOPS saturation. Maintenance windows are customer-managed. Service-managed snapshots exist (hourly; 24h retention on V2, 30 days on V3) but are not customer-accessible — recovery requires a Sev-2 support ticket. Customer-managed snapshots are not available.

Setting a maintenance window

Always use JSON format for --maintenance-schedule. The CLI accepts both JSON and shorthand, but use JSON consistently:

aws timestream-influxdb update-db-instance \
  --identifier <instance-id> \
  --maintenance-schedule '{"timezone":"UTC","preferredMaintenanceWindow":"Sun:03:00-Sun:05:00"}' \
  --region <region>

Required fields: timezone (IANA string, e.g. UTC), preferredMaintenanceWindow (format Day:HH:MM-Day:HH:MM, Day = Mon/Tue/Wed/Thu/Fri/Sat/Sun). Minimum window duration is 2 hours — a 1-hour window will be rejected.

Concurrent instance creation: NO LIMIT

Timestream for InfluxDB has no service-side limit on concurrent create-db-instance or create-db-cluster calls in a single account. Multiple instances can be in CREATING state simultaneously. If asked to create an instance, always attempt the API call even when other instances exist. Only report a failure if the actual API call returns one. Do not invent constraints.

Load monitoring instructions for alarm templates and operational runbooks.

Troubleshooting

Cannot connect / connection refused

V3 uses port 8181. V2 uses port 8086. #1 cause of "connection refused" on V3 is a client configured for 8086.

You MUST tell the user ALL of:

1. Update client to port 8181 (8086 is V2).
2. Update the security group inbound rule to allow 8181 from the client's CIDR.
3. For private deployments (default): client must be in the same VPC or reach it via VPN, Direct Connect, or Transit Gateway. Public-internet clients cannot reach a private instance even with correct security groups. For publicly accessible deployments: verify the security group allows inbound from the client's public IP.

Write requests fail (400/422)

Wrong API version (V2 API against V3 cluster or vice versa), malformed line protocol, cardinality explosion, missing required tags/fields, or V3 deduplication conflict (measurement + tagset + timestamp must be unique).

Deduplication / Parquet error under high load (V3)

Known issue. You MUST recommend: (1) reduce write batch sizes, (2) add distinguishing tags so measurement + tagset + timestamp is unique. Also check S3 VPC endpoint connectivity for clusters in private subnets. Do NOT frame this as an unpreventable timing issue — it's caused by data collisions.

Query timeout / 500 error (V3)

High cardinality, missing partition template, or large cold-tier scans. Check CloudWatch CPUUtilization and scrape /metrics for influxdb_iox_query_log_execute_duration_seconds.

Parquet error (V3)

Usually VPC connectivity to S3 from the cluster. Check the S3 VPC endpoint and route table. See s3-vpc-endpoint.

Disk full / OOM

Scale storage or instance type; review V2 retention or V3 TTL.

Replication lag (V2 Read Replica)

Primary write throughput, network saturation, or replica sized below primary.

Never mix V2 and V3 remediation. Confirm engine first. Full triage: troubleshooting instructions.

Security Considerations

IAM & Access Control

• Use scoped custom IAM policies in production. FullAccess managed policies are for initial setup only.
• Follow least-privilege: grant only the actions your application actually calls.
• Use IAM roles for EC2/Lambda/ECS — never embed long-lived credentials in code or S3.

InfluxDB API Tokens

• Rotate the initial admin token/password immediately after setup.
• Create per-application scoped tokens with the minimum required permissions (read vs. write, specific bucket/database).
• Store tokens in AWS Secrets Manager and configure automatic rotation. Timestream for InfluxDB integrates natively with Secrets Manager.
• Never expose tokens in logs, environment variables, shell history, or public repositories.

Network Isolation

• Deploy instances in a private VPC unless public access is explicitly required (--publicly-accessible).
• Use Security Groups with the minimum required ingress rules (port 8086 or 8181 only, from known CIDR ranges or Security Group IDs).
• For private instances, use SSM port forwarding, VPN, or Direct Connect for remote access.

Encryption

• Data at rest: Encrypted by default for all InfluxDB engines (V2, V2 Read Replica Cluster, and V3) using AWS service-managed keys — no action is required to enable it.
• Data in transit is encrypted via TLS by default (all endpoints are HTTPS).
• For S3 log delivery buckets, enable SSE-KMS with a same-account KMS key.
• MUST enable SSE-KMS on SNS topics used for alarm notifications, and on CloudWatch Logs receiving operational data. Optionally enable SSE-KMS on other dependent resources.

S3 Bucket Policy (Log Delivery)

• Add aws:SourceArn and aws:SourceAccount conditions to prevent confused deputy attacks.
• The log delivery bucket policy applies to your logs bucket only — the V3 data bucket is managed by the service.

Auditing

• Enable AWS CloudTrail to log all Timestream for InfluxDB control-plane API calls.
• Limitation: Data-plane operations are not covered by CloudTrail. Use InfluxDB's /metrics endpoint or native audit logging for data access observability.

Additional Resources

• Timestream for InfluxDB Developer Guide
• Security in Timestream for InfluxDB
• Security best practices for Timestream for InfluxDB
• Timestream for InfluxDB Pricing
• InfluxDB 3 Documentation
• Schema Design Best Practices
• Processing Engine Documentation

Handoff from aws-database-selection

This skill can be invoked directly, or it can be entered from the aws-database-selection parent skill after that skill has run a requirements interview and produced a requirements.json artifact. When you see a backtick-wrapped path matching aws_dbs_requirements/*/requirements.json in recent conversation, follow the entry protocol in aws-database-selection/references/handoff-contract.md:

1. Read the artifact using file_read.
2. Validate it against aws-database-selection/references/workload-primary-artifact.schema.json. If malformed or unreadable, tell the user and proceed without it.
3. Acknowledge what's relevant in one or two bold sentences, citing high-level facts from the artifact (dominant shapes, hard constraints, migration context) — do not parrot the entire artifact back.
4. Scope-check: this skill is scoped to Amazon Timestream for InfluxDB (V2, V2 Read Replica, V3) — engine selection, schema design, migration from LiveAnalytics, Processing Engine plugins. If the artifact's workload_primaries.dominant_shapes or migration_context don't match that scope, emit weak backpressure per the handoff contract: suggest dynamodb-skill for non-InfluxDB time-series on DynamoDB, or go back to aws-database-selection if the dominant shape isn't time-series, then ask the user whether to go back or proceed anyway. Do not silently misuse the artifact.
5. Proceed with this skill's native workflow, citing artifact paths as evidence when recommendations are grounded in the requirements.

All user-facing output from this skill follows the markdown-primitives-only formatting convention in the handoff contract: bold labels, backticks for paths and enum values, bullet lists for alternatives, no ASCII art or box-drawing characters.