How to configure S3 object storage for InfluxDB 3 Core

Configuring Amazon S3 object storage makes InfluxDB 3 Core store catalog records, write-ahead log files, snapshots, and Parquet data under a bucket prefix instead of a local data directory. Use it before the first production start of a packaged Core service when the database host should persist state in network object storage.

The packaged influxdb3-core service reads /etc/influxdb3/influxdb3-core.conf and converts TOML keys into INFLUXDB3_* environment variables before it runs influxdb3 serve. For S3, the service needs an unchanged node-id, object-store="s3", a bucket name, the bucket region, and credentials that can list the bucket and read, write, and delete objects.

Keep the bucket dedicated to one InfluxDB 3 Core deployment or to one clearly separated bucket prefix. The node-id becomes the leading object-key prefix, so changing it after data is written makes the same bucket look like a different server state to Core.

Steps to configure S3 object storage for InfluxDB 3 Core:

Choose the bucket, region, IAM identity, AWS CLI profile, and InfluxDB node ID.
```
Bucket: influxdb3-prod-core
Region: us-west-2
IAM user or role: influxdb3-core
AWS CLI profile for service credential tests: influxdb3-storage
InfluxDB node-id: core01
```
Use a bucket name that is globally unique in Amazon S3. Keep the node-id unchanged for the lifetime of the stored Core data.

Create the dedicated S3 bucket when it does not already exist.

$ aws s3api create-bucket \
  --bucket influxdb3-prod-core \
  --region us-west-2 \
  --create-bucket-configuration LocationConstraint=us-west-2 \
  --profile platform-admin
{
    "Location": "http://influxdb3-prod-core.s3.amazonaws.com/"
}

For us-east-1, omit --create-bucket-configuration because S3 treats that region differently from other regions.

Confirm the bucket region before writing the service configuration.
```
$ aws s3api get-bucket-location \
  --bucket influxdb3-prod-core \
  --profile platform-admin
{
    "LocationConstraint": "us-west-2"
}
```
A region mismatch can make the service fail object-store initialization with redirect or authentication errors even when the access key is valid.

Save a bucket-scoped IAM policy document for the credential that InfluxDB uses.

$ vi influxdb3-s3-policy.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::influxdb3-prod-core"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::influxdb3-prod-core/*"
    }
  ]
}

Attach the policy to the IAM user or role that owns the access key used by the service. Avoid giving the database host broad account-wide S3 access.

Attach the policy document to the IAM user that supplies the service access key.

$ aws iam put-user-policy \
  --user-name influxdb3-core \
  --policy-name InfluxDB3S3ObjectStore \
  --policy-document file://influxdb3-s3-policy.json \
  --profile platform-admin

Use aws iam put-role-policy instead when the credential is issued from an IAM role.

Create a root-protected credential file on the InfluxDB host.

$ sudo install -o influxdb3 -g influxdb3 -m 0600 /dev/null /etc/influxdb3/s3-credentials.json

Add the S3 access key to the credential file.
```
$ sudoedit /etc/influxdb3/s3-credentials.json
```
```
{
  "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "aws_secret_access_key": "REPLACE_WITH_SECRET_ACCESS_KEY"
}
```
Store the real secret in the protected file only. Do not paste it into shell history, screenshots, shared transcripts, or the TOML configuration file.

Back up the packaged InfluxDB TOML file.

$ sudo cp -a /etc/influxdb3/influxdb3-core.conf /etc/influxdb3/influxdb3-core.conf.bak

Set the S3 object-store values in the packaged TOML file.
```
$ sudoedit /etc/influxdb3/influxdb3-core.conf
```
```
node-id="core01"
object-store="s3"
bucket="influxdb3-prod-core"
aws-default-region="us-west-2"
aws-credentials-file="/etc/influxdb3/s3-credentials.json"
plugin-dir="/var/lib/influxdb3/plugins"
log-filter="info"
```
The credential file overrides matching access-key flags if both are present. Keep any existing token, plugin, log, or HTTP settings that belong to the service.
Related: How to configure InfluxDB 3 Core for systemd
Restart the packaged service to apply the object-store change.
```
$ sudo systemctl restart influxdb3-core
```
Changing object-store on a server that already has file-backed data does not move that data into S3. Back up or migrate existing data before changing a live node's storage backend.

The packaged unit has no reload action for storage changes. Restarting is required.
Related: How to manage the InfluxDB 3 Core service with systemctl

Confirm the service is running after the restart.

$ systemctl status influxdb3-core
● influxdb3-core.service - InfluxDB 3 Core
     Loaded: loaded (/usr/lib/systemd/system/influxdb3-core.service; enabled; preset: enabled)
     Active: active (running) since Sat 2026-06-20 08:12:11 UTC; 7s ago
   Main PID: 1842 (influxdb3)
##### snipped #####

Check the recent service log for S3 or credential initialization errors.

$ sudo journalctl --unit influxdb3-core -n 30 --no-pager
Jun 20 08:12:11 db01 systemd[1]: Started influxdb3-core.service - InfluxDB 3 Core.
Jun 20 08:12:12 db01 influxdb3[1842]: InfluxDB 3 Core server started
##### snipped #####

If the journal reports an object-store error, fix the first bucket, region, permission, or credential message before writing data.

Create a database with an existing admin token.

$ influxdb3 create database \
  --token "$INFLUXDB3_AUTH_TOKEN" \
  factory_metrics
Database "factory_metrics" created successfully

Write one line protocol point through the restarted service.

$ influxdb3 write \
  --token "$INFLUXDB3_AUTH_TOKEN" \
  --database factory_metrics \
  'temperature,site=plant-1 value=22.4'
768ms: 1 request (1.30 requests/sec), 1 lines (1 lines/s), 35B (45B/s)

Query the point from the same database.

$ influxdb3 query \
  --token "$INFLUXDB3_AUTH_TOKEN" \
  --database factory_metrics \
  'SELECT site, value FROM temperature'
+---------+-------+
| site    | value |
+---------+-------+
| plant-1 | 22.4  |
+---------+-------+

List the S3 node prefix to confirm that Core created bucket objects.

$ aws s3 ls s3://influxdb3-prod-core/core01/ \
  --recursive \
  --profile influxdb3-storage
2026-06-20 04:15:47         98 core01/catalog/v3/logs/00000000000000000001.catalog
2026-06-20 04:15:47        498 core01/catalog/v3/logs/00000000000000000003.catalog
2026-06-20 04:16:37        156 core01/wal/00000000001.wal

Catalog and WAL objects under the node-id prefix prove that InfluxDB 3 Core is using the configured bucket. Parquet files appear as data is snapshotted and compacted.