datacentred

README

Client library for automating DataCentred account management in Go.

www.datacentred.co.uk

Installation

Run:

go get github.com/datacentred/datacentred-go

In your code:

import(
    "github.com/datacentred/datacentred-go"
)

Usage

This SDK allows you to automate operations against your DataCentred account.

Operations include:

• Creating and managing users;
• Creating and managing roles for users;
• Managing OpenStack Project creation, quota adjustments, and user assignments;
• Viewing detailed usage/billing information for your account.

Authentication

The API used by this SDK uses two pieces of information to authenticate access.

A unique access key specific to your DataCentred account, and a secret key which is generated once.

To get started:

1. Find your API access key and secret key at my.datacentred.io

1. Set your credentials by exporting your access key and secret key as environment variables in your shell:

export DATACENTRED_ACCESS="my_access"
export DATACENTRED_SECRET="my_secret"

Or set your keys manually using the following code:

datacentred.Config.AccessKey = "my_access"
datacentred.Config.SecretKey = "my_secret"

Usage Examples

List all available users

users, err := datacentred.Users()
fmt.Println(users)
// => [{2bd21ee25cde40fdb9454954e4fbb4b5 bill.s.preston@esquire.com Bill Preston 2015-02-13 11:07:00 +0000 UTC 2017-09-26 09:11:38 +0000 UTC } {69a34c127dcb439fa9366762234687ac ted.theodore@logan.com Ted Logan 2014-08-22 14:32:31 +0000 UTC 2017-09-21 14:55:43 +0000 UTC }]

Find a user by id

user, err := datacentred.FindUser("2bd21ee25cde40fdb9454954e4fbb4b5")
fmt.Println(user)
// => {2bd21ee25cde40fdb9454954e4fbb4b5 bill.s.preston@esquire.com Bill Preston 2015-02-13 11:07:00 +0000 UTC 2017-09-26 09:11:38 +0000 UTC } 

Update a project

project, err := datacentred.FindProject("37033518a4514f12adeb8346ac3f188c")
project.QuotaSet.Compute.Instances = 50
_, err = project.Save()
fmt.Println(project)
// => [{37033518a4514f12adeb8346ac3f188c seancentred {{40 50 60000} {40 10 5} {0 10 50 10 10 100 10}} 2015-04-09 08:14:19 +0000 UTC 2016-12-08 11:44:05 +0000 UTC}

Create a role

params := map[string]string{
  "name": "Wyld Stallyns",
}

role, err := CreateRole(params)
fmt.Println(role)
// => {5713b281-b9f7-41d7-bc8c-9eb92920d1d3 Wyld Stallyns false [] 2017-09-26 09:42:56 +0000 UTC 2017-09-26 09:42:56 +0000 UTC}

Add a user to a role

user, _ := datacentred.Users()[0]
result, err := role.AddUser(user.Id)
fmt.Println(result)
// => true

Remove a user from a project

users, _ := datacentred.Users()
user := users[0]
result, err = project.RemoveUser(user.Id)
fmt.Println(result)
// => true

Get usage data for a given year and month

usage, err := datacentred.FindUsage(2017, 9)
fmt.Println(usage.Projects[0].Usage.Instances[0].Usage.Value)
// => 744
fmt.Println(usage.Projects[0].Usage.Instances[0].Usage.Unit)
// => "hours"

Documentation

https://godoc.org/github.com/datacentred/datacentred-go

API Reference Manual

Please check out the DataCentred API Documentation for a comprehensive description of the API itself.

Documentation

Index

• Constants
• Variables
• func Request(verb string, path string, body []byte) ([]byte, error)
• type ApiError
• type Configuration
• type InstanceFlavor
• type InstanceHistoryEntry
• type IpQuotaChange
• type Project
  • func CreateProject(Params interface{}) (*Project, error)
  • func FindProject(Id string) (*Project, error)
  • func Projects() ([]Project, error)
  • func (p Project) AddUser(UserId string) (bool, error)
  • func (p Project) Destroy() (bool, error)
  • func (p Project) RemoveUser(UserId string) (bool, error)
  • func (p Project) Save() (Project, error)
  • func (p Project) Users() ([]User, error)
