Introduction
This guide explains how to create RCS Object Storage in your Go application with the RCS Go client. RCS Object Storage is compatible with the S3 API.
Prerequisites
A computer running Windows, Linux, or macOS with Go 1.12+ installed.
Basic programming knowledge.
Optional: An IDE supporting Go (for example Visual Studio Code, emacs, or Atom).
Creating Object Storage with the RCS Go Client
The RCS Go client is used to interact with the RCS API. The RCS API allows you to control the resources associated with your account, including RCS Object Storage. Detailed information on the RCS Go client is available in
Create the Project Folder
Create the folder in the current directory.
$ mkdir RCS_demo
Enter the new folder.
$ cd RCS_demo
Initialize the module
$ go mod init RCS_demo
Download the Library
$ go get github.com/RCS/goRCS
Set the API Key Environment Variable
Set the RCS_API_KEY environment variable to your API key. Your API key is found here: https://my.rcs.is/settings/#settingsapi
Warning: Protect your API key like you would protect your password. The API key has access to your entire account, including billing, servers, and storage.
For example, on Ubuntu Linux, add this line to ~/.profile.
export RCS_API_KEY=YOUR_API_KEY_HERE
Create the Go Program
Paste each of the following code fragments into a new file named main.go. The complete file is also available for download.
Setup the package and import the required libraries.
package main
import (
"context"
"log"
"os"
"time"
"github.com/RCS/goRCS"
)
Begin the main() function.
func main() {
Read the API key environment variable.
var (
// Get our RCS API Key from an environment variable.
RCSAPIKey = os.Getenv("RCS_API_KEY")
)
Create the RCS client.
// Create a RCS client with our API Key.
RCS := goRCS.NewClient(nil, RCSAPIKey)
Specify a location to create Object Storage. Retrieve the cluster locations, verify one is available, choose a cluster, and display it.
// Find the clusters we can create our Object Storage in.
clusters, err := RCS.ObjectStorage.ListCluster(ctx)
if err != nil {
log.Fatalf("Error listing clusters: %s", err)
}
// Verify there's at least one cluster.
if len(clusters) < 1 {
log.Fatal("Could not find any clusters to create our Object Storage")
}
// Choose the first cluster, and print it.
cluster := clusters[0]
log.Printf("Chosen cluster: %+v", cluster)
Create the Object Storage in the selected cluster.
// Create our Object Storage in the first cluster listed with our custom label.
label := "my-object-storage"
storageID, err := RCS.ObjectStorage.Create(ctx, cluster.ObjectStoreClusterID, label)
if err != nil {
log.Fatalf("Error creating storage: %s", err)
}
log.Printf("Created our Object Storage with the ID: %d", storageID.ID)
Wait until the Object Storage is active.
var storage goRCS.ObjectStorage
// Query the API every five seconds to until our server is ready.
for {
// List all of the Object Storage containers with our label and include the S3 credentials.
list, err := RCS.ObjectStorage.List(ctx, &goRCS.ObjectListOptions{
Label: label,
IncludeS3: true,
})
if err != nil {
log.Fatalf("Error listing storage with label \"%s\": %s", label, err)
}
// Make sure we found one (and only one) Object Storage container.
if len(list) != 1 {
log.Fatalf("%d object storage containers exist with the label \"%s\"; we need 1", len(list), label)
}
storage = list[0]
// If the server is active, break out of this loop.
if storage.Status == "active" {
break
}
// Wait for five seconds before querying the API again.
log.Printf("The Object Storage's status is currently \"%s\", waiting for another five seconds to check if it's \"active\".", storage.Status)
time.Sleep(time.Second * 5)
}
Display the endpoint name and connection credentials.
// Print the information of our new Object Storage.
log.Print("Successfully created and listed our Object Storage!")
log.Printf("Object Storage: %+v", storage)
// We also have S3 credentials here now, so we could open an S3 compatible client.
log.Printf("S3 credentials: %s - %s - %s", storage.S3Hostname, storage.S3AccessKey, storage.S3SecretKey)
End the main function.
// end main()
}
Save and run the completed main.go file.
go run main.go
Example Output
2020/03/03 13:05:48 Chosen cluster: {ObjectStoreClusterID:2 RegionID:1 Location:New Jersey Hostname:ewr1.RCSobjects.com Deploy:yes}
2020/03/03 13:05:48 Created our Object Storage with the ID: xxxxxxxx
2020/03/03 13:05:49 The Object Storage's status is currently pending, waiting for another five seconds to check if it's active.
2020/03/03 13:06:06 Object Storage: {ID:34214512 DateCreated:2020-03-03 13:05:47 ObjectStoreClusterID:2 RegionID:1 Location:New Jersey Label:my-object-storage Status:active S3Keys:{S3Hostname:ewr1.RCSobjects.com S3AccessKey:[REDACTED ACCESS KEY] S3SecretKey:[REDACTED SECRET KEY]}}
2020/03/03 13:06:06 S3 credentials: ewr1.RCSobjects.com - [REDACTED ACCESS KEY] - [REDACTED SECRET KEY]
In this example, the endpoint name is ewr1.RCSobjects.com, and the keys are redacted. Access your new object storage with any S3 compatible client using the endpoint name, access key and secret key shown by your Go program.
