Blixt Documentation v2.9

Cloud credentials

Create a bucket and working credentials in your cloud provider, and pass them to BlixtFS.

Before installing BlixtFS you need a bucket and working credentials from your cloud provider. There is a page for each provider covering both.

BlixtFS needs credentials that can read the bucket and, unless the bucket is read-only, write and delete objects in it. To keep up with changes made outside BlixtFS, it also needs permission to set up the provider’s change notifications.

How BlixtFS is told which cloud a bucket belongs to

A bucket is named with a scheme, and the scheme is what picks the provider and the settings BlixtFS uses to reach it. s3://my-bucket is served with the AWS settings, r2://my-bucket with the Cloudflare ones, and so on. A bucket name with no scheme belongs to the cloud named by DEFAULT_CLOUD (--default_cloud, or general.default_cloud).

Provider Scheme Credentials Notes
Amazon S3 s3:// AWS credentials file, environment, or IAM role Bucket entries in a config file need the bucket’s real region
Google Cloud Storage gs:// Service-account JSON key, or Application Default Credentials Grant the storage service agent roles/pubsub.publisher
Azure Blob Storage azure:// Storage account name and key, or workload identity
Oracle OCI oci:// Customer secret key (S3-compatible), namespace and region
MinIO minio:// Access key and secret key, plus the endpoint URL
Cloudflare R2 r2:// Account ID and R2 access keys, as environment variables An API token is needed only for change notifications
CoreWeave cw:// Static access key, organization ID and availability zone, as environment variables No change notifications

Buckets covers bucket specs and their attributes, and Configuration covers the file format.

A bucket

Create at least one bucket (or container) in your cloud storage provider. If you already have one, you only need the credentials part. BlixtFS does not create buckets for you.

Working credentials

Each provider hands out credentials differently: a file for AWS, GCP, Azure and Oracle, environment variables for Cloudflare R2 and CoreWeave. Follow your provider’s page above, then see Passing credentials to the container.

Passing credentials to the container

A credentials file

Mount the file read-only and point the configuration at it:

docker run -d --name blixt \
  -p 2049:2049 \
  -v /srv/blixt:/data \
  -v ~/.aws/credentials:/credentials:ro \
  blixtfs/standard:2.9.0 --config /data/config.yaml

cloud:
  aws:
    enabled: true
    credentials: /credentials
    buckets:
      - bucket: s3://my-bucket
        region: us-east-1

Without an explicit path, the container looks in /config/gcp/credentials.json, /config/aws/config and /config/aws/credentials.

Environment variables

Cloudflare R2 and CoreWeave take no credentials file. Pass their settings as environment variables:

# Cloudflare R2
-e CLOUDFLARE_ACCOUNT_ID=... \
-e CLOUDFLARE_ACCESS_KEY=... \
-e CLOUDFLARE_SECRET_KEY=... \
-e CLOUDFLARE_API_TOKEN=...        # optional: change notifications

# CoreWeave
-e COREWEAVE_ORGANIZATION_ID=... \
-e COREWEAVE_AVAILABILITY_ZONE=US-EAST-04A \
-e COREWEAVE_ACCESS_KEY=... \
-e COREWEAVE_SECRET_KEY=...

Environment variables lists every variable.

Platform identity

On Google Compute Engine and GKE, BlixtFS uses the attached service account automatically. The Kubernetes chart supports workload identity on GCP, AWS, Azure and Oracle, so no key is stored in the cluster.

Keep secret keys out of shell history and version control. A configuration file that holds keys should be chmod 600, and in Kubernetes keys belong in Secrets.

Permissions checklist

  • List, read, write and delete objects in the bucket.
  • Create the notification plumbing (topic, queue or subscription). If your policy forbids that, have an administrator create a topic and name it with the topic= bucket attribute (GCS and S3), or run without notifications.
  • For read-only buckets: list and read only. At startup BlixtFS writes and deletes a small probe object under the reserved .__bfs__/probe/ prefix to find out whether a bucket’s credentials can write. A bucket that fails the probe is served read-only, with a warning; set cloud.strict_bucket_access to fail startup instead, or cloud.write_probe: false to skip the check.

Once your bucket and credentials are ready, continue with Docker, Kubernetes or one of the other installation guides.