Using CloudSigma’s API with Golang

aLogging into the CloudSigma website presents one with all that is needed to create, configure, and administer a CloudSigma virtual infrastructure, or IaaS. Alongside the menu for the various control panels, you will also see a link to the API documentation. The API enables programmatic access to all of the website functionality of the CloudSigma platform via HTTPS, returning JSON by default, or XML data [0]. Programmatic control of one’s infrastructure enables automation. It also enables responding to resource needs on demand, and integration with external systems from the cloud.  With Golang as my current systems language of choice, I set about writing a client library to harness the benefits of CloudSigma’s API.

CloudSigma API Documentation: https://cloudsigma-docs.readthedocs.org/en/latest/

The library consists of a Client object and a collection of resource objects. Each resource object represents a resource list, or item, such as cloud_status, locations, servers, or snapshots, and describes the resource with properties such as the URL resource name, whether authorization is a requirement, and methods for getting, creating, updating, and deleting the resource on the server. The library can be found at: https://github.com/russmack/cloudsigma

Making a Start

In order to send a request to a given resource, a resource object must be created. Then, an arguments object must be created. The arguments object is created by calling one of the desired NewList(), NewCreate(), NewEdit(), or NewDelete() methods, which correspond to the HTTPS GET, POST, PUT, and DELETE methods, and which return an Args object containing the required request properties for the resource request, such as the HTTPS verb, the content type, and whether authentication is required. Once created, the Args object has a number of user-specific fields such as Username, Password, Location, and Format. Then, they can be set. As an example, a request to the cloud_status resource would use an Args object as follows:

The cloud_status resource doesn’t require authentication, so there is no need to set args.Username or args.Password. Location is a requirement, and Format is optional: xml or json. With the args object set with the properties we require, we then create a Client object. The Client object has a Call method which takes as an argument the args object created in the preceding step. The response from Client.Call(Args) is a []byte.

Putting those parts together in a small example:

The options for the Args.Location field can be found by getting the locations [1] resource, as follows. You’ll notice that this request itself requires a location, because the API requires a subdomain, for which it uses a location.

At the time of writing, the above returns an object for each of Zurich, Honolulu, Miami, San Jose, and Washington DC. All of them with associated metadata.

Values with Limits

Requests which have limits to its values might vary according to factors such as cloud usage, or location. Client applications should use the capabilities [2] resource to retrieve the dynamic limits rather than hard-coding them. This resource requires authentication, so set the Username and Password properties.

The API has numerous administrative resources such as balance, subscriptions, transactions, and notification_preferences. Each of these can be retrieved with the same code as above, changing only the new resource call from NewCapabilities() to NewBalance(), NewSubscriptions(), NewTransactions(), and NewNotificationPreferences() respectively.

Editing Resources

Editing resources is similar. Instead of creating an Args object from the NewList() method, an Args objects is created from the NewEdit() method. Using notification_preferences as an example, to change the notification preferences of a specified contact, a Preference object is first created which will be posted as the body with the new values:

The Contact value above is in the resource_uri field of the response from a request to the notification_contacts resource, using NewNotificationContacts() NewList(). The Preference object is then passed to the NewEdit(Preference) method to create a suitable post Args object, then the required properties are set, and the Call(args) method called.

The call to get the Contact value from above, uses the same code with the following two lines changed:

Scaling Infrastructure

The fun starts with scaling and controlling the infrastructure. A new server can be created with the servers resource. In the following example, note that the new server is defined, and added to a slice, because although we’re only creating a single server, multiple can be created at a time. The server properties which we can specify are Name, CPU, Memory, and VNC password:

The server is created. If more servers are needed, that’s as simple as adding to the slice. CloudSigma will have the new servers created within a few seconds:

Servers can be started, stopped, and shutdown, by using the NewStart, NewStop, and NewShutdown methods to create an Args object. Each of the methods take the server UUID, retrieved from either the response of the create server request, or from a server listing:

Shutting down, and stopping are similar:

Creating drives takes the same approach as creating servers. The drive properties we can specify are Media, Name, and Size. Media can be disk or cdrom.

You can delete drives as well as servers, using the NewDelete(uuid) method. The UUID is in the response from a resource list request, or the response from a create request:

Conclusion

The CloudSigma API is comprehensive, including resources for networking, firewall policies, job tracking and audit logs. This post is only an introduction to start using Golang. Hopefully, you’ll find the client library helpful in speeding up your integrations and getting your client applications up and running faster.

References

• About
• Latest

About Russell Mackenzie

Russell is a developer with a keen interest in Go, and is enjoying putting it to use with Cloud technology. When he’s not exploring software he’s likely cycling into the countryside, or watching Formula 1.

• Using CloudSigma’s API with Golang - June 28, 2015