# README

gridscale Go Client Library

This is a client for the gridscale API. It can be used to make an application interact with the gridscale cloud platform to create and manage resources.

Prerequisites

To be able to use this client a number of steps need to be taken. First a gridscale account will be required, which can be created here. Then an API-token should be created.

Installation

First the Go programming language will need to be installed. This can be done by using the official Go installation guide or by using the packages provided by your distribution.

Downloading the gridscale Go client can be done with the following go command:

$ go get github.com/gridscale/gsclient-go/v3

Using the Client

To be able to use the gridscale Go client in an application it can be imported in a go file. This can be done with the following code:

import "github.com/gridscale/gsclient-go/v3"

To get access to the functions of the Go client, a Client type needs to be created. This requires a Config type. Both of these can be created with the following code:

//Using default config
config := gsclient.DefaultConfiguration("User-UUID", "API-token")

//OR Custom config
config := gsclient.NewConfiguration(
            "API-URL",
            "User-UUID",
            "API-token",
            false, //Set debug mode
            true, //Set sync mode
            500, //Delay (in milliseconds) between requests (or retry 503 error code)
            100, //Maximum number of retries when server returns 503 error code
        )
client := gsclient.NewClient(config)

To trace the duration of individual client calls, set logger to Trace level via gsclient.SetLogLevel() function. Other log levels: https://github.com/sirupsen/logrus#level-logging

gsclient.SetLogLevel(logrus.TraceLevel)

Trace message looks like following:

TRAC[2021-03-12T10:32:43+01:00] Successful method="github.com/gridscale/gsclient-go/v3.(*Client).GetServer" requestUUID=035fc625-199d-41da-93c4-f32502d101c1 timeMs=350

Make sure to replace the user-UUID and API-token strings with valid credentials or variables containing valid credentials. It is recommended to use environment variables for them.

Using API endpoints

***Note: context has to be passed to all APIs of gsclient-go as the first parameter. In case you want to set timeout for a specific operation, you can pass a context with timeout (via context.WithTimeout or context.WithDeadline)

After having created a Client type, as shown above, it will be possible to interact with the API. An example would be the Servers Get endpoint:

ctx := context.Background()
servers := client.GetServerList(ctx)

For creating and updating/patching objects in gridscale, it will be required to use the respective CreateRequest and UpdateRequest types. For creating an IP that would be IPCreateRequest and IPUpdateRequest. Here an example:

ctx := context.Background()
requestBody := gsclient.IPCreateRequest{
    Name:       "IPTest",
    Family:     gsclient.IPv6Type,
    Failover:   false,
    ReverseDNS: "my-reverse-dns-entry.tld",
    Labels:     []string{"MyLabel"},
}

client.CreateIP(ctx, requestBody)

For updating/scaling server resources you could use:

myServerUuid := "[Server UUID]"
backgroundContext := context.Background()

// No hotplug available for scaling resources down, shutdown server first via ACPI
shutdownErr := client.ShutdownServer(backgroundContext, myServerUuid)
if shutdownErr != nil{
    log.Error("Shutdown server failed", shutdownErr)
    return
}

// Update servers resources
requestBody := gsclient.ServerUpdateRequest{
    Memory:          12,
    Cores:           4,
}

updateErr := client.UpdateServer(backgroundContext, myServerUuid, requestBody)
if updateErr != nil{
    log.Error("Serverupdate failed", updateErr)
    return
}

// Start server again
poweronErr := client.StartServer(backgroundContext, myServerUuid)
if poweronErr != nil{
    log.Error("Start server failed", poweronErr)
    return
}

What options are available for each create and update request can be found in the source code. After installing it should be located in $GOPATH/src/github.com/gridscale/gsclient-go.

Examples

Examples on how to use each resource can be found in the examples folder:

Firewall (firewall.go)
IP (ip.go)
ISO-image (isoimage.go)
Loadbalancer (loadbalancer.go)
Network (network.go)
Object Storage (objectstorage.go)
PaaS service (paas.go)
Server (server.go)
Storage (storage.go)
Storage snapshot (snapshot.go)
Storage snapshot schedule (snapshotschedule.go)
SSH-key (sshkey.go)
Template (template.go)

Implemented API Endpoints

Not all endpoints have been implemented in this client, but new ones will be added in the future. Here is the current list of implemented endpoints and their respective function written like endpoint (function):