This is the official client for interfacing with UpCloud's API using the Go programming language. The features allows for easy and quick development and integration when using Go.
You'll need Go 1.7 or higher to use the client. You can use the following command to retrieve the client:
go get github.com/UpCloudLtd/upcloud-go-api
The general usage of the client adheres to the following pattern:
- Authenticate by creating a
client.Client
- Create a
service.Service
by passing the newly createdclient
object to it - Interface with the API using the various methods of the
service
object. Methods that take parameters wrap them in request objects.
We recommend setting up a separate subaccount for API usage to allow better access control and security. You can find out more about creating subaccounts at the following support article for Server Tags and Group Accounts. We strongly recommend limiting the connections to a specific address or address range for security purposes.
The examples here only deal with how to use the client itself. For information on how to use the API in general, please consult the UpCloud API documentation.
// Authenticate by passing your account login credentials to the client
c := client.New(user, password)
// It is generally a good idea to override the default timeout of the underlying HTTP client since some requests block for longer periods of time
c.SetTimeout(time.Second * 30)
// Create the service object
svc := service.New(c)
The easiest way to check whether the client credentials are correct is to issue a call to GetAccount()
.
username := "completely"
password := "invalid"
svc := service.New(client.New(username, password))
_, err := svc.GetAccount()
if err != nil {
panic("Invalid credentials")
}
All Service
methods return a result and an error object. You can differentiate between generic connection errors (like the API not being reachable) and service errors, which are errors returned in the response body by the API. This is useful for gracefully recovering from certain types of errors.
username := "completely"
password := "invalid"
svc := service.New(client.New(username, password))
_, err := svc.GetAccount()
// Handle errors in general
if (err != nil) {
// Handle service errors specifically
if serviceError, ok := err.(*upcloud.Error); ok {
fmt.Println(serviceError.ErrorCode)
fmt.Println(serviceError.ErrorMessage)
}
}
This snippet would print the following:
AUTHENTICATION_FAILED
Authentication failed using the given username and password.
The rest of these examples assume you already have a service object configured and named svc
.
The following example will retrieve a list of servers the account has access to.
// Retrieve the list of servers
servers, err := svc.GetServers()
if err != nil {
panic(err)
}
// Print the UUID and hostname of each server
for _, server := range servers.Servers {
fmt.Println(fmt.Sprintf("UUID: %s, hostname: %s", server.UUID, server.Hostname))
}
Since the request for creating a new server is asynchronous, the server will report its status as "maintenance" until the deployment has been fully completed.
// Create the server
serverDetails, err := svc.CreateServer(&request.CreateServerRequest{
Zone: "fi-hel1",
Title: "My new server",
Hostname: "server.example.com",
PasswordDelivery: request.PasswordDeliveryNone,
StorageDevices: []request.CreateServerStorageDevice{
{
Action: request.CreateStorageDeviceActionClone,
Storage: "01000000-0000-4000-8000-000030060200",
Title: "disk1",
Size: 30,
Tier: upcloud.StorageTierMaxIOPS,
},
},
IPAddresses: []request.CreateServerIPAddress{
{
Access: upcloud.IPAddressAccessPrivate,
Family: upcloud.IPAddressFamilyIPv4,
},
{
Access: upcloud.IPAddressAccessPublic,
Family: upcloud.IPAddressFamilyIPv4,
},
{
Access: upcloud.IPAddressAccessPublic,
Family: upcloud.IPAddressFamilyIPv6,
},
},
})
if err != nil {
panic(err)
}
fmt.Println(fmt.Sprintf("Server %s with UUID %s created", serverDetails.Title, serverDetails.UUID))
// Block for up to five minutes until the server has entered the "started" state
err = svc.WaitForServerState(&request.WaitForServerStateRequest{
UUID: serverDetails.UUID,
DesiredState: upcloud.ServerStateStarted,
Timeout: time.Minute * 5,
})
if err != nil {
panic(err)
}
fmt.Println("Server is now started")
In this example, we assume that there is a server represented by the variable serverDetails
and that the server state is stopped
. The next piece of code allows you to templatize the first storage device of the server.
// Loop through the storage devices
for i, storage := range serverDetails.StorageDevices {
// Find the first device
if i == 0 {
// Templatize the storage
storageDetails, err := svc.TemplatizeStorage(&request.TemplatizeStorageRequest{
UUID: storage.UUID,
Title: "Templatized storage",
})
if err != nil {
panic(err)
}
fmt.Println(fmt.Sprintf("Storage templatized as %s", storageDetails.UUID))
break
}
}
In this example, we assume that there is a storage device represented by storageDetails
and that if it is attached to any server, the server is stopped.
backupDetails, err := svc.CreateBackup(&request.CreateBackupRequest{
UUID: storageDetails.UUID,
Title: "Backup",
})
if err != nil {
panic(err)
}
fmt.Println(fmt.Sprintf("Backup of %s created as %s", storageDetails.UUID, backupDetails.UUID))
In this example, we assume that there is a server represented by the variable serverDetails
.
firewallRule, err := svc.CreateFirewallRule(&request.CreateFirewallRuleRequest{
ServerUUID: serverDetails.UUID,
FirewallRule: upcloud.FirewallRule{
Direction: upcloud.FirewallRuleDirectionIn,
Action: upcloud.FirewallRuleActionAccept,
Family: upcloud.IPAddressFamilyIPv4,
Protocol: upcloud.FirewallRuleProtocolTCP,
Position: 1,
Comment: "Accept all TCP input on IPv4",
},
})
if err != nil {
panic(err)
}
For more examples, please consult the service integration test suite (upcloud/service/service_test.go
).
The repository contains a Postman collection which can be used to quickly perform requests against the API to see what it returns. Import the collection into Postman, then create an environment containing the following variables:
authorization
- the value of theAuthorization
HTTP header, e.g.Basic <base64>
serveruuid
- an existing server UUIDipaddress
- an existing IP address that is assigned to one of your serversstorageuuid
- the UUID of a piece of storage (can be a template, doesn't have to be a disk)
To be able to run the test suite you'll need to export the following environment variables with their corresponding values:
UPCLOUD_GO_API_TEST_USER
(the API username)UPCLOUD_GO_API_TEST_PASSWORD
(the API password)UPCLOUD_GO_API_TEST_DELETE_RESOURCES
(eitheryes
orno
)
To run the test suite, run go test ./... -v -parallel 8
. If UPCLOUD_GO_API_TEST_DELETE_RESOURCES
is set to yes
,
all resources will be stopped and/or deleted after the test suite has run. Be careful which account you use for
testing so you don't accidentally delete or your production resources!
You can skip running the integration tests and just run the unit tests by passing -short
to the test command.
This client is distributed under the MIT License, see LICENSE.txt for more information.