Oracle Cloud Infrastructure

FlexFS supports Oracle Cloud Infrastructure (OCI) Object Storage as a block store backend using the OCI Go SDK. Authentication is handled via API key credentials (customer secret keys) or instance principal authentication.

Namespace and bucket

Every OCI tenancy has a unique Object Storage namespace. Retrieve it with:

oci os ns get

Create a bucket for flexFS block storage:

oci os bucket create \
  --compartment-id <compartment-ocid> \
  --name my-flexfs-blocks \
  --namespace <namespace>

Recommended bucket settings

• Storage tier: Standard. Archive is not suitable for active block storage.
• Emit Object Events: Not required.
• Versioning: Not required.
• Auto-tiering: Not recommended. FlexFS block access patterns are managed internally.

Authentication

API key credentials (customer secret keys)

OCI API key authentication requires a JSON-encoded set of identity fields as the blockUser and a PEM-encoded private key as the blockPass.

First, generate an API signing key:

# Generate the private key
openssl genrsa -out oci_api_key.pem 2048

# Generate the public key
openssl rsa -pubout -in oci_api_key.pem -out oci_api_key_public.pem

# Get the key fingerprint
openssl rsa -pubout -outform DER -in oci_api_key.pem | openssl md5 -c

Upload the public key to your OCI user:

oci iam user api-key upload \
  --user-id <user-ocid> \
  --key-file oci_api_key_public.pem

When configuring the flexFS block store credentials:

• blockUser: A JSON string containing the OCI identity fields:

  {
    "tenancy_ocid": "ocid1.tenancy.oc1..aaaa...",
    "user_ocid": "ocid1.user.oc1..aaaa...",
    "region": "us-ashburn-1",
    "key_id": "ocid1.tenancy.oc1..aaaa.../ocid1.user.oc1..aaaa.../aa:bb:cc:...",
    "key_fingerprint": "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"
  }

• blockPass: The PEM-encoded private key contents

Note

The key_id field follows the OCI format: tenancy_ocid/user_ocid/fingerprint. The key_fingerprint is the MD5 fingerprint of the public key.

Instance principal authentication

When blockPass is left empty, flexFS attempts to authenticate using OCI instance principal credentials. This is available on OCI Compute instances that belong to a dynamic group with the appropriate IAM policies.

Create a dynamic group matching your compute instances:

All {instance.compartment.id = '<compartment-ocid>'}

Create an IAM policy granting Object Storage access:

Allow dynamic-group flexfs-instances to manage objects in compartment <compartment-name> where target.bucket.name='my-flexfs-blocks'
Allow dynamic-group flexfs-instances to read buckets in compartment <compartment-name> where target.bucket.name='my-flexfs-blocks'

If instance principal credentials are unavailable, flexFS falls back to the OCI default configuration provider (which reads from ~/.oci/config).

Instance principal authentication is the recommended method for production deployments on OCI.

Custom endpoint

OCI Object Storage endpoints are region-specific. By default flexFS uses the standard endpoint for the region reported by the configured credentials, which covers the commercial realm.

Set --address to override it. This is what reaches a government or sovereign realm, a Dedicated Region or Cloud@Customer deployment, a private endpoint, or a region newer than the bundled SDK’s region map:

configure.flexfs update block-store <id> \
  --address objectstorage.us-langley-1.oraclegovcloud.com

A value with no scheme is assumed to be https.

Block store configuration

When creating a block store via configure.flexfs (Enterprise) or the installer, provide:

Field	Flag	Value
Provider	--providerCode	oci
Region	--regionCode	OCI region identifier (e.g. us-ashburn-1)
API	--apiCode	oci
Bucket	--bucket	Your OCI bucket name
Namespace	--namespace	Your OCI Object Storage namespace
Prefix	--prefix	Optional key prefix
blockUser	--username	JSON identity string (or leave empty for instance principal)
blockPass	--password	PEM private key contents (or leave empty for instance principal)

configure.flexfs create block-store \
  --providerCode oci \
  --regionCode us-ashburn-1 \
  --apiCode oci \
  --bucket my-flexfs-blocks \
  --namespace my-tenancy-namespace \
  --prefix flexfs

Community edition takes the same two flags on free.flexfs init creds:

free.flexfs init creds \
  --provider oci \
  --region us-ashburn-1 \
  --api oci \
  --bucket my-flexfs-blocks \
  --namespace my-tenancy-namespace \
  --prefix flexfs \
  --metaAddr meta.example.com:443

Tip

OCI Object Storage uses the concept of a namespace in addition to the bucket name. The namespace is unique to your tenancy and is required for all OCI Object Storage operations. FlexFS passes the namespace to the OCI SDK on every GetObject and PutObject call.