This guide demonstrate the basics of Exoscale’s Simple Object Storage (SOS).

With object storage, you can store, distribute and manage large quantities of files (or objects). Example uses range from simple backups to complex media delivery.

You can store almost anything in SOS: assets, backups, email attachments, videos, pictures and anything else you may imagine.

Your data will stay in the zone in which you store it. Exoscale will never move data on your behalf. For example, if you first upload data to Simple Object Storage in Geneva, then your data is kept in Switzerland, under Swiss privacy regulations. Whichever the initial location, it is replicated in that same location in at least three physical distinct copies to ensure maximum safety.

All the actions we will demonstrate through the command line can also be performed through our CLI or the Portal, although the real power of SOS is in the tools you script, and in the clients you may use in your application.

S3 Compatibility

SOS is S3 compatible, so it works with most object storage clients and provides library access from a host of languages. You can drop in from other services and you will not be locked in. Most of the time, a change of API credentials and endpoint allows you to switch to our service.

Here are a few clients and tools that you can use:

We will use aws s3 cli in this guide.

Setup

This guide assumes you never used the aws s3 cli. If you have used the aws s3 cli beforew, take a look at the $HOME/.aws/credentials example below, drop in your Exoscale’s API Key and API Secret and you can use SOS.

First, install the aws cli utility following the recommended steps in AWS page here: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

Then create a file at the location ~/.aws/credentials in your home directory. Copy and paste the following configuration template:

[default]
addressing_style = path
region=ch-dk-2
aws_access_key_id = $EXO_SOS_KEY
aws_secret_access_key = $EXO_SOS_SECRET
output = json
endpoint_url = https://sos-ch-dk-2.exo.io

Replace region and the endpoint_url with the zone your bucket belongs to. For example, for a bucket deployed on the ch-gva-2 zone:

region=ch-gva-2
endpoint_url=https://sos-ch-gva-2.exo.io

Replace $EXO_SOS_KEY and $EXO_SOS_SECRET with your API Key and API Secret. You can choose to use your User Keys or a specific IAM API key.

Your first Bucket

We need to create a container for all of our objects, which is called a bucket.

aws s3 mb s3://my-new-bucket

This creates a bucket called my-new-bucket.

Bucket names are unique across the entire platform. You may encounter an error creating my-new-bucket if the name is already taken.

Why are bucket names unique? Buckets and their content can be accessed under https://sos-ch-dk-2.exo.io/my-new-bucket/ or https://my-new-bucket.sos-ch-dk-2.exo.io. Buckets become subdomains and prefixed URLs under the sos-ch-dk-2.exo.io domain, so names have to be unique.

This does not mean objects are publicly accessible, however. You can define precise access control through IAM Keys or ACLs, and uploaded objects are private by default.

You can check your bucket has been created by listing your buckets:

aws s3 ls

Uploading and downloading assets

Now choose file on your computer and upload it to your bucket:

aws s3 cp picture.jpg s3://my-new-bucket

Check your file was uploaded successfully:

aws s3 ls s3://my-new-bucket

You can also verify the presence of your file in the Portal. Select the Storage section from the main navigation on the left. You should see your my-new-bucket listed here. Select the bucket and you will find your file.

You can try to upload more files in the Portal by drag-and-drop.

To get your files:

aws s3 cp s3://my-new-bucket/picture.jpg picture_download.jpg

Getting further

Get further with SOS and the S3 compatibility coverage by going over the overview section