Getting Started and Setup

When to Activate

User wants to create a new Timestream for InfluxDB instance or cluster, connect to an existing one, choose between engine variants, or configure authentication.

Workflow

1. Determine Engine Variant

Ask the user one question: "Are you starting a new project or working with an existing InfluxDB deployment?"

New project → Recommend InfluxDB 3 (SQL support, Processing Engine, better high-cardinality handling)
Existing V2 deployment → Stay on V2 unless they want to migrate (route to migration)
Need read scaling → Verify the supported read-scaling options; use a Read Replica Cluster only when the engine and licensing documentation supports it for the selected variant

2. Provision

Before either V2 creation command, store the initial username and generated password as JSON in Secrets Manager. Retrieve that SecretString to a mode-600 file on an encrypted volume, use it as CLI input, and delete it immediately after creation:

V2_ADMIN_SECRET_ID="/timestream-influxdb/<resource-name>/initial-admin"
V2_ADMIN_INPUT="<mode-600-json-file-on-encrypted-volume>"
umask 077
aws secretsmanager get-secret-value \
  --secret-id "$V2_ADMIN_SECRET_ID" \
  --query SecretString --output text > "$V2_ADMIN_INPUT"

Keep shell tracing disabled. The password is not a literal command argument or written to shell history.

InfluxDB 2 (standalone instance):

aws timestream-influxdb create-db-instance \
  --cli-input-json "file://${V2_ADMIN_INPUT}" \
  --name my-influxdb \
  --db-instance-type <instance-type> \
  --db-storage-type <storage-type> \
  --allocated-storage <allocated-storage-gib> \
  --deployment-type SINGLE_AZ \
  --vpc-subnet-ids subnet-abc \
  --vpc-security-group-ids sg-abc \
  --db-parameter-group-identifier <param-group-id> \
  --organization my-org --bucket my-bucket \
  --tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}
rm -f "$V2_ADMIN_INPUT"

Before selecting <instance-type>, <storage-type>, or <allocated-storage-gib>, verify the supported DB instance classes, storage types, and storage ranges for the V2 deployment type and Region in the Timestream for InfluxDB documentation and CreateDbInstance API model. Encryption at rest is required; verify the service-applied encryption behavior and supported key choices in the Data protection documentation and CreateDbInstance API model.

For production instances, inspect CreateDbInstance for create-time log-delivery support. When supported, configure log delivery during creation with the documented request shape and apply the bucket-policy and SSE-KMS controls in Log Delivery to S3. Do not pass a log-delivery field when the operation does not accept it.

Security best practice — InfluxDB V2 credentials:

Keep the generated password in Secrets Manager and do not print the secret value.

Rotate the initial admin password immediately after first login; it is set during instance creation and should not be used by applications.

Create scoped API tokens for each application or service — never share the operator token.

The engine does not support automatic token expiration or rotation. Token rotation is the customer's responsibility. There is no automatic synchronization between AWS Secrets Manager and the engine's token management layer.

For InfluxDB V3 or new deployments, the preferred approach is Secrets Manager-based Bearer tokens provisioned automatically by the service.

InfluxDB 2 Read Replica Cluster:

aws timestream-influxdb create-db-cluster \
  --cli-input-json "file://${V2_ADMIN_INPUT}" \
  --name my-rr-cluster \
  --db-instance-type <instance-type> \
  --db-storage-type <storage-type> \
  --allocated-storage <allocated-storage-gib> \
  --deployment-type MULTI_NODE_READ_REPLICAS \
  --vpc-subnet-ids subnet-az1 subnet-az2 \
  --vpc-security-group-ids sg-abc \
  --db-parameter-group-identifier <param-group-id> \
  --organization my-org --bucket my-bucket \
  --tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}
rm -f "$V2_ADMIN_INPUT"

For production Read Replica Clusters, inspect CreateDbCluster for create-time log-delivery support. When supported, configure log delivery during creation with the documented request shape and apply the bucket-policy and SSE-KMS controls in Log Delivery to S3. Do not pass a log-delivery field when the operation does not accept it.

V2 Read Replica security: Encryption at rest is required. Before creation, verify the service-applied encryption and supported key choices for V2 Read Replica Clusters in the Data protection documentation and CreateDbCluster API model. Pass --kms-key-id only when the API supports it for the selected engine variant. Verify the credential-secret response field in the API model; when the service returns influxAuthParametersSecretArn, retrieve the initial admin credentials from that Secrets Manager secret, rotate the password immediately after setup, and use a separate scoped token for each application.

InfluxDB 3 Core Creation Contract

The current CreateDbCluster API contract for InfluxDB 3 Core is:

