Mounts a cloud bucket to your container. Currently supports AWS S3, Cloudflare R2, and Google Cloud Storage buckets.
S3 buckets are mounted using AWS S3 Mountpoint. S3 mounts are optimized for reading large files sequentially. It does not support every file operation; consult the AWS S3 Mountpoint documentation for more information.
Constructor
modal.CloudBucketMount(
bucket_name: str,
bucket_endpoint_url: Optional[str] = None,
key_prefix: Optional[str] = None,
secret: Optional[Secret] = None,
oidc_auth_role_arn: Optional[str] = None,
read_only: bool = False,
requester_pays: bool = False,
force_path_style: bool = False,
)
Name of the cloud bucket.
Endpoint URL for the bucket (required for R2 and GCS).
Prefix to add to all object paths. Must end with ’/’.
Secret containing credentials. Required for private buckets.
Role ARN for OIDC authentication.
Enable requester pays (requires credentials).
AWS S3 usage
import subprocess
import modal
app = modal.App()
secret = modal.Secret.from_name(
"aws-secret",
required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
# Note: providing AWS_REGION can help when automatic detection fails
)
@app.function(
volumes={
"/my-mount": modal.CloudBucketMount(
bucket_name="s3-bucket-name",
secret=secret,
read_only=True
)
}
)
def f():
subprocess.run(["ls", "/my-mount"], check=True)
Cloudflare R2 usage
Cloudflare R2 is S3-compatible but requires the bucket_endpoint_url parameter.
import subprocess
import modal
app = modal.App()
secret = modal.Secret.from_name(
"r2-secret",
required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
)
@app.function(
volumes={
"/my-mount": modal.CloudBucketMount(
bucket_name="my-r2-bucket",
bucket_endpoint_url="https://<ACCOUNT ID>.r2.cloudflarestorage.com",
secret=secret,
read_only=True
)
}
)
def f():
subprocess.run(["ls", "/my-mount"], check=True)
Google Cloud Storage usage
Google Cloud Storage (GCS) is S3-compatible. GCS Buckets require a secret with Google-specific key names populated with a HMAC key.
import subprocess
import modal
app = modal.App()
gcp_hmac_secret = modal.Secret.from_name(
"gcp-secret",
required_keys=["GOOGLE_ACCESS_KEY_ID", "GOOGLE_ACCESS_KEY_SECRET"]
)
@app.function(
volumes={
"/my-mount": modal.CloudBucketMount(
bucket_name="my-gcs-bucket",
bucket_endpoint_url="https://storage.googleapis.com",
secret=gcp_hmac_secret,
)
}
)
def f():
subprocess.run(["ls", "/my-mount"], check=True)
Notes
- For private buckets, the secret must contain
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
- For publicly accessible buckets, the secret is unnecessary and can be omitted
- For GCS, use
GOOGLE_ACCESS_KEY_ID and GOOGLE_ACCESS_KEY_SECRET instead
- If
requester_pays is True, credentials are required