How to access Edge Storage using the S3 protocol

Azion Edge Storage offers compatibility with the S3 protocol through credentials. When you create a credential for any bucket that you own, you’ll get an access key and a secret key to set up permissions for operations. Access to your bucket through the S3 protocol will be verified using the credential.

The S3 protocol allows you to access buckets and objects using an Edge Storage URL. This configuration facilitates file operations through command line interface (CLI) tools, such as s3cmd, database services, or functions.

Create a credential via API

Run the following POST request in your terminal, replacing [TOKEN VALUE] with your personal token:

curl --location 'https://api.azion.com/v4/storage/s3-credentials' \
--header 'Accept: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-s3-credential",
    "capabilities": [
        "listAllBucketNames",
        "listBuckets",
        "listFiles",
        "readFiles",
        "writeFiles",
        "deleteFiles"
    ],
    "bucket": "<bucket_name>",
    "expiration_date": "<datetime>"
}'

Key	Description
`name`	Defines a string value as the name of the credential
`capabilities`	Accepts a list of capabilities to allow the execution of operations
`bucket`	Optional. Restricts the use of the credential to the specified bucket only
`expiration_date`	Sets the time for the credential to expire. The datetime format must be in UTC ISO 8601 standard: `YYYY-MM-DDT00:00:00Z`

You should receive a response similar to this:

{
    "state": "executed",
    "data": {
        "name": "my-s3-credential",
        "access_key": "<s3_credential_access_key>",
        "secret_key": "<s3_credential_secret_key>", // this value can no longer be accessed in future requests
        "capabilities": [
            "listAllBucketNames",
            "listBuckets",
            "listFiles",
            "readFiles",
            "writeFiles",
            "deleteFiles"
        ],
        "bucket": "<bucket_name>",
        "expiration_date": "<datetime>",
        "created_at": "<datetime>"
    }
}

Copy the values of the access_key and secret_key to set up access thorugh the S3 protocol.

Configure access to the bucket through s3cmd

s3cmd is a command line interface (CLI) tool for managing S3 and other cloud storage services. It can be used to manage objects on Edge Storage and other S3-compatible storage services.

To use s3cmd to manage your Edge Storage bucket, follow these steps:

Download and install s3cmd package through the official website.
Make sure s3cmd is added to your system’s PATH.
Run s3cmd --configure and enter the access key and secret key.
Enter the default region for the Edge Storage region: us-east.
Enter the endpoint URL for Edge Storage: s3.us-east-005.azionstorage.net.
Use the default DNS template: %(bucket).s3.us-east-005.azionstorage.net.
Inform an encryption password and a path to GPG program if needed.

Activate the HTTPS protocol by typing true.
Inform HTTP proxy servers if needed.
Press y to test access.

If your access and secret keys are correct, you should get the following success message:

Please wait, attempting to list all buckets...
Success. Your access key and secret key worked fine :-)

You can save your settings into an .s3cfg file if needed and modify them again using s3cmd --configure. Run the command s3cmd --help to see all available commands.

s3cmd commands to manage objects on Edge Storage

Once you’ve configured access to the bucket through s3cmd, you can execute operations to manage your objects on Edge Storage using the available commands.

Scope	Description
`s3cmd ls`	List all your buckets
`s3cmd mb s3://my-new-bucket-name`	Create a new bucket. Bucket names must be unique and best practices for naming buckets include specifying what types of objects are stored and the type of permissions for the objects
`s3cmd ls s3://my-new-bucket-name`	List the contents of the bucket
`s3cmd put file.xml s3://my-new-bucket-name/file.xml`	Upload a file into the bucket
`s3cmd get s3://my-new-bucket-name/file.xml file-2.xml`	Retrieve the file back and verify that it hasn’t been corrupted
`s3cmd del s3://my-new-bucket-name/addrbook.xml s3://my-new-bucket-name/storage.jpg`	Delete the object
`s3cmd rb s3://logix.cz-test`	Remove the bucket. Only empty buckets can be removed

For more details on S3 protocol and s3cmd commands, check the official documentation. You can also visit the Edge Storage reference.

Contributors