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.

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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

7. 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.

8. Back up the packaged InfluxDB TOML file.

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

9. 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

10. 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

11. 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 #####

12. 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.

13. Create a database with an existing admin token.

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

    Related: How to create an InfluxDB 3 Core admin token

14. 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)

    Related: How to write line protocol with the influxdb3 CLI

15. 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  |
    +---------+-------+

    Related: How to run an SQL query in InfluxDB 3 Core

16. 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.