Skip to content
flexFS

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

Section titled “Namespace and bucket”

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

Terminal window
oci os ns get

Create a bucket for flexFS block storage:

Terminal window
oci os bucket create \
  --compartment-id <compartment-ocid> \
  --name <bucket> \
  --namespace <namespace>
Section titled “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

Section titled “Authentication”

API signing key credentials

Section titled “API signing key credentials”

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:

Terminal window
# 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:

Terminal window
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

Instance principal authentication

Section titled “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='<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

Section titled “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:

Terminal window
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

Section titled “Block store configuration”

When creating a block store via configure.flexfs (Enterprise) or the installer, 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 (blockUser) and the PEM private key contents as --password (blockPass), as described under API signing key credentials above — or leave both empty for instance principal authentication. For the full field list with types and defaults, see Block Store Fields in the configure.flexfs CLI reference.

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

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

Terminal window
free.flexfs init creds \
  --provider oci \
  --region <region> \
  --api oci \
  --bucket <bucket> \
  --namespace <namespace> \
  --prefix <prefix> \
  --metaAddr meta.example.com:443