Oracle Cloud Infrastructure Documentation

Persistent File Storage for Hosted Applications

Retain application files across container restarts and redeployments with service-managed File Storage in OCI Generative AI.

Attach File Storage to a hosted application and specify an absolute container path where the service mounts it. Files written to that path remain available across restarts and redeployments. Use persistent files for model artifacts, intermediate results, checkpoints, and application state that your workload needs across these events.

Each application receives a separate file system, including when applications use the same managed storage resource. Reusing a storage configuration doesn't share files between applications. Applications access their own files through the configured mount path.

Important

Persistent file storage supports one replica in this release. Set the application's minimum and maximum replica counts to 1.
  • An application can have one File Storage mount and one attached storage resource of each storage type.
  • Each file storage attachment has a fixed 50 GB quota (50,000,000,000 bytes).
  • You must specify the mount path when you create the application. You can't change it afterward.
  • Files written outside the mount path don't gain persistence from this attachment. Use /tmp for temporary files.

You can configure File Storage through the Console or the Generative AI API. For the Console workflow, see Storage.

Selecting a Mount Path

The recommended mount path is /mnt/persistent/data. You can specify another valid path, such as /data, /app/storage, or /mount. Configure your application to read and write persistent files at the selected path.

The path must meet the following requirements:

  • Use an absolute path in canonical UTF-8 format, with at most 4,096 bytes in total and 255 bytes per path component.
  • Don't include empty components, . or .. components, control characters, or a trailing slash.
  • Don't use the root path (/) or a path that overlaps another container volume mount.
  • Don't use a path that overlaps a reserved system directory or platform mount.

The following paths are reserved:

  • /bin, /boot, /dev, /etc, /lib, /lib64, /proc, /sbin, and /sys
  • /run, /tmp, and /var/run
  • /usr/bin, /usr/sbin, /usr/lib, and /usr/lib64
  • /usr/local/bin, /usr/local/sbin, /usr/local/lib, and /usr/local/lib64

File Storage requires an explicit mount path. Generated mount paths and environmentVariableKey configuration aren't supported for this storage type.

Creating File Storage with the API

Ensure that you have permission to create managed storage and hosted applications. See API-Level Permissions for Application Storage and Permissions for Deploying Applications.

Configure the application with minimum and maximum replica counts of 1. Persistent file storage supports one replica in this release.

Use the Generative AI control plane API to create a managed storage resource, then reference it in the application's storage configuration.

  1. Create the storage resource with CreateHostedApplicationStorage.

    Send a POST request to /20231130/hostedApplicationStorages with a CreateHostedApplicationStorageDetails request body. Supply the compartment OCID, a display name, and FILE_STORAGE as the storage type.

    {
  "compartmentId": "<compartment-ocid>",
  "displayName": "application-files",
  "storageType": "FILE_STORAGE"
}

    You can also supply an optional description, defined tags, and free-form tags.

  2. Record the OCID of the created HostedApplicationStorage resource. If you're using existing File Storage, use its managed storage resource OCID.
  3. Include a File Storage entry in storageConfigs when you create the hosted application.

    In the StorageConfig entry, set storageId to the managed storage resource OCID and mountPath to the selected container path. Omit environmentVariableKey.

    The following fragment shows only the attachment configuration. Include the other required properties for the application creation operation that you use.

    {
  "storageConfigs": [
    {
      "storageId": "<hosted-application-storage-ocid>",
      "mountPath": "/mnt/persistent/data"
    }
  ]
}

    The application supports up to four storage configurations, with one attachment per storage type. For ADB, PostgreSQL, and cache storage, supply environmentVariableKey and omit mountPath.

  4. Check the application's returned storageConfigs[].fileStorageDetails.mountState before using the mount.

    READY means that the active application revision can use the configured mount path. See Checking Attachment Status.

Checking Attachment Status

The application's storageConfigs entry includes fileStorageDetails with the attachment status. See FileStorageDetails in the API reference. These fields report service-managed state.

File Storage attachment status
FieldDescription
mountStateREADY means that the service has reconciled the attachment and the active application revision can use the configured mount path. Other values are CREATING, NEEDS_ATTENTION, DELETING, DELETED, and FAILED. In these states, the attachment doesn't fall back to local storage or a direct NFS mount.
lifecycleDetailsWhen provided, describes an attachment or mount failure and the action you can take.
quotaLimitInGigabytesThe fixed attachment quota of 50 GB.

Checking Storage Usage

Use the usage fields in fileStorageDetails to review the most recently observed consumption. Usage values are advisory. File Storage enforces the hard quota.

File Storage usage
FieldDescription
usageStateCURRENT indicates a current sample. STALE indicates a sample older than the service's freshness target. UNAVAILABLE indicates that no usage sample is available.
usageInBytesThe most recently observed usage in bytes.
usagePercentageThe most recently observed percentage of the 50 GB quota in use.
timeUsageObservedThe time of the usage observation, in RFC 3339 format.

The usage values and observation time are returned only when usageState is CURRENT or STALE. When it's UNAVAILABLE, these fields are omitted. Missing values don't mean that no storage is in use.