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

Field	Flag	Type	Required	Description
id	—	integer	auto	Unique identifier (auto-assigned)
provider_code	--providerCode	string	create	Provider code (e.g., aws, gcp)
region_code	--regionCode	string	create	Region code (e.g., us-east-1)
block_api_code	--apiCode	string	create	Storage API protocol: s3, gcs, azure, oci
bucket	--bucket	string	create	Storage bucket or container name
bucket	--namespace	string	oci	Object storage namespace; required for oci, rejected for every other API
prefix	--prefix	string	—	Key prefix within the bucket (relocation-guarded; see caution below)
username	--username	string	—	S3: access key. Azure: storage account. OCI: JSON identity. GCS: unused
password	--password	string	—	S3: secret key. Azure: account key. OCI: PEM private key. GCS: service account JSON
address	--address	string	—	Object storage endpoint; overrides the backend’s default. See each backend 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 or prefix change with 409 while any volume on the block store still holds blocks — that is, any volume whose blocks have not yet been reclaimed. Retiring a volume is not sufficient on its own; its blocks remain until retention cleanup has run.

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 us-east-1 \
  --apiCode s3 \
  --bucket my-flexfs-bucket \
  --prefix flexfs \
  --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 us-central1 \
  --apiCode gcs \
  --bucket my-flexfs-bucket \
  --prefix flexfs \
  --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 eastus \
  --apiCode azure \
  --bucket my-flexfs-container \
  --prefix flexfs \
  --username $USERNAME \
  --password $PASSWORD

The endpoint defaults to the public commercial cloud, <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 usgovvirginia \
  --apiCode azure \
  --bucket my-flexfs-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 local \
  --apiCode azure \
  --bucket my-flexfs-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 us-ashburn-1 \
  --apiCode oci \
  --bucket my-flexfs-bucket \
  --namespace my-tenancy-namespace \
  --prefix flexfs \
  --username $USERNAME \
  --password $PASSWORD

To correct a namespace on an existing OCI block store:

configure.flexfs update block-store <id> --namespace my-tenancy-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 local \
  --apiCode s3 \
  --bucket flexfs \
  --prefix data \
  --username $USERNAME \
  --password $PASSWORD \
  --address minio.example.com:9000

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. The server will reject the request with a foreign key constraint error. 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 us-east-1 --apiCode s3 \
  --bucket shared-bucket --prefix prod

# Staging block store (same bucket, different prefix)
configure.flexfs create block-store \
  --providerCode aws --regionCode us-east-1 --apiCode s3 \
  --bucket shared-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