Block Stores

Note

Block store management via configure.flexfs is an Enterprise-only feature. Community edition configures its block store directly during free.flexfs init creds.

A block store defines where flexFS stores file data blocks. Each block store maps to a bucket (or container) in a cloud object storage service. Volumes reference a block store by ID — all data blocks for that volume are stored in the configured bucket and prefix.

Block Store Fields

For the full list of block store fields, their flags, types, and defaults, see Block Store Fields in the configure.flexfs CLI reference. Per-backend meanings for --username and --password are given under Credential Handling below.

The provider_code, region_code, and block_api_code are immutable after creation. Credentials (username, password), the endpoint address, the prefix, and the OCI --namespace can be updated. configure.flexfs deliberately does not offer --bucket on update; a bucket name can only be changed through the REST API, and is guarded as described below.

Caution

The bucket name and prefix together determine where blocks are read and written for every volume using the block store. Changing either relocates all future block operations; blocks already written stay where they are, neither reachable nor reclaimable by retention cleanup.

The server therefore rejects a bucket-name or prefix change with 409 (block store is in use by N volume(s)) while any volume still references the block store. Retiring a volume is not sufficient on its own: it stops counting only once its cleanup has completed, which happens after its retention period has elapsed.

Changing an OCI --namespace relocates the store to a different tenancy, so it is guarded too, but on a narrower test: it is refused once any volume on the store has reported holding blocks. That leaves the repair it exists for — a namespace that was wrong from the start, where nothing was ever written — while refusing to move a store that is in use.

Note

--bucket and --namespace write to the same bucket field. OCI Object Storage identifies a bucket by tenancy namespace as well as name, so for --apiCode oci the two are stored together there as a JSON object. list and show render it as namespace/bucket; use --json to see the value exactly as stored. Filtering a list with --bucket accepts the bucket name on its own or the namespace/bucket form shown in the listing.

Creating a Block Store

Tip

When using IAM instance roles, managed identities, or instance principals, omit --username and --password. FlexFS will use the ambient credentials from the instance metadata service.

Amazon S3

configure.flexfs create block-store \
  --providerCode aws \
  --regionCode <region> \
  --apiCode s3 \
  --bucket <bucket> \
  --prefix <prefix> \
  --username <username> \
  --password <password>

Google Cloud Storage

GCS uses the native Cloud Storage API. Pass a service account JSON key as --password, or omit credentials entirely to use the workload’s application default credentials:

configure.flexfs create block-store \
  --providerCode gcp \
  --regionCode <region> \
  --apiCode gcs \
  --bucket <bucket> \
  --prefix <prefix> \
  --password "$(cat service-account.json)"

--address is not needed for standard GCS. Set it only to reach a restricted VIP (restricted.googleapis.com) or a local emulator.

Azure Blob Storage

--username is the storage account name and --password its access key:

configure.flexfs create block-store \
  --providerCode azure \
  --regionCode <region> \
  --apiCode azure \
  --bucket <container> \
  --prefix <prefix> \
  --username <username> \
  --password <password>

The endpoint defaults to the public commercial cloud, <storage-account>.blob.core.windows.net. Reaching a sovereign cloud, Azure Stack, or a custom domain requires --address, given as the full service host including the account label:

configure.flexfs create block-store \
  --providerCode azure \
  --regionCode <region> \
  --apiCode azure \
  --bucket <container> \
  --username <username> \
  --password <password> \
  --address <username>.blob.core.usgovcloudapi.net

The Azurite emulator addresses the account in the path rather than as a subdomain, so give --address that form:

configure.flexfs create block-store \
  --providerCode azure \
  --regionCode <region> \
  --apiCode azure \
  --bucket <container> \
  --username devstoreaccount1 \
  --password <azurite-key> \
  --address http://127.0.0.1:10000/devstoreaccount1

Azure is the only API whose --address may carry a path. For the others the bucket is a separate field, so a path there is rejected as a likely pasted bucket URL.

Oracle Cloud Infrastructure

OCI requires --namespace in addition to --bucket:

configure.flexfs create block-store \
  --providerCode oci \
  --regionCode <region> \
  --apiCode oci \
  --bucket <bucket> \
  --namespace <namespace> \
  --prefix <prefix> \
  --username <username> \
  --password <password>

To correct a namespace on an existing OCI block store:

configure.flexfs update block-store <id> --namespace <namespace>

S3-Compatible Storage

For S3-compatible stores like MinIO, Wasabi, or Ceph RGW, use the s3 API code with a custom --address:

configure.flexfs create block-store \
  --providerCode minio \
  --regionCode <region> \
  --apiCode s3 \
  --bucket <bucket> \
  --prefix <prefix> \
  --username <username> \
  --password <password> \
  --address minio.example.com:9000

Note

A block store can only reference a provider and region that already exist. A custom provider code like minio, and the region code it uses, are not built in, so create the provider and region first with configure.flexfs create provider and configure.flexfs create region. See Providers and Regions.

Updating a Block Store

Credentials, the address, the prefix, and the OCI --namespace can be updated on an existing block store. The prefix and the bucket name are relocation-guarded, as described above.

configure.flexfs update block-store <id> \
  --username <username> \
  --password <password>

configure.flexfs update block-store <id> --address new-endpoint.example.com

Listing Block Stores

configure.flexfs list block-stores

The list view shows id, provider_code, region_code, block_api_code, address, bucket, and prefix. Credentials are not shown in list output.

Viewing Block Store Details

configure.flexfs show block-store <id>

The full detail view includes all fields. The password field is included in the output — treat it as sensitive.

Deleting a Block Store

configure.flexfs delete block-store <id>

Note

A block store cannot be deleted while it is referenced by any volume. Retire or delete all volumes using the block store first. Deleting a block store removes only the configuration record — the block data in the bucket is not affected.

Prefix and Bucket Design

The prefix field determines the key prefix for all blocks stored by volumes using this block store. Using different prefixes within the same bucket allows multiple block stores to share a single bucket:

# Production block store
configure.flexfs create block-store \
  --providerCode aws --regionCode <region> --apiCode s3 \
  --bucket <bucket> --prefix prod

# Staging block store (same bucket, different prefix)
configure.flexfs create block-store \
  --providerCode aws --regionCode <region> --apiCode s3 \
  --bucket <bucket> --prefix staging

Credential Handling

Note

Credentials (username and password) are stored in the admin server’s database and transmitted to mount clients over TLS when they authenticate. For environments that use IAM roles or instance profiles, credentials can be omitted — the mount client and metadata server will fall back to the cloud provider’s ambient credential chain.

For storage backends that require explicit credentials:

Backend	Username	Password
Amazon S3	AWS access key ID	AWS secret access key
Google Cloud Storage	(unused)	Service account JSON key (leave empty for application default credentials)
Azure Blob Storage	Storage account name	Storage account access key
Oracle Cloud (oci API)	JSON identity document: tenancy_ocid, user_ocid, region, key_id, key_fingerprint	PEM-encoded RSA private key
S3-compatible	Access key	Secret key