OSS mount feature (Invitational Preview)

MaxFrame's OSS mount function maps an OSS bucket to a local file system path inside your distributed task. Once mounted, your code accesses OSS data through standard POSIX file APIs (open, read, write) — no OSS SDK calls required.

This feature is in Invitational Preview. Requires MaxFrame SDK 2.4.0 or later.

Use cases

Large-scale data processing: Run offline batch jobs that read from and write to OSS without managing SDK credentials in task code.
Data preprocessing: Read raw data from OSS, clean and transform it, then write results to MaxCompute.
Hybrid storage: Keep data in OSS while processing it with MaxFrame distributed tasks.

How it works

Apply the @with_fs_mount decorator to your task function. MaxFrame mounts the specified OSS path to a local directory before the function runs and unmounts it automatically when the function exits — even if it exits with an error.

from maxframe.udf import with_fs_mount, with_running_options
import pandas as pd

@with_running_options(engine="dpe", cpu=2, memory=8)
@with_fs_mount(
    path="oss://oss-cn-shanghai-internal.aliyuncs.com/bigdata-bucket/preprocessed/",
    mount_path="/mnt/data",
    storage_options={"role_arn": "acs:ram::123456:role/DataAccess"}
)
def etl_job():
    df = pd.read_csv("/mnt/data/2025-*.csv")
    # Distributed processing...

The mount is scoped to a single function invocation. After etl_job finishes, /mnt/data is unmounted and no longer accessible.

Limitations

Constraint	Detail
Mount scope	Scoped to one function invocation. The mount is automatically unmounted in an exception-safe manner after the function exits.
Path uniqueness	Each mount target is independent. Avoid path conflicts across `@with_fs_mount` decorators.
Permissions	The task user must have read and write permission on the mount directory.
Preview availability	Feature is in Invitational Preview. Contact your account team to enable access.

Parameters

`path`

The remote OSS path to mount.

Format: scheme://<endpoint>/<bucket>/<object_prefix>

Component	Description	Example
`scheme`	Protocol type (OSS)	`oss`
`endpoint`	OSS endpoint for the region	`oss-cn-shanghai-internal.aliyuncs.com`
`bucket`	Bucket name	`bigdata-bucket`
`object_prefix`	Path prefix within the bucket	`preprocessed/`

Example:

path = "oss://oss-cn-shanghai-internal.aliyuncs.com/maxframe-test/oss_data"

`mount_path`

The local path inside your task where the OSS bucket is accessible.

MaxFrame creates this directory automatically. The path is valid only for the duration of the decorated function.

Example:

mount_path = "/mnt/oss_data"

`storage_options`

Authentication configuration for OSS access. Use a RAM role to avoid embedding long-term AccessKey pairs in your task code.

Get the RAM role ARN:

Log on to the Resource Access Management (RAM) console.
In the left navigation pane, choose Identities > Roles.
Open the target role. The ARN appears in the Basic Information section.

Example:

storage_options = {
    "role_arn": "acs:ram::xxxxxxxx:role/MaxFrameAccessRole"
}

Scope the RAM policy to the minimum permissions needed. The following policy grants read-only access to a specific object prefix:

{
    "Statement": [
        {
            "Action": "oss:GetObject",
            "Effect": "Allow",
            "Resource": "acs:oss:*:*:maxframe-***-poc/oss_data/*"
        }
    ],
    "Version": "1"
}

Examples

Load and process CSV files from OSS

import pandas as pd
from maxframe.udf import with_fs_mount, with_running_options

@with_running_options(engine="dpe", cpu=2, memory=8)
@with_fs_mount(
    path="oss://oss-cn-shanghai-internal.aliyuncs.com/bigdata-bucket/preprocessed/",
    mount_path="/mnt/data",
    storage_options={"role_arn": "acs:ram::123456:role/DataAccess"}
)
def etl_job():
    df = pd.read_csv("/mnt/data/2025-*.csv")
    # Distributed processing...

Load a model checkpoint from OSS

from maxframe.udf import with_fs_mount, with_running_options

@with_running_options(engine="dpe", cpu=2, memory=8)
@with_fs_mount(
    path="oss://oss-cn-shanghai-internal.aliyuncs.com/model-registry/model_path",
    mount_path="/mnt/model_path",
    storage_options={"role_arn": "acs:ram::123456:role/ModelAccess"}
)
def resume_training():
    model = load_model("/mnt/model_path/model.pkl")
    # Model training...

What's next

For complete runnable examples and best practices, see OSS mounting and best practices.