Configure S3-compatible access for FastAPI

Summary

Configure S3-compatible access for a FastAPI app on Ample. Create a bucket with ample bucket create, pass its endpoint, region, bucket name and keys as encrypted environment variables, and use boto3 with Config(s3={'addressing_style': 'path'}). The app writes and reads objects through the S3-compatible endpoint; the bucket stays private.

Infrastructure requirements

• Verified compute (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
• Verified S3-compatible object storage (Buckets are S3-compatible with issued credentials; PutObject and GetObject are verified by canary. Other S3 operations are not verified.)

Prerequisites

• An S3 client in the app (boto3 with Config(s3={'addressing_style': 'path'})) reading S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY
• A bucket created with ample bucket create <name> and its credentials from ample bucket credentials <name>
• An Ample account token with servers:write and buckets:read

Exact tested configuration

• template: python-3.12
• runtime: python
• size: s-1vcpu-1gb
• install: python3 -m pip install --target .ample/python -r requirements.txt
• start: PYTHONPATH=.ample/python:${PYTHONPATH:-} python3 run.py

Steps

1. Create the bucket. Create it once and keep the issued credentials out of the repository.

   ample bucket create --name <bucket-name>

2. Configure the client with path-style addressing. Use boto3 with Config(s3={'addressing_style': 'path'}); virtual-host addressing is not verified.
3. Deploy with the credentials as encrypted env. Pass the five S3_* variables with --env; they are stored encrypted and reused on redeploys.

   ample deploy . --name <app-name> --public --start "python3 run.py" --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...

4. Test through the app. Expose a route (/storage) that writes then reads an object and reports s3=ok.
5. Verify. Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

   ample logs <deployment_id> --kind build

Tested examples

• FastAPI bucket canary (tests/deploy-canaries/fastapi-bucket-uploads): Write and read an object with the injected credentials.

Success checks

• object write and read succeed (/storage on the live URL, expect s3=ok)

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• PutObject and GetObject with path-style addressing are verified; multipart upload, listing, presigned URLs and lifecycle rules are not verified.
• Bucket credentials are passed as encrypted environment variables; the catalog never creates the bucket for you (use ample bucket create).
• Storage is allocation-priced per bucket quota and capped by the account plan; the estimate below covers compute only.

Cost estimate

Estimated 5.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).

• app server x1 s-1vcpu-1gb: 5.00 USD

Compute only. Buckets are allocation-priced per quota and capped by the plan; see ample usage.

Verification evidence

• canary_run on 2026-09-20T01:13:26Z at revision cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5): FastAPI app using boto3 (path-style addressing) with injected bucket credentials: put_object then get_object returned s3=ok. (expires 2027-03-19T01:13:26Z)
• canary_run on 2026-09-20T01:13:26Z at revision cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5): ample bucket create issued credentials; PutObject and GetObject succeeded through the public S3 endpoint; publish exposed the object through the CDN host with an ETag; unpublish and delete cleaned up. (expires 2027-03-19T01:13:26Z)

Last verified: 2026-09-20T01:13:26Z

Execution binding

MCP tool ample_deploy (registry mcp:ample_deploy), schema hash 876465fce906da0c observed 2026-09-20T01:55:48.667900+00:00 at revision 199ff1dfd526, binding state current, required scopes: servers:write, buckets:read.