Skip to content
flexBlock

Amazon S3

FlexBlock drives Amazon S3 through its native API. Any S3-compatible store that supports conditional PUTs works too. The grant names the bucket, prefix, region and, for S3-compatible stores, the endpoint and path style, so none of them is passed on the command line.

Credentials

Section titled “Credentials”

FlexBlock uses the AWS default credential chain, in this order:

  1. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  2. AWS_PROFILE and the shared configuration files
  3. Web identity
  4. The container or instance role

On EC2 the recommended setup is an instance profile whose role carries a policy scoped to the prefix. Nothing to rotate, nothing on disk.

Off AWS, export the two key variables or point AWS_PROFILE at a profile in ~/.aws/credentials. Under systemd, put them in the per-instance environment file, owned by root with mode 0600; see Running Under systemd.

IAM policy

Section titled “IAM policy”

The listing permission is on the bucket and can be limited with the s3:prefix condition; the object permissions are on the prefix itself. This example covers the volume at acme-data/flexblock/acme-0001:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::acme-data",
      "Condition": { "StringLike": { "s3:prefix": ["flexblock/acme-0001/*"] } }
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::acme-data/flexblock/acme-0001/*"
    }
  ]
}

Server-side encryption with S3 managed keys needs no further permission.

Verify the grant and identity together before touching a device:

Terminal window
sudo -E flexblock show --remote

Encryption at rest

Section titled “Encryption at rest”

On S3, flexBlock requests SSE-S3 (server-side encryption with S3 managed keys) by default. Some S3-compatible stores reject the encryption header; for those, turn it off when creating the volume. If your credentials are exported environment variables, use sudo -E as shown, so they reach flexBlock:

Terminal window
sudo -E flexblock init --device-size 2T --s3-no-sse

The choice is recorded on the volume. To change it later for subsequent writes, stop the daemon and run update with --s3-sse or --s3-no-sse:

Terminal window
sudo -E flexblock update /dev/nvme1n1p1 --s3-no-sse

See Compression and Encryption.

Checksums

Section titled “Checksums”

Every chunk object is uploaded with a CRC32 checksum that S3 verifies, and verified again by flexBlock on download.

Deletes on general-purpose buckets

Section titled “Deletes on general-purpose buckets”

AWS S3 general-purpose buckets count every key of a batch delete against the prefix’s request rate. All deletes, discards while serving and wipe alike, share a budget of keys per second that starts at 2,500, never exceeds 3,500, halves when S3 throttles and recovers while deletes succeed (flexblock_obj_delete_keys_per_second). The pacing applies only to AWS S3 general-purpose buckets, not to custom endpoints or directory buckets.

S3-compatible stores

Section titled “S3-compatible stores”

Any S3-compatible store works if it enforces conditional PUTs (If-None-Match and If-Match). FlexBlock relies on them to keep two hosts from claiming the same volume.

  • init and attach check that the store enforces conditional writes, and refuse one that does not with exit code 10. Use a store, or a version of it, that enforces conditional PUTs.
  • The store’s endpoint and path-style addressing come from the grant (obj_endpoint and s3_force_path_style). Tell Paradigm4 about them when you request the grant.
  • The region string is whatever the store expects, often us-east-1.
  • The store takes the same policy shape as above, in its own dialect.
  • If the store rejects the SSE header, create the volume with --s3-no-sse.
Section titled “Related”