Amazon S3

FlexFS stores file data as compressed blocks in object storage (optionally encrypted end-to-end with AES-256). Amazon S3 is the most commonly used backend and serves as the reference implementation for S3-compatible services such as MinIO, Wasabi, Backblaze B2, and Ceph RGW.

Bucket creation

Create a dedicated S3 bucket for flexFS block storage. FlexFS writes opaque binary blocks — there is no reason to enable versioning or lifecycle rules.

aws s3api create-bucket \
  --bucket my-flexfs-blocks \
  --region us-east-1

For regions other than us-east-1, include a location constraint:

aws s3api create-bucket \
  --bucket my-flexfs-blocks \
  --region eu-west-1 \
  --create-bucket-configuration LocationConstraint=eu-west-1

Tip

Choose a region close to your metadata server and mount clients to minimize latency. If you deploy proxy groups, place the bucket in the same region as your primary proxy group.

Recommended bucket settings

• Block Public Access: Enable all four “Block Public Access” settings. FlexFS never requires public access.
• Versioning: Not required. FlexFS manages its own block lifecycle.
• Object Lock: Not required.
• Encryption: See the Server-Side Encryption section below if you want S3-managed encryption at rest.

IAM policy

FlexFS requires the following S3 permissions on the bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::my-flexfs-blocks",
        "arn:aws:s3:::my-flexfs-blocks/*"
      ]
    }
  ]
}

Attach this policy to the IAM user or role that flexFS will authenticate as.

Authentication

FlexFS supports two authentication methods for S3. The method is determined by whether static credentials are provided.

Static access keys

Provide an IAM access key ID and secret access key. During block store creation, set:

• blockUser — the AWS access key ID
• blockPass — the AWS secret access key

These values are stored in the credentials file for the metadata server and proxy server. For example, a metadata server credentials file at ~/.flexfs/meta/creds would contain:

adminAddr = "admin.example.com:443"
blockUser = "$USERNAME"
blockPass = "$PASSWORD"
token = "$TOKEN"

Instance roles (EC2 / ECS / EKS)

When blockPass is left empty, flexFS automatically attempts to use EC2 instance role credentials via the instance metadata service (IMDS). If instance role credentials are unavailable, it falls back to the default AWS credential chain (environment variables, shared credentials file, etc.).

Instance roles are the recommended authentication method for production deployments on AWS, as they eliminate the need to manage static credentials.

Note

When using instance roles, the IAM role attached to the EC2 instance (or ECS task role, or EKS service account role) must have the S3 permissions listed above.

S3-compatible stores

FlexFS uses the AWS SDK v2 with path-style addressing for any endpoint that does not end in amazonaws.com. This enables compatibility with S3-compatible object storage services.

MinIO

Set the block store endpoint to your MinIO server address:

• API code: s3
• Endpoint: https://minio.example.com:9000 (or http:// for non-TLS)
• blockUser: MinIO access key
• blockPass: MinIO secret key

Tip

When the endpoint starts with http: (not https:), flexFS automatically disables TLS for the S3 connection. When the endpoint does not start with http, flexFS prepends https://.

Wasabi

Wasabi provides an S3-compatible API with regional endpoints:

• API code: s3
• Endpoint: https://s3.wasabisys.com (or the region-specific endpoint, e.g. https://s3.us-east-2.wasabisys.com)
• Region: The Wasabi region (e.g. us-east-2)
• blockUser: Wasabi access key
• blockPass: Wasabi secret key

Backblaze B2

Use Backblaze B2’s S3-compatible API:

• API code: s3
• Endpoint: https://s3.us-west-004.backblazeb2.com (use your account’s regional endpoint)
• blockUser: B2 application key ID
• blockPass: B2 application key

Ceph RGW

For Ceph RADOS Gateway deployments:

• API code: s3
• Endpoint: Your RGW endpoint (e.g. https://rgw.example.com)
• blockUser: RGW access key
• blockPass: RGW secret key

Server-side encryption

FlexFS supports S3 server-side encryption with Amazon S3-managed keys (SSE-S3, AES256). When enabled, every PutObject call includes the x-amz-server-side-encryption: AES256 header, instructing S3 to encrypt blocks at rest using AWS-managed keys.

Enable SSE on the proxy server or mount client with the --sse flag.

Caution

SSE-S3 is independent of flexFS end-to-end encryption (Enterprise). When both are enabled, blocks are encrypted twice: first by the client (AES-256-GCM), then by S3 (SSE-S3). The two mechanisms serve different purposes — end-to-end encryption ensures that unencrypted data never leaves the client, while SSE provides an additional compliance layer at rest in S3.

Block store configuration

When creating a block store via configure.flexfs (Enterprise) or the installer, provide:

Field	Value
Provider	aws
Region	AWS region code (e.g. us-east-1)
API	s3
Bucket	Your S3 bucket name
Prefix	Optional key prefix for multi-tenant buckets
Endpoint	Leave empty for standard AWS S3; set for S3-compatible stores
blockUser	Access key ID (or leave empty for instance roles)
blockPass	Secret access key (or leave empty for instance roles)