• type ProjectImagesUsage
• type ProjectInstancesUsage
• type ProjectIpsUsage
• type ProjectLoadBalancersUsage
• type ProjectUsage
• type ProjectVolumesUsage
• type ProjectVpnsUsage
• type QuotaSet
• type Role
  • func CreateRole(Params interface{}) (*Role, error)
  • func FindRole(Id string) (*Role, error)
  • func Roles() ([]Role, error)
  • func (r Role) AddUser(UserId string) (bool, error)
  • func (r Role) Destroy() (bool, error)
  • func (r Role) RemoveUser(UserId string) (bool, error)
  • func (r Role) Save() (Role, error)
  • func (r Role) Users() ([]User, error)
• type Usage
  • func FindUsage(year int, month int) (*Usage, error)
• type UsageBreakdown
• type User
  • func CreateUser(Params interface{}) (*User, error)
  • func FindUser(Id string) (*User, error)
  • func Users() ([]User, error)
  • func (u User) ChangePassword(Password string) (bool, error)
  • func (u User) Destroy() (bool, error)
  • func (u User) Save() (User, error)

Constants

const AcceptType = "application/vnd.datacentred.api+json"

AcceptType is the response type we accept from the server.

const ApiVersion = "1"

ApiVersion is the API microversion this SDK currently targets on server.

const BaseUri = "https://my.datacentred.io/api/"

BaseUri is the server's base URI before path suffixes are added.

const ContentType = "application/json"

ContentType is the request content type for the API.

const UserAgent = "datacentred/go v1"

Variables

var Config = Configuration{
	Client:    http.Client{},
	AccessKey: os.Getenv("DATACENTRED_ACCESS"),
	SecretKey: os.Getenv("DATACENTRED_SECRET"),
}

Config holds config information for this SDK. This includes API credentials and a HTTP transport client.

Functions

func Request

func Request(verb string, path string, body []byte) ([]byte, error)

Request makes a single HTTP request against the API server and returns the server's response as a byte sequence.

Types

type ApiError

type ApiError struct {
	Detail   string
	Field    string
	Resource string
}

ApiError contains details of a single error returned from the API.

type Configuration

type Configuration struct {
	Client    http.Client
	AccessKey string
	SecretKey string
}

Configuration is a structure for config data this SDK.

type InstanceFlavor

type InstanceFlavor struct {
	Id         string `json:"id"`
	Name       string `json:"name"`
	RamMb      int    `json:"ram_mb"`
	RootDiskGb int    `json:"root_disk_gb"`
	VcpusCount int    `json:"vcpus_count"`
}

InstanceFlavor contains information about a cloud instance's assigned flavor.

type InstanceHistoryEntry

type InstanceHistoryEntry struct {
	Billable   bool      `json:"billable"`
	EventName  string    `json:"event_name"`
	Flavor     string    `json:"flavor"`
	RecordedAt time.Time `json:"recorded_at"`
	Seconds    int       `json:"seconds"`
	State      string    `json:"state"`
	UserId     string    `json:"user_id"`
}

InstanceHistoryEntry contains information about a specific event in a cloud instance's runtime history.

type IpQuotaChange

type IpQuotaChange struct {
	Previous   int       `json:"previous"`
	Quota      int       `json:"quota"`
	RecordedAt time.Time `json:"recorded_at"`
}

IpQuotaChange contains information about an IP quota change event.

type Project