Use create-db-cluster. Never substitute the V2 create-db-instance operation.
Use the exact default parameter-group identifier InfluxDBV3Core. Do not substitute a guessed identifier or a V2 parameter group.
Omit V2-only creation fields. Do not pass allocatedStorage, dbStorageType, deploymentType, username, password, organization, or bucket (the CLI forms are --allocated-storage, --db-storage-type, --deployment-type, --username, --password, --organization, and --bucket).
Verify Core's current Marketplace and licensing prerequisites. Check the Timestream for InfluxDB documentation and current CreateDbCluster API model before provisioning. Do not infer Core requirements from V2, Read Replica, or Enterprise. If an intended Core creation returns a Marketplace or Read Replica licensing error, recheck the current documentation, parameter-group identifier, and request fields rather than switching to a V2 operation.
Use port 8181. Port 8086 is for V2. Restrict inbound access to known CIDR ranges or security-group IDs; never use 0.0.0.0/0.

Treat the current service API reference and Timestream for InfluxDB documentation as authoritative. If the installed AWS CLI or SDK model does not expose create-db-cluster or InfluxDBV3Core, update the CLI or SDK before provisioning. Do not work around a stale local model by falling back to create-db-instance, V2 fields, port 8086, or V2 licensing assumptions.

InfluxDB 3 (cluster):

aws timestream-influxdb create-db-cluster \
  --name my-v3-cluster \
  --db-instance-type <instance-type> \
  --db-parameter-group-identifier InfluxDBV3Core \
  --vpc-subnet-ids subnet-abc subnet-def \
  --vpc-security-group-ids sg-abc \
  --tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}

# Recommended arguments for production after verifying CreateDbCluster support:
#   --kms-key-id <kms-key-arn>
#   --log-delivery-configuration '{"s3Configuration":{"bucketName":"<logs-bucket>","enabled":true}}'

After create-db-cluster returns, use its cluster ID to poll get-db-cluster until the status is AVAILABLE or a terminal failure. Do not report creation complete or ask the user to take over polling while the cluster remains CREATING. When creation requested a customer-managed KMS key, also require the returned kmsKeyId ARN to exactly match the requested key ARN before reporting success. Treat an absent kmsKeyId during CREATING as unverified and check it again at AVAILABLE; a missing or different value at AVAILABLE is a failed verification.

After creation, follow AWS CloudTrail integration. Verify event coverage in the Timestream for InfluxDB CloudTrail documentation, then confirm that a trail records the documented management events with the required retention, encryption, and log-file validation controls.

For production clusters, configure log delivery when the selected engine variant supports it and apply the documented bucket-policy and SSE-KMS controls in Log Delivery to S3. Omit --log-delivery-configuration only for dev/test workloads or when the current API model and documentation explicitly show that the selected engine variant does not support it.

Before selecting <instance-type>, check the Timestream for InfluxDB DB instance classes documentation; supported classes can change and should not be inferred from examples.

Encryption at rest is required for production workloads. Verify the service-applied encryption option and kmsKeyId support in the Create API. Use --kms-key-id when customer-controlled policy, rotation, revocation, or auditing is required. Omit it only when the current documentation confirms AWS-owned default encryption and that option satisfies the workload's requirements, generally for dev/test. Load encryption guidance before choosing between the documented encryption options.

Default parameter group identifiers: List the available groups and verify the documentation or API model before selecting an identifier:

aws timestream-influxdb list-db-parameter-groups --region <region>

Use the exact default identifier listed for the selected engine variant. Create a custom group only when you need to override defaults.

3. Retrieve Token

V2: Token is stored in Secrets Manager at the ARN returned in influxAuthParametersSecretArn:

aws secretsmanager get-secret-value \
  --secret-id <influxAuthParametersSecretArn> \
  --query SecretString --output text

After retrieving the initial credentials, create an all-access operator token via the InfluxDB UI or cookie-based API auth (see V2 Onboarding below).

V3: Inspect the GetDbCluster output or API model for the token-secret ARN field. When the response includes influxAuthParametersSecretArn, use the ARN it returns; do not derive a secret identifier from a naming convention:

V3_TOKEN_SECRET_ARN="$(
  aws timestream-influxdb get-db-cluster \
    --db-cluster-id <cluster-id> \
    --query influxAuthParametersSecretArn \
    --output text
)"
aws secretsmanager get-secret-value \
  --secret-id "$V3_TOKEN_SECRET_ARN" \
  --query SecretString --output text

Before modifying or rotating the secret, verify its ownership and rotation behavior in the Timestream for InfluxDB documentation. Do not assume that changing its SecretString changes the cluster token.

4. Connect

