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 <bucket> \
  --region us-east-1

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

aws s3api create-bucket \
  --bucket <bucket> \
  --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:::<bucket>",
        "arn:aws:s3:::<bucket>/*"
      ]
    }
  ]
}

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:

• Enterprise: pass them as --username (access key ID) and --password (secret access key) when creating the block store with configure.flexfs. They are stored in the admin server’s database and passed to the metadata server and mount clients.
• Community: pass them as --blockUser and --blockPass to free.flexfs init creds.

The metadata server and proxy servers also accept blockUser and blockPass in their own credentials files, set with --blockUser and --blockPass on init creds. The metadata server uses them only for block stores that have no password, and passes them to mount clients in that case. A proxy server always uses its own credentials for its storage access. For example, a metadata server credentials file at ~/.flexfs/meta/creds would contain:

adminAddr = "admin.example.com:443"
blockPass = "<password>"
blockUser = "<username>"
token = "<meta-token>"

Instance roles (EC2 / ECS / EKS)

When no password is configured, flexFS first tries EC2 instance role credentials from the instance metadata service (IMDS). If those are unavailable, it falls back to the AWS SDK default credential chain: environment variables, the shared ~/.aws files, web identity (such as EKS IAM roles for service accounts), and container credentials (ECS task roles, EKS Pod Identity).

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

Note

The IAM role flexFS uses must have the S3 permissions listed above. Because IMDS is tried first, the EC2 instance role takes precedence over an ECS task role, IRSA, or Pod Identity role wherever IMDS is reachable, so grant the permissions to the instance role or block IMDS access from the containers. For a block store with no password, mount clients use the credentials the metadata server passes them rather than their own role, so the role belongs on the metadata server host and on any proxy server hosts.

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

Point the block store address at your MinIO server:

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

Tip

When the address starts with http: (not https:), flexFS automatically disables TLS for the S3 connection. When the address carries no scheme, flexFS prepends https://.

Wasabi

Wasabi provides an S3-compatible API with regional endpoints:

• API code: s3
• Address: 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)
• Username: Wasabi access key
• Password: Wasabi secret key

Backblaze B2

Use Backblaze B2’s S3-compatible API:

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

Ceph RGW

For Ceph RADOS Gateway deployments:

• API code: s3
• Address: Your RGW endpoint (e.g. https://rgw.example.com)
• Username: RGW access key
• Password: RGW secret key

Server-side encryption

Amazon S3 encrypts every new object with Amazon S3-managed keys (SSE-S3) by default, so blocks written to AWS S3 are encrypted at rest without any flexFS setting. The --sse flag on the proxy server or mount client sends x-amz-server-side-encryption: AES256 on every upload, which also applies to S3-compatible stores that support the header. This overrides a bucket’s default SSE-KMS encryption for flexFS blocks, and a bucket policy that requires SSE-KMS rejects the uploads.

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
Address	Leave empty for standard AWS S3; set for S3-compatible stores
Username (--username)	Access key ID (or leave empty for instance roles)
Password (--password)	Secret access key (or leave empty for instance roles)