type Project struct {
	Id        string    `json:"id"`
	Name      string    `json:"name"`
	QuotaSet  QuotaSet  `json:"quota_set"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Project is a cloud organizational unit. It is possible to manage a project's name and resource quotas, as well as assign/revoke user access.

func CreateProject

func CreateProject(Params interface{}) (*Project, error)

CreateProject creates a new project on the currently authenticated user's account. This may fail if the account is at its limit for projects.

func FindProject

func FindProject(Id string) (*Project, error)

FindProject locates a specific project by its unique ID.

func Projects

func Projects() ([]Project, error)

Projects is the collection of projects belonging to the currently authenticated user's account.

func (Project) AddUser

func (p Project) AddUser(UserId string) (bool, error)

AddUser grants a user access to this project.

func (Project) Destroy

func (p Project) Destroy() (bool, error)

Destroy permanently removes this project.

func (Project) RemoveUser

func (p Project) RemoveUser(UserId string) (bool, error)

RemoveUser revokes a user's access to this project.

func (Project) Save

func (p Project) Save() (Project, error)

Save commits any changes to this project's fields.

func (Project) Users

func (p Project) Users() ([]User, error)

Users is the collection of users assigned to this project.

type ProjectImagesUsage

type ProjectImagesUsage struct {
	CreatedAt    time.Time        `json:"created_at"`
	DeletedAt    time.Time        `json:"deleted_at"`
	Id           string           `json:"id"`
	LatestSizeGb float64          `json:"latest_size_gb"`
	Name         string           `json:"name"`
	Owner        string           `json:"owner"`
	Usage        []UsageBreakdown `json:"usage"`
}

ProjectImagesUsage contains usage information for a single cloud image.

type ProjectInstancesUsage

type ProjectInstancesUsage struct {
	FirstBootedAt time.Time              `json:"first_booted_at"`
	TerminatedAt  time.Time              `json:"terminated_at"`
	Id            string                 `json:"id"`
	Name          string                 `json:"name"`
	LatestState   string                 `json:"latest_state"`
	History       []InstanceHistoryEntry `json:"history"`
	Tags          []string               `json:"tags"`
	CurrentFlavor InstanceFlavor         `json:"current_flavor"`
	Usage         []UsageBreakdown       `json:"usage"`
}

ProjectInstancesUsage contains usage information about a single cloud instance.

type ProjectIpsUsage

type ProjectIpsUsage struct {
	CurrentQuota int              `json:"current_quota"`
	QuotaChanges []IpQuotaChange  `json:"quota_changes"`
	Usage        []UsageBreakdown `json:"usage"`
}

ProjectIpsUsage contains usage information about IPs.

type ProjectLoadBalancersUsage

type ProjectLoadBalancersUsage struct {
	Id           string           `json:"id"`
	Name         string           `json:"name"`
	Owner        string           `json:"owner"`
	StartedAt    time.Time        `json:"started_at"`
	TerminatedAt time.Time        `json:"terminated_at"`
	Usage        []UsageBreakdown `json:"usage"`
}

ProjectLoadBalancersUsage contains usage information about a single cloud load balancer.

type ProjectUsage

type ProjectUsage struct {
	Id    string `json:"id"`
	Name  string `json:"name"`
	Usage struct {
		Images        []ProjectImagesUsage        `json:"images"`
		Instances     []ProjectInstancesUsage     `json:"instances"`
		Ips           ProjectIpsUsage             `json:"ips"`
		LoadBalancers []ProjectLoadBalancersUsage `json:"load_balancers"`
		ObjectStorage struct {
			Usage []UsageBreakdown `json:"usage"`
		} `json:"object_storage"`
		Volumes []ProjectVolumesUsage `json:"volumes"`
		Vpns    []ProjectVpnsUsage    `json:"vpns"`
	} `json:"usage"`
}

ProjectUsage contains usage information about a single cloud project.

type ProjectVolumesUsage

type ProjectVolumesUsage struct {
	CreatedAt    time.Time        `json:"created_at"`
	DeletedAt    time.Time        `json:"deleted_at"`
	Id           string           `json:"id"`
	LatestSizeGb int              `json:"latest_size_gb"`
	Name         string           `json:"name"`
	Owner        string           `json:"owner"`
	Tags         []string         `json:"tags"`
	Usage        []UsageBreakdown `json:"usage"`
}

ProjectVolumesUsage contains usage information about a single cloud volume.

type ProjectVpnsUsage

type ProjectVpnsUsage struct {
	Id           string           `json:"id"`
	Name         string           `json:"name"`
	Owner        string           `json:"owner"`
	StartedAt    time.Time        `json:"started_at"`
	TerminatedAt time.Time        `json:"terminated_at"`
	Usage        []UsageBreakdown `json:"usage"`
}

ProjectVpnsUsage contains usage information about a single cloud VPN.

type QuotaSet

type QuotaSet struct {
	Compute struct {
		Cores     int `json:"cores"`
		Instances int `json:"instances"`
		Ram       int `json:"ram"`
	} `json:"compute"`
	Volume struct {
		Gigabytes int `json:"gigabytes"`
		Snapshots int `json:"snapshots"`
		Volumes   int `json:"volumes"`
	} `json:"volume"`
	Network struct {
		FloatingIp        int `json:"floating_ip"`
		Network           int `json:"network"`
		Port              int `json:"port"`
		Router            int `json:"router"`
		SecurityGroup     int `json:"security_group"`
		SecurityGroupRule int `json:"security_group_rule"`
		Subnet            int `json:"subnet"`
	} `json:"network"`
}

QuotaSet is a collection of resource quota values for a Project. It contains Compute, Volume, and Network values as positive integers.

type Role

type Role struct {
	Id          string    `json:"id"`
	Name        string    `json:"name"`
	Admin       bool      `json:"admin"`
	Permissions []string  `json:"permissions"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Role is a grouping structure for assigning account permissions to all users who are assigned as members of the role.

func CreateRole

func CreateRole(Params interface{}) (*Role, error)

CreateRole creates a new role on the currently authenticated user's account.

func FindRole

func FindRole(Id string) (*Role, error)

FindRole locates a specific role by its unique ID.

func Roles

func Roles() ([]Role, error)

Roles is the collection of roles belonging to the currently authenticated user's account.

func (Role) AddUser

func (r Role) AddUser(UserId string) (bool, error)

AddUser assigns a user to this role, granting them the role's permissions.

func (Role) Destroy

func (r Role) Destroy() (bool, error)

Destroy permanently removes this role.

func (Role) RemoveUser

func (r Role) RemoveUser(UserId string) (bool, error)

RemoveUser removes a user from this role, revoking the role's permissions.

func (Role) Save

func (r Role) Save() (Role, error)

Save commits any changes to this role's fields.

func (Role) Users

func (r Role) Users() ([]User, error)

Users is the collection of users assigned to this role.

type Usage

type Usage struct {
	LastUpdatedAt time.Time      `json:"last_updated_at"`
	Projects      []ProjectUsage `json:"projects"`
}

Usage contains usage information about all cloud projects belonging to the currently authenticated user's account.

func FindUsage

func FindUsage(year int, month int) (*Usage, error)

FindUsage retrieves resource usage data for a given month belonging to the currently authenticated user's account.

type UsageBreakdown

type UsageBreakdown struct {
	Cost struct {
		Currency string  `json:"currency"`
		Rate     float64 `json:"rate"`
		Value    float64 `json:"value"`
	}
	Meta  map[string]interface{} `json:"meta"`
	Unit  string                 `json:"unit"`
	Value float64                `json:"value"`
}

UsageBreakdown show the cost and unit-usage of a resource. This structure is common to all resource types.

type User

type User struct {
	Id        string    `json:"id"`
	Email     string    `json:"email"`
	FirstName string    `json:"first_name"`
	LastName  string    `json:"last_name"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

User is a member of this account's team. Users can log into the DataCentred dashboard and be assigned to OpenStack projects and granted system permissions via role assignment.

func CreateUser

func CreateUser(Params interface{}) (*User, error)

CreateUser creates a new user on the currently authenticated user's account. A password must be specified to create a new user.

func FindUser

func FindUser(Id string) (*User, error)

FindUser locates a specific user by its unique ID.

func Users

func Users() ([]User, error)

Users is the collection of users belonging to the currently authenticated user's account.

func (User) ChangePassword

func (u User) ChangePassword(Password string) (bool, error)

ChangePassword allows a new password to be set for this user.

func (User) Destroy

func (u User) Destroy() (bool, error)

Destroy permanently removes this user.

func (User) Save

func (u User) Save() (User, error)

Save commits any changes to this user's fields.