​
Object Storage Guide

Uncloud provides S3-compatible object storage for storing files, images, backups, and any unstructured data.

​
Prerequisites

  • Object storage component installed (via Admin Setup)
  • Storage configuration in config.yaml

​
Check Storage Status

curl http://localhost:8080/api/v1/storage/status

{
  "available": true,
  "endpoint": "http://s3.cluster.local:9000",
  "region": "us-east-1"
}

​
Create a Bucket

curl -X POST http://localhost:8080/api/v1/storage/buckets \
  -H "Content-Type: application/json" \
  -d '{"name": "my-assets"}'
Bucket names must be DNS-compatible: lowercase letters, numbers, and hyphens only.

​
Upload Files

​
Via API

curl -X POST http://localhost:8080/api/v1/storage/buckets/my-assets/objects \
  -F "file=@/path/to/photo.jpg" \
  -F "key=images/photo.jpg"

​
Via Pre-signed URL

Generate a temporary upload URL: 
curl -X POST http://localhost:8080/api/v1/storage/buckets/my-assets/objects/presign \
  -H "Content-Type: application/json" \
  -d '{
    "key": "uploads/document.pdf",
    "method": "PUT",
    "expires_in": 3600
  }'
Then upload directly: 
curl -X PUT "<presigned-url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

​
Browse Objects

# List all objects
curl http://localhost:8080/api/v1/storage/buckets/my-assets/objects

# Filter by prefix
curl "http://localhost:8080/api/v1/storage/buckets/my-assets/objects?prefix=images/"

​
Download Files

Generate a pre-signed download URL: 
curl -X POST http://localhost:8080/api/v1/storage/buckets/my-assets/objects/presign \
  -H "Content-Type: application/json" \
  -d '{
    "key": "images/photo.jpg",
    "method": "GET",
    "expires_in": 3600
  }'

​
Delete Objects

curl -X DELETE http://localhost:8080/api/v1/storage/buckets/my-assets/objects \
  -H "Content-Type: application/json" \
  -d '{"key": "images/old-photo.jpg"}'

​
Delete a Bucket

curl -X DELETE http://localhost:8080/api/v1/storage/buckets/my-assets
The bucket must be empty before deletion.

​
Using S3 Clients

The storage endpoint is S3-compatible. Use any AWS SDK or CLI:

​
AWS CLI

# Configure credentials
aws configure set aws_access_key_id YOUR_ACCESS_KEY
aws configure set aws_secret_access_key YOUR_SECRET_KEY

# List buckets
aws s3 ls --endpoint-url http://s3.cluster.local:9000

# Upload a file
aws s3 cp photo.jpg s3://my-assets/images/ \
  --endpoint-url http://s3.cluster.local:9000

# Sync a directory
aws s3 sync ./build s3://my-assets/static/ \
  --endpoint-url http://s3.cluster.local:9000

​
Python (boto3)

import boto3

s3 = boto3.client('s3',
    endpoint_url='http://s3.cluster.local:9000',
    aws_access_key_id='YOUR_ACCESS_KEY',
    aws_secret_access_key='YOUR_SECRET_KEY'
)

# Upload
s3.upload_file('photo.jpg', 'my-assets', 'images/photo.jpg')

# List objects
response = s3.list_objects_v2(Bucket='my-assets', Prefix='images/')
for obj in response.get('Contents', []):
    print(obj['Key'])

​
Next Steps