API - evroc User Documentation

Environment setup

To access the evroc API you need to log in and setup your environment. The steps required are described in the IAM chapter.

This guide will describe how you can access the Object Storage programmatically via the S3 compatible API. This setup is suitable for configuring an existing S3 compatible client, or when writing your own code using an S3 compatible SDK.

Generate Credentials

A client requires credentials to access the Object Storage API. These credentials are used to prove the legitimacy of the requests sent by the client, conversely blocking any requests that does not have valid credentials.

NOTE: these credentials are secrets that should not be shared publicly. Take care to how you store and access your credentials!

This guide requires you to have the evroc CLI downloaded and for the CLI to be logged in to your evroc Organisation. For instructions on this please follow the Getting Started instructions

1. Create a Service Account

The credentials you are about to generate will be tied to a Service Account, which represents the client you want to give access to.

To create a new Service Account, use the evroc iam serviceaccount create command in the CLI. For example, to create a Service Account called sa-external, run:

evroc iam serviceaccount create sa-external

2. Create the bucket and set the Service Account as owner

To specify which Buckets your Service Account can access you need to configure the Service Account as an owner of this Bucket.

To create a new Bucket, here named my-bucket, with the newly created Service Account as an owner, run:

evroc storage bucket create my-bucket --owner ServiceAccount.sa-external

To configure an existing bucket, here named my-existing-bucket, with the newly created Service Account as an owner, run:

evroc storage bucket update my-existing-bucket --append --owner ServiceAccount.sa-external

3. Extract the Ccredentials

The Service Account will now have credentials tied to it that are authorized to access the Bucket. These credentials are given as a pair of an Access key and a Secret key. To see these credentials, run:

evroc storage bucket get-s3-credentials --name sa-external

The output of this command will print the credentials in an INI format. It should look like this:

$ evroc storage bucket get-s3-credentials --name sa-external
[sa-external]
aws_access_key_id = <ACCESS_KEY_ID>
aws_secret_access_key = <SECRET_ACCESS_KEY>

After your credentials have been successfully extracted, review your Secret Access Key and Access Key ID values.

You will also need to configure the endpoint in your S3 client to https://storage.services.evroc.cloud/

Configure Client

The Object Storage service exposes an S3 compatible API that will work with many existing clients and SDKs.

You need to configure this client to talk to the evroc API. The configuration interface might look different depending on your client. The configuration values you must set are:

The endpoint to https://storage.services.evroc.cloud/.
The region to sto-1.
The credentials to the credentials you generated in Generate Credentials.

Code Examples

This section provides some code snippets with examples of configured SDKs in different languages.

Python: AWS Boto3

import io
import boto3

bucket_name = "real-bucket"
access_key_id = '<ACCESS_KEY_ID>'
secret_access_key = '<SECRET_ACCESS_KEY>'

s3 = boto3.client('s3',
  endpoint_url = 'https://storage.services.evroc.cloud/',
  region = 'sto-1',
  aws_access_key_id = access_key_id,
  aws_secret_access_key = secret_access_key
)

# Upload/Update single file
s3.upload_fileobj(io.BytesIO(b"The quick brown fox"), Bucket=bucket_name, Key="thefox")

# Get object information
object_information = s3.head_object(Bucket=bucket_name, Key="thefox")

# List objects
objects = s3.list_objects(Bucket=bucket_name)

# Delete object
s3.delete_object(Bucket=bucket_name, Key="thefox")

Go: aws-sdk-go

package main

import (
        "context"
        "encoding/json"
        "fmt"
        "log"

        "github.com/aws/aws-sdk-go-v2/aws"
        "github.com/aws/aws-sdk-go-v2/config"
        "github.com/aws/aws-sdk-go-v2/credentials"
        "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
        var bucketName = "real-bucket"
        var accessKeyId = "<ACCESS_KEY_ID>"
        var accessKeySecret = "<SECRET_ACCESS_KEY>"

        resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
                return aws.Endpoint{
                    URL: "https://storage.services.evroc.cloud/",
                    HostnameImmutable: true,
                }, nil
        })

        cfg, err := config.LoadDefaultConfig(context.TODO(),
                config.WithEndpointResolverWithOptions(resolver),
                config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyId, accessKeySecret, "")),
                config.WithRegion("sto-1"),
        )
        if err != nil {
                log.Fatal(err)
        }

        client := s3.NewFromConfig(cfg)

        listObjectsOutput, err := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
                Bucket: &bucketName,
        })
        if err != nil {
                log.Fatal(err)
        }

        for _, object := range listObjectsOutput.Contents {
                obj, _ := json.MarshalIndent(object, "", "\t")
                fmt.Println(string(obj))
        }
}