Security group configuration for publicly accessible instances:

When creating an instance or cluster with --publicly-accessible, the endpoint is exposed over the public internet. Public access is a supported opt-in feature at creation time — by default, instances are private (VPC-only). For publicly accessible deployments, the default security group blocks all inbound traffic. You must add an inbound rule for the InfluxDB port:

# V2 (port 8086)
aws ec2 authorize-security-group-ingress \
  --group-id <sg-id> \
  --protocol tcp --port 8086 \
  --cidr <your-ip>/32   # or another trusted client CIDR; never use 0.0.0.0/0

# V3 (port 8181)
aws ec2 authorize-security-group-ingress \
  --group-id <sg-id> \
  --protocol tcp --port 8181 \
  --cidr <your-ip>/32

Restrict the CIDR to the smallest set of IPs that need access. Never use 0.0.0.0/0.

For private (VPC-only) deployments: Clients must be in the same VPC or reach the instance via VPN, Direct Connect, or Transit Gateway. Security group rules should allow inbound from the VPC CIDR or specific private subnets.

InfluxDB 2: Endpoint on port 8086. Use the InfluxDB 2.x API with org/bucket/token. Keep the scoped token in Secrets Manager and supply it through the CLI's supported environment variable instead of saving it in an unencrypted local config:

export INFLUX_TOKEN="$(
  aws secretsmanager get-secret-value \
    --secret-id "<v2-application-token-secret-id>" \
    --query SecretString --output text |
  jq -er '.token'
)"
INFLUX_HOST="https://<endpoint>:8086" INFLUX_ORG="<org>" influx bucket list
unset INFLUX_TOKEN

InfluxDB 3: Endpoint on port 8181. Use SQL or InfluxQL via the InfluxDB 3.x API.

# Set V3_TOKEN_SECRET_ARN from GetDbCluster as shown in Retrieve Token.
V3_TOKEN="$(
  aws secretsmanager get-secret-value \
    --secret-id "$V3_TOKEN_SECRET_ARN" \
    --query SecretString --output text |
  jq -er '.token'
)"

# Write via line protocol
printf 'Authorization: Bearer %s\n' "$V3_TOKEN" |
curl -X POST "https://<endpoint>:8181/api/v3/write_lp?db=<database>" \
  -H @- \
  -H "Content-Type: text/plain" \
  -d "measurement,tag=value field=1.0"

# Query via SQL
printf 'Authorization: Bearer %s\n' "$V3_TOKEN" |
curl -X POST "https://<endpoint>:8181/api/v3/query_sql" \
  -H @- \
  -H "Content-Type: application/json" \
  -d '{"db":"<database>","q":"SELECT * FROM measurement LIMIT 10"}'

unset V3_TOKEN V3_TOKEN_SECRET_ARN

5. Post-Setup

Configure maintenance window
Set up CloudWatch alarms → route to monitoring
Design schema → route to schema-design

Private Access via SSM Bastion

For V3 clusters in private subnets without direct connectivity:

aws ssm start-session --target <bastion-instance-id> \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["<CLUSTER_ENDPOINT>"],"portNumber":["8181"],"localPortNumber":["8181"]}'

Add 127.0.0.1 <CLUSTER_ENDPOINT> to /etc/hosts so TLS certificate validation succeeds against the forwarded connection.

Log Delivery to S3

Before configuring log delivery, verify its availability, delivery cadence, bucket account and Region constraints, KMS key constraints, service principal, object prefix, and source-ARN formats in the Timestream for InfluxDB documentation and the applicable create or update API reference. Treat those sources as authoritative; adapt or omit the following template when they differ.

