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 signing key credentials 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 <bucket> \
  --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 signing key credentials

OCI API key authentication requires a JSON-encoded set of identity fields as the username and a PEM-encoded private key as the password (--username and --password in configure.flexfs, or --blockUser and --blockPass in free.flexfs init creds for Community).

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:

• Username: 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"
  }

• Password: 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 the password 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. For mount clients, the metadata server obtains these credentials on its host and passes them on, so the dynamic group must include the metadata server and any proxy server instances.

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='<bucket>'
Allow dynamic-group flexfs-instances to read buckets in compartment <compartment-name> where target.bucket.name='<bucket>'

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, in any realm the bundled OCI SDK knows, including government realms.

Set --address (--blockAddr on free.flexfs init creds for Community) to override it for a Dedicated Region or Cloud@Customer deployment, a private endpoint, or a region newer than the bundled SDK:

configure.flexfs update block-store <id> \
  --address <endpoint-host>

A value with no scheme is assumed to be https.

The OCI S3 compatibility endpoint (<namespace>.compat.objectstorage.<region>.oraclecloud.com) is reached only through the s3 block API. With --apiCode oci, configure.flexfs rejects such an address with 400: invalid address, and Community logs a warning and uses the default endpoint instead.

Block store configuration

When creating a block store with configure.flexfs (Enterprise), set both --providerCode and --apiCode to oci, --regionCode to your OCI region identifier (e.g. us-ashburn-1), and --bucket/--namespace to your OCI bucket name and Object Storage namespace. Pass the JSON identity string as --username and the PEM private key contents as --password, as described under API signing key credentials above — or leave both empty for instance principal authentication. The installer instead asks for the user OCID, tenancy OCID, API key fingerprint, and the path to the private key file, and builds both values itself. For the full field list with types and defaults, see Block Store Fields in the configure.flexfs CLI reference.

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

Community edition sets the same fields on free.flexfs init creds, with --provider, --region and --api in place of the three code flags:

free.flexfs init creds \
  --provider oci \
  --region <region> \
  --api oci \
  --bucket <bucket> \
  --namespace <namespace> \
  --prefix <prefix> \
  --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, so set --namespace on every OCI block store.