SSE-KMS note: Use only the KMS key ownership and account arrangements that the log-delivery documentation supports. Do not assume that a cross-account key works.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "timestream-influxdb.amazonaws.com"},
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::BUCKET_NAME/InfluxLogs/*",
    "Condition": {
      "StringEquals": {
        "aws:SourceAccount": "YOUR_ACCOUNT_ID"
      },
      "ArnLike": {
        "aws:SourceArn": [
          "arn:aws:timestream-influxdb:<REGION>:<ACCOUNT_ID>:db-instance/<INSTANCE_ID>",
          "arn:aws:timestream-influxdb:<REGION>:<ACCOUNT_ID>:db-cluster/<CLUSTER_ID>"
        ]
      }
    }
  }]
}

When the log-delivery documentation prescribes aws:SourceArn, add it to prevent confused deputy attacks and scope it to the exact source resource. Apply this template only to a customer-managed log bucket, and verify data-bucket ownership before stating whether the customer can configure its bucket policy.

Enable via create or update:

--log-delivery-configuration '{"s3Configuration":{"bucketName":"BUCKET","enabled":true}}'

Reboot Commands

Before targeting specific nodes, inspect the current RebootDbCluster request model and Timestream for InfluxDB documentation to verify the maximum number of instanceIds and any other request constraints. Do not assume a fixed limit.

# V2 instance
aws timestream-influxdb reboot-db-instance --identifier <instance-id>

# V3 cluster (all nodes)
aws timestream-influxdb reboot-db-cluster --db-cluster-id <cluster-id>

# V3 cluster (specific nodes)
aws timestream-influxdb reboot-db-cluster --db-cluster-id <cluster-id> \
  --instance-ids <id1> <id2>

Determine Updatable Fields

For a V2 instance, inspect the UpdateDbInstance request parameters or the installed CLI or SDK model. For a cluster, inspect the UpdateDbCluster request parameters or installed model. Use only fields exposed by the selected operation, and verify documented restart, replacement, transition, and value constraints before proposing an update. Do not infer updatability from a Create operation or a cached field list. For kmsKeyId, follow the API verification and migration guidance in encryption guidance.

V2 Onboarding: Cookie Auth for Operator Token

After initial provisioning, the credentials in Secrets Manager give you UI access but not a full API operator token. To create one:

Sign in to the InfluxDB UI at https://<endpoint>:8086 with the username/password from Secrets Manager
Navigate to Load Data → API Tokens → Generate API Token → All Access API Token
Copy the generated operator token directly into a new AWS Secrets Manager secret. Do not persist it in local files, shell profiles, logs, or source control; clear any clipboard copy after storage.
Create scoped tokens for application use, store each one in AWS Secrets Manager immediately, and avoid using the all-access operator token in production applications.

Marketplace Activation and IAM Prerequisites

Before provisioning, verify the Marketplace subscription and activation requirements for the selected engine variant in the Timestream for InfluxDB documentation and the CreateDbCluster API reference. Do not reuse licensing prerequisites from another engine variant.

When the documentation requires first-time Marketplace activation through the console, attach AmazonTimestreamInfluxDBFullAccess and AmazonTimestreamConsoleFullAccess only to the principal performing that activation. Remove both managed policies immediately after activation succeeds, within the same administrative session whenever possible, and replace them with the scoped custom policy below before production or operational use. Leaving either FullAccess policy attached to a production identity is a significant over-privilege risk. Configure an AWS Config custom rule or equivalent periodic control to detect either policy remaining attached after activation, and use IAM Access Analyzer unused-access findings to further reduce the replacement policy.

Example scoped policy for day-to-day operations (read plus the operational write actions this guide uses — update, reboot, tag):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListResources",
      "Effect": "Allow",
      "Action": [
        "timestream-influxdb:ListDbInstances",
        "timestream-influxdb:ListDbClusters"
      ],
      "Resource": "*"
    },
    {
      "Sid": "OperateOnSelectedResources",
      "Effect": "Allow",
      "Action": [
        "timestream-influxdb:GetDbInstance",
        "timestream-influxdb:GetDbCluster",
        "timestream-influxdb:ListTagsForResource",
        "timestream-influxdb:UpdateDbInstance",
        "timestream-influxdb:UpdateDbCluster",
        "timestream-influxdb:RebootDbInstance",
        "timestream-influxdb:RebootDbCluster",
        "timestream-influxdb:TagResource"
      ],
      "Resource": [
        "arn:aws:timestream-influxdb:<region>:<account-id>:db-instance/<instance-id>",
        "arn:aws:timestream-influxdb:<region>:<account-id>:db-cluster/<cluster-id>"
      ]
    }
  ]
}

Retain only the actions and resource type required by the operator. Replace each identifier with an exact resource ID; do not broaden it to *. Verify action-level resource support in the Service Authorization Reference, and use Resource: "*" only for actions that do not support resource-level permissions.

Compare Engine Variants

Before comparing engine variants, retrieve the Timestream for InfluxDB documentation and inspect the applicable Create, Get, and Update API models for each candidate. Verify each variant's query languages, authentication flow, data model, endpoint, resource operation, deployment and storage model, scaling behavior, Processing Engine support, and Region-specific constraints. Use only capabilities confirmed by those sources for the user's Region and requested operation; do not infer one variant's behavior from another variant or from examples in this guide.

Instance Types

Before recommending an instance class, retrieve the Timestream for InfluxDB DB instance classes documentation and inspect the Create API model for the selected engine variant and Region. Use only instance classes and hardware specifications those sources identify as supported. Do not infer availability, vCPU, memory, or workload fit from examples or a cached class list.

/timestream-influxdb

referencesgetting-started.md