gophercloud

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2014 License: Apache-2.0 Imports: 7 Imported by: 16,429

README 

== Gophercloud -- V0.1.0 image:https://secure.travis-ci.org/rackspace/gophercloud.png?branch=master["build status",link="https://travis-ci.org/rackspace/gophercloud"]

Gophercloud currently lets you authenticate with OpenStack providers to create and manage servers.
We are working on extending the API to further include cloud files, block storage, DNS, databases, security groups, and other features.

WARNING: This library is still in the very early stages of development. Unless you want to contribute, it probably isn't what you want.  Yet.

=== Outstanding Features

1.  Apache 2.0 License, making Gophercloud friendly to commercial and open-source enterprises alike.
2.  Gophercloud is one of the most actively maintained Go SDKs for OpenStack.
3.  Gophercloud supports Identity V2 and Nova V2 APIs.  More coming soon!
4.  The up-coming Gophercloud 0.2.0 release supports API extensions, and makes writing support for new extensions easy.
5.  Gophercloud supports automatic reauthentication upon auth token timeout, if enabled by your software.
6.  Gophercloud is the only SDK implementation with actual acceptance-level integration tests.

=== What Does it Look Like?

The Gophercloud 0.1.0 and earlier APIs are now deprecated and obsolete.
No new feature development will occur for 0.1.0 or 0.0.0.
However, we will accept and provide bug fixes for these APIs.
Please refer to the acceptance tests in the master brach for code examples using the v0.1.0 API.
The most up to date documentation for version 0.1.x can be found at link:http://godoc.org/github.com/rackspace/gophercloud[our Godoc.org documentation].

We are working on a new API that provides much better support for extensions, pagination, and other features that proved difficult to implement before.
This new API will be substantially more Go-idiomatic as well; one of the complaints received about 0.1.x and earlier is that it didn't "feel" right.
To see what this new API is going to look like, you can look at the code examples up on the link:http://gophercloud.io/docs.html[Gophercloud website].
If you're interested in tracking progress, note that features for version 0.2.0 will appear in the `v0.2.0` branch until merged to master.

=== How can I Contribute?

After using Gophercloud for a while, you might find that it lacks some useful feature, or that existing behavior seems buggy.  We welcome contributions from our users for both missing functionality as well as for bug fixes.  We encourage contributors to collaborate with the link:http://gophercloud.io/community.html[Gophercloud community.]

Finally, Gophercloud maintains its own link:http://gophercloud.io[announcements and updates blog.]
Feel free to check back now and again to see what's new.

== License

Copyright (C) 2013, 2014 Rackspace, Inc.

Licensed under the Apache License, Version 2.0

Documentation

Overview

Gophercloud provides a multi-vendor interface to OpenStack-compatible clouds which attempts to follow established Go community coding standards and social norms.

Unless you intend on contributing code to the SDK, you will almost certainly never have to use any Context structures or any of its methods. Contextual methods exist for easier unit testing only. Stick with the global functions unless you know exactly what you're doing, and why.

Index

Constants

View Source 
const (
	PublicURL = iota
	InternalURL
)

The choices available for UrlChoice. See the ApiCriteria structure for details.

Variables

View Source 
var ErrConfiguration = fmt.Errorf("Missing or incomplete configuration")

ErrConfiguration errors happen when attempting to add a new provider, and the provider added lacks a correct or consistent configuration. For example, all providers must expose at least an Identity V2 API for authentication; if this endpoint isn't specified, you may receive this error when attempting to register it against a context.

View Source 
var ErrCredentials = fmt.Errorf("Missing or incomplete credentials")

ErrCredentials errors happen when attempting to authenticate using a set of credentials not recognized by the Authenticate() method. For example, not providing a username or password when attempting to authenticate against an Identity V2 API.

View Source 
var ErrEndpoint = fmt.Errorf("Missing endpoint, or insufficient privileges to access endpoint")

ErrEndpoint errors happen when no endpoint with the desired characteristics exists in the service catalog. This can also happen if your tenant lacks adequate permissions to access a given endpoint.

View Source 
var ErrError = fmt.Errorf("Attempt to solicit actual HTTP response code from error entity which doesn't know")

ErrError errors happen when you attempt to discover the response code responsible for a previous request bombing with an error, but pass in an error interface which doesn't belong to the web client.

View Source 
var ErrNotImplemented = fmt.Errorf("Not implemented")

ErrNotImplemented should be used only while developing new SDK features. No established function or method will ever produce this error.

View Source 
var ErrProvider = fmt.Errorf("Missing or incorrect provider")

ErrProvider errors occur when attempting to reference an unsupported provider. More often than not, this error happens due to a typo in the name.

View Source 
var OpenstackApi = map[string]interface{}{
	"UrlChoice": PublicURL,
}

The default generic openstack api

View Source 
var RackspaceApi = map[string]interface{}{
	"Name":      "cloudServersOpenStack",
	"VersionId": "2",
	"UrlChoice": PublicURL,
}

Api for use with rackspace

View Source 
var WarnUnauthoritative = fmt.Errorf("Unauthoritative data")

WarnUnauthoritative warnings happen when a service believes its response to be correct, but is not in a position of knowing for sure at the moment. For example, the service could be responding with cached data that has exceeded its time-to-live setting, but which has not yet received an official update from an authoritative source.

Functions

func ActualResponseCode 

func ActualResponseCode(e error) (int, error)

ActualResponseCode inspects a returned error, and discovers the actual response actual response code that caused the error to be raised.

Types

type Access 

type Access struct {
	Token          Token
	ServiceCatalog []CatalogEntry
	User           User
	// contains filtered or unexported fields
}

Access encapsulates the API token and its relevant fields, as well as the services catalog that Identity API returns once authenticated.

func Authenticate 

func Authenticate(provider string, options AuthOptions) (*Access, error)

Authenticate() grants access to the OpenStack-compatible provider API.

Providers are identified through a unique key string. Specifying an unsupported provider will result in an ErrProvider error. However, you may also specify a custom Identity API URL. Any provider name that contains the characters "://", in that order, will be treated as a custom Identity API URL. Custom URLs, important for private cloud deployments, overrides all provider configurations.

The supplied AuthOptions instance allows the client to specify only those credentials relevant for the authentication request. At present, support exists for OpenStack Identity V2 API only; support for V3 will become available as soon as documentation for it becomes readily available.

For Identity V2 API requirements, you must provide at least the Username and Password options. The TenantId field is optional, and defaults to "".

func (*Access) AuthToken 

func (a *Access) AuthToken() string

See AccessProvider interface definition for details.

func (*Access) FirstEndpointUrlByCriteria 

func (a *Access) FirstEndpointUrlByCriteria(ac ApiCriteria) string

See AccessProvider interface definition for details.

func (*Access) Reauthenticate 

func (a *Access) Reauthenticate() error

Reauthenticate attempts to reauthenticate using the configured access credentials, if allowed. This method takes no action unless your AuthOptions has the AllowReauth flag set to true.

func (*Access) Revoke 

func (a *Access) Revoke(tok string) error

See AccessProvider interface definition for details.

func (*Access) V2ServiceCatalog 

func (a *Access) V2ServiceCatalog() []CatalogEntry

See ServiceCatalogerForIdentityV2 interface definition for details. Note that the raw slice is returend; be careful not to alter the fields of any members, for other components of Gophercloud may depend upon them. If this becomes a problem in the future, a future revision may return a deep-copy of the service catalog instead.

type AccessProvider 

type AccessProvider interface {
	// FirstEndpointUrlByCriteria searches through the service catalog for the first
	// matching entry endpoint fulfilling the provided criteria.  If nothing found,
	// return "".  Otherwise, return either the public or internal URL for the
	// endpoint, depending on both its existence and the setting of the ApiCriteria.UrlChoice
	// field.
	FirstEndpointUrlByCriteria(ApiCriteria) string

	// AuthToken provides a copy of the current authentication token for the user's credentials.
	// Note that AuthToken() will not automatically refresh an expired token.
	AuthToken() string

	// Revoke allows you to terminate any program's access to the OpenStack API by token ID.
	Revoke(string) error

	// Reauthenticate attempts to acquire a new authentication token, if the feature is enabled by
	// AuthOptions.AllowReauth.
	Reauthenticate() error
}

AccessProvider instances encapsulate a Keystone authentication interface.

type AddressSet 

type AddressSet struct {
	Public  []VersionedAddress `json:"public"`
	Private []VersionedAddress `json:"private"`
}

An AddressSet provides a set of public and private IP addresses for a resource. Each address has a version to identify if IPv4 or IPv6.

type ApiCriteria 

type ApiCriteria struct {
	Name          string
	Type          string
	Region        string
	VersionId     string
	UrlChoice     int
	IgnoreEnvVars bool
}

ApiCriteria provides one or more criteria for the SDK to look for appropriate endpoints. Fields left unspecified or otherwise set to their zero-values are assumed to not be relevant, and do not participate in the endpoint search.

Name specifies the desired service catalog entry name. Type specifies the desired service catalog entry type. Region specifies the desired endpoint region. If unset, Gophercloud will try to use the region set in the OS_REGION_NAME environment variable. If that's not set, region comparison will not occur. If OS_REGION_NAME is set and IgnoreEnvVars is also set, OS_REGION_NAME will be ignored. VersionId specifies the desired version of the endpoint. Note that this field is matched exactly, and is (at present) opaque to Gophercloud. Thus, requesting a version 2 endpoint will _not_ match a version 3 endpoint. The UrlChoice field inidicates whether or not gophercloud should use the public or internal endpoint URL if a candidate endpoint is found. IgnoreEnvVars instructs Gophercloud to ignore helpful environment variables.

func PopulateApi added in v0.1.0 

func PopulateApi(variant string) (ApiCriteria, error)

Populates an ApiCriteria struct with the api values from one of the api maps

type ApiKeyCredentials 

type ApiKeyCredentials struct {
	Username string `json:"username"`
	ApiKey   string `json:"apiKey"`
}

type Auth 

type Auth struct {
	PasswordCredentials *PasswordCredentials `json:"passwordCredentials,omitempty"`
	ApiKeyCredentials   *ApiKeyCredentials   `json:"RAX-KSKEY:apiKeyCredentials,omitempty"`
	TenantId            string               `json:"tenantId,omitempty"`
	TenantName          string               `json:"tenantName,omitempty"`
}

Auth provides a JSON encoding wrapper for passing credentials to the Identity service. You will not work with this structure directly.

type AuthContainer 

type AuthContainer struct {
	Auth Auth `json:"auth"`
}

AuthContainer provides a JSON encoding wrapper for passing credentials to the Identity service. You will not work with this structure directly.

type AuthOptions 

type AuthOptions struct {
	// Username and Password are required if using Identity V2 API.
	// Consult with your provider's control panel to discover your
	// account's username and password.
	Username, Password string

	// ApiKey used for providers that support Api Key authentication
	ApiKey string

	// The TenantId field is optional for the Identity V2 API.
	TenantId string

	// The TenantName can be specified instead of the TenantId
	TenantName string

	// AllowReauth should be set to true if you grant permission for Gophercloud to cache
	// your credentials in memory, and to allow Gophercloud to attempt to re-authenticate
	// automatically if/when your token expires.  If you set it to false, it will not cache
	// these settings, but re-authentication will not be possible.  This setting defaults
	// to false.
	AllowReauth bool
}

AuthOptions lets anyone calling Authenticate() supply the required access credentials. At present, only Identity V2 API support exists; therefore, only Username, Password, and optionally, TenantId are provided. If future Identity API versions become available, alternative fields unique to those versions may appear here.

type CatalogEntry 

type CatalogEntry struct {
	Name, Type string
	Endpoints  []EntryEndpoint
}

CatalogEntry encapsulates a service catalog record.

type CloudServersProvider 

type CloudServersProvider interface {

	// ListServers provides a complete list of servers hosted by the user
	// in a given region.  This function differs from ListServersLinksOnly()
	// in that it returns all available details for each server returned.
	ListServers() ([]Server, error)

	// ListServers provides a complete list of servers hosted by the user
	// in a given region.  This function differs from ListServers() in that
	// it returns only IDs and links to each server returned.
	//
	// This function should be used only under certain circumstances.
	// It's most useful for checking to see if a server with a given ID exists,
	// or that you have permission to work with that server.  It's also useful
	// when the cost of retrieving the server link list plus the overhead of manually
	// invoking ServerById() for each of the servers you're interested in is less than
	// just calling ListServers() to begin with.  This may be a consideration, for
	// example, with mobile applications.
	//
	// In other cases, you probably should just call ListServers() and cache the
	// results to conserve overall bandwidth and reduce your access rate on the API.
	ListServersLinksOnly() ([]Server, error)

	// ServerById will retrieve a detailed server description given the unique ID
	// of a server.  The ID can be returned by either ListServers() or by ListServersLinksOnly().
	ServerById(id string) (*Server, error)

	// CreateServer requests a new server to be created by the cloud server provider.
	// The user must pass in a pointer to an initialized NewServerContainer structure.
	// Please refer to the NewServerContainer documentation for more details.
	//
	// If the NewServer structure's AdminPass is empty (""), a password will be
	// automatically generated by your OpenStack provider, and returned through the
	// AdminPass field of the result.  Take care, however; this will be the only time
	// this happens.  No other means exists in the public API to acquire a password
	// for a pre-existing server.  If you lose it, you'll need to call SetAdminPassword()
	// to set a new one.
	CreateServer(ns NewServer) (*NewServer, error)

	// DeleteServerById requests that the server with the assigned ID be removed
	// from your account.  The delete happens asynchronously.
	DeleteServerById(id string) error

	// SetAdminPassword requests that the server with the specified ID have its
	// administrative password changed.  For Linux, BSD, or other POSIX-like
	// system, this password corresponds to the root user.  For Windows machines,
	// the Administrator password will be affected instead.
	SetAdminPassword(id string, pw string) error

	// ResizeServer can be a short-hand for RebuildServer where only the size of the server
	// changes.  Note that after the resize operation is requested, you will need to confirm
	// the resize has completed for changes to take effect permanently.  Changes will assume
	// to be confirmed even without an explicit confirmation after 24 hours from the initial
	// request.
	ResizeServer(id, newName, newFlavor, newDiskConfig string) error

	// RevertResize will reject a server's resized configuration, thus
	// rolling back to the original server.
	RevertResize(id string) error

	// ConfirmResizeServer will acknowledge a server's resized configuration.
	ConfirmResize(id string) error

	// RebootServer requests that the server with the specified ID be rebooted.
	// Two reboot mechanisms exist.
	//
	// - Hard.  This will physically power-cycle the unit.
	// - Soft.  This will attempt to use the server's software-based mechanisms to restart
	//           the machine.  E.g., "shutdown -r now" on Linux.
	RebootServer(id string, hard bool) error

	// RescueServer requests that the server with the specified ID be placed into
	// a state of maintenance.  The server instance is replaced with a new instance,
	// of the same flavor and image.  This new image will have the boot volume of the
	// original machine mounted as a secondary device, so that repair and administration
	// may occur.  Use UnrescueServer() to restore the server to its previous state.
	// Note also that many providers will impose a time limit for how long a server may
	// exist in rescue mode!  Consult the API documentation for your provider for
	// details.
	RescueServer(id string) (string, error)

	// UnrescueServer requests that a server in rescue state be placed into its nominal
	// operating state.
	UnrescueServer(id string) error

	// UpdateServer alters one or more fields of the identified server's Server record.
	// However, not all fields may be altered.  Presently, only Name, AccessIPv4, and
	// AccessIPv6 fields may be altered.   If unspecified, or set to an empty or zero
	// value, the corresponding field remains unaltered.
	//
	// This function returns the new set of server details if successful.
	UpdateServer(id string, newValues NewServerSettings) (*Server, error)

	// RebuildServer reprovisions a server to the specifications given by the
	// NewServer structure.  The following fields are guaranteed to be recognized:
	//
	//		Name (required)				AccessIPv4
	//		imageRef (required)			AccessIPv6
	//		AdminPass (required)		Metadata
	//		Personality
	//
	// Other providers may reserve the right to act on additional fields.
	RebuildServer(id string, ns NewServer) (*Server, error)

	// CreateImage will create a new image from the specified server id returning the id of the new image.
	CreateImage(id string, ci CreateImage) (string, error)

	// ListAddresses yields the list of available addresses for the server.
	// This information is also returned by ServerById() in the Server.Addresses
	// field.  However, if you have a lot of servers and all you need are addresses,
	// this function might be more efficient.
	ListAddresses(id string) (AddressSet, error)

	// ListAddressesByNetwork yields the list of available addresses for a given server id and networkLabel.
	// Example: ListAddressesByNetwork("234-4353-4jfrj-43j2s", "private")
	ListAddressesByNetwork(id, networkLabel string) (NetworkAddress, error)

	// ListFloatingIps yields the list of all floating IP addresses allocated to the current project.
	ListFloatingIps() ([]FloatingIp, error)

	// CreateFloatingIp allocates a new IP from the named pool to the current project.
	CreateFloatingIp(pool string) (FloatingIp, error)

	// DeleteFloatingIp returns the specified IP from the current project to the pool.
	DeleteFloatingIp(ip FloatingIp) error

	// AssociateFloatingIp associates the given floating IP to the given server id.
	AssociateFloatingIp(serverId string, ip FloatingIp) error

	// ListImages yields the list of available operating system images.  This function
	// returns full details for each image, if available.
	ListImages() ([]Image, error)

	// ImageById yields details about a specific image.
	ImageById(id string) (*Image, error)

	// DeleteImageById will delete the specific image.
	DeleteImageById(id string) error

	// ListFlavors yields the list of available system flavors.  This function
	// returns full details for each flavor, if available.
	ListFlavors() ([]Flavor, error)

	// ListKeyPairs yields the list of available keypairs.
	ListKeyPairs() ([]KeyPair, error)

	// CreateKeyPairs will create or generate a new keypair.
	CreateKeyPair(nkp NewKeyPair) (KeyPair, error)

	// DeleteKeyPair wil delete a keypair.
	DeleteKeyPair(name string) error

	// ShowKeyPair will yield the named keypair.
	ShowKeyPair(name string) (KeyPair, error)

	// ListSecurityGroups provides a listing of security groups for the tenant.
	// This method works only if the provider supports the os-security-groups extension.
	ListSecurityGroups() ([]SecurityGroup, error)

	// CreateSecurityGroup lets a tenant create a new security group.
	// Only the SecurityGroup fields which are specified will be marshalled to the API.
	// This method works only if the provider supports the os-security-groups extension.
	CreateSecurityGroup(desired SecurityGroup) (*SecurityGroup, error)

	// ListSecurityGroupsByServerId provides a list of security groups which apply to the indicated server.
	// This method works only if the provider supports the os-security-groups extension.
	ListSecurityGroupsByServerId(id string) ([]SecurityGroup, error)

	// SecurityGroupById returns a security group corresponding to the provided ID number.
	// This method works only if the provider supports the os-security-groups extension.
	SecurityGroupById(id int) (*SecurityGroup, error)

	// DeleteSecurityGroupById disposes of a security group corresponding to the provided ID number.
	// This method works only if the provider supports the os-security-groups extension.
	DeleteSecurityGroupById(id int) error

	// ListDefaultSGRules lists default security group rules.
	// This method only works if the provider supports the os-security-groups-default-rules extension.
	ListDefaultSGRules() ([]SGRule, error)

	// CreateDefaultSGRule creates a default security group rule.
	// This method only works if the provider supports the os-security-groups-default-rules extension.
	CreateDefaultSGRule(SGRule) (*SGRule, error)

	// GetSGRule obtains information for a specified security group rule.
	// This method only works if the provider supports the os-security-groups-default-rules extension.
	GetSGRule(string) (*SGRule, error)
}

CloudServersProvider instances encapsulate a Cloud Servers API, should one exist in the service catalog for your provider.

func ServersApi 

func ServersApi(acc AccessProvider, criteria ApiCriteria) (CloudServersProvider, error)

Instantiates a Cloud Servers object for the provider given.

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context structures encapsulate Gophercloud-global state in a manner which facilitates easier unit testing. As a user of this SDK, you'll never have to use this structure, except when contributing new code to the SDK.

func TestContext 

func TestContext() *Context

TestContext yields a new Context instance, pre-initialized with a barren state suitable for per-unit-test customization. This configuration consists of:

* An empty provider map.

* An HTTP client built by the net/http package (see http://godoc.org/net/http#Client).

func (*Context) Authenticate 

func (c *Context) Authenticate(provider string, options AuthOptions) (*Access, error)

Authenticate() grants access to the OpenStack-compatible provider API.

Providers are identified through a unique key string. See the RegisterProvider() method for more details.

The supplied AuthOptions instance allows the client to specify only those credentials relevant for the authentication request. At present, support exists for OpenStack Identity V2 API only; support for V3 will become available as soon as documentation for it becomes readily available.

For Identity V2 API requirements, you must provide at least the Username and Password options. The TenantId field is optional, and defaults to "".

func (*Context) ProviderByName 

func (c *Context) ProviderByName(name string) (p Provider, err error)

ProviderByName will locate a provider amongst those previously registered, if it exists. If the named provider has not been registered, an ErrProvider error will result.

You may also specify a custom Identity API URL. Any provider name that contains the characters "://", in that order, will be treated as a custom Identity API URL. Custom URLs, important for private cloud deployments, overrides all provider configurations.

func (*Context) RegisterProvider 

func (c *Context) RegisterProvider(name string, p Provider) error

RegisterProvider allows a unit test to register a mythical provider convenient for testing. If the provider structure lacks adequate configuration, or the configuration given has some detectable error, an ErrConfiguration error will result.

func (*Context) ResponseWithReauth 

func (c *Context) ResponseWithReauth(ap AccessProvider, f func() (*perigee.Response, error)) (*perigee.Response, error)

This is like WithReauth above but returns a perigee Response object

func (*Context) ServersApi 

func (c *Context) ServersApi(acc AccessProvider, criteria ApiCriteria) (CloudServersProvider, error)

Instantiates a Cloud Servers API for the provider given.

func (*Context) UseCustomClient 

func (c *Context) UseCustomClient(hc *http.Client) *Context

UseCustomClient configures the context to use a customized HTTP client instance. By default, TestContext() will return a Context which uses the net/http package's default client instance.

func (*Context) WithProvider 

func (c *Context) WithProvider(name string, p Provider) *Context

WithProvider offers convenience for unit tests.

func (*Context) WithReauth 

func (c *Context) WithReauth(ap AccessProvider, f func() error) error

WithReauth wraps a Perigee request fragment with logic to perform re-authentication if it's deemed necessary.

Do not confuse this function with WithReauth()! Although they work together to support reauthentication, WithReauth() actually contains the decision-making logic to determine when to perform a reauth, while WithReauthHandler() is used to configure what a reauth actually entails.

func (*Context) WithReauthHandler 

func (c *Context) WithReauthHandler(f ReauthHandlerFunc) *Context

WithReauthHandler configures the context to handle reauthentication attempts using the supplied funtion. By default, reauthentication happens by invoking Authenticate(), which is unlikely to be useful in a unit test.

Do not confuse this function with WithReauth()! Although they work together to support reauthentication, WithReauth() actually contains the decision-making logic to determine when to perform a reauth, while WithReauthHandler() is used to configure what a reauth actually entails.

type CreateImage 

type CreateImage struct {
	Name     string            `json:"name"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type EntryEndpoint 

type EntryEndpoint struct {
	Region, TenantId                    string
	PublicURL, InternalURL              string
	VersionId, VersionInfo, VersionList string
}

EntryEndpoint encapsulates how to get to the API of some service.

func FindFirstEndpointByCriteria 

func FindFirstEndpointByCriteria(entries []CatalogEntry, ac ApiCriteria) EntryEndpoint

Given a set of criteria to match on, locate the first candidate endpoint in the provided service catalog.

If nothing found, the result will be a zero-valued EntryEndpoint (all URLs set to "").

type FileConfig 

type FileConfig struct {
	Path     string `json:"path"`
	Contents string `json:"contents"`
}

FileConfig structures represent a blob of data which must appear at a a specific location in a server's filesystem. The file contents are base-64 encoded.

type Flavor 

type Flavor struct {
	OsFlvDisabled bool    `json:"OS-FLV-DISABLED:disabled"`
	Disk          int     `json:"disk"`
	Id            string  `json:"id"`
	Links         []Link  `json:"links"`
	Name          string  `json:"name"`
	Ram           int     `json:"ram"`
	RxTxFactor    float64 `json:"rxtx_factor"`
	Swap          int     `json:"swap"`
	VCpus         int     `json:"vcpus"`
}

Flavor records represent (virtual) hardware configurations for server resources in a region.

The Id field contains the flavor's unique identifier. For example, this identifier will be useful when specifying which hardware configuration to use for a new server instance.

The Disk and Ram fields provide a measure of storage space offered by the flavor, in GB and MB, respectively.

The Name field provides a human-readable moniker for the flavor.

Swap indicates how much space is reserved for swap. If not provided, this field will be set to 0.

VCpus indicates how many (virtual) CPUs are available for this flavor. 

type FlavorLink struct {
	Id    string `json:"id"`
	Links []Link `json:"links"`
}

FlavorLink provides a reference to a flavor by either ID or by direct URL. Some services use just the ID, others use just the URL. This structure provides a common means of expressing both in a single field.

type FloatingIp added in v0.1.0 

type FloatingIp struct {
	Id         int    `json:"id"`
	Pool       string `json:"pool"`
	Ip         string `json:"ip"`
	FixedIp    string `json:"fixed_ip"`
	InstanceId string `json:"instance_id"`
}

type Image 

type Image struct {
	Created         string `json:"created"`
	Id              string `json:"id"`
	Links           []Link `json:"links"`
	MinDisk         int    `json:"minDisk"`
	MinRam          int    `json:"minRam"`
	Name            string `json:"name"`
	Progress        int    `json:"progress"`
	Status          string `json:"status"`
	Updated         string `json:"updated"`
	OsDcfDiskConfig string `json:"OS-DCF:diskConfig"`
}

Image is used for JSON (un)marshalling. It provides a description of an OS image.

The Id field contains the image's unique identifier. For example, this identifier will be useful for specifying which operating system to install on a new server instance.

The MinDisk and MinRam fields specify the minimum resources a server must provide to be able to install the image.

The Name field provides a human-readable moniker for the OS image.

The Progress and Status fields indicate image-creation status. Any usable image will have 100% progress.

The Updated field indicates the last time this image was changed.

OsDcfDiskConfig indicates the server's boot volume configuration. Valid values are: 

AUTO
----
The server is built with a single partition the size of the target flavor disk.
The file system is automatically adjusted to fit the entire partition.
This keeps things simple and automated.
AUTO is valid only for images and servers with a single partition that use the EXT3 file system.
This is the default setting for applicable Rackspace base images.

MANUAL
------
The server is built using whatever partition scheme and file system is in the source image.
If the target flavor disk is larger,
the remaining disk space is left unpartitioned.
This enables images to have non-EXT3 file systems, multiple partitions, and so on,
and enables you to manage the disk configuration.

type ImageLink struct {
	Id    string `json:"id"`
	Links []Link `json:"links"`
}

ImageLink provides a reference to a image by either ID or by direct URL. Some services use just the ID, others use just the URL. This structure provides a common means of expressing both in a single field.

type KeyPair 

type KeyPair struct {
	FingerPrint string `json:"fingerprint"`
	Name        string `json:"name"`
	PrivateKey  string `json:"private_key,omitempty"`
	PublicKey   string `json:"public_key"`
	UserID      string `json:"user_id,omitempty"`
}
type Link struct {
	Href string `json:"href"`
	Rel  string `json:"rel"`
	Type string `json:"type"`
}

Link is used for JSON (un)marshalling. It provides RESTful links to a resource.

type NetworkAddress 

type NetworkAddress map[string][]VersionedAddress

type NetworkConfig 

type NetworkConfig struct {
	Uuid string `json:"uuid"`
}

NetworkConfig structures represent an affinity between a server and a specific, uniquely identified network. Networks are identified through universally unique IDs.

type NewKeyPair 

type NewKeyPair struct {
	Name      string `json:"name"`
	PublicKey string `json:"public_key,omitempty"`
}

type NewServer 

type NewServer struct {
	Name            string                   `json:"name,omitempty"`
	ImageRef        string                   `json:"imageRef,omitempty"`
	FlavorRef       string                   `json:"flavorRef,omitempty"`
	Metadata        map[string]string        `json:"metadata,omitempty"`
	Personality     []FileConfig             `json:"personality,omitempty"`
	Networks        []NetworkConfig          `json:"networks,omitempty"`
	AdminPass       string                   `json:"adminPass,omitempty"`
	KeyPairName     string                   `json:"key_name,omitempty"`
	Id              string                   `json:"id,omitempty"`
	Links           []Link                   `json:"links,omitempty"`
	OsDcfDiskConfig string                   `json:"OS-DCF:diskConfig,omitempty"`
	SecurityGroup   []map[string]interface{} `json:"security_groups,omitempty"`
}

NewServer structures are used for both requests and responses. The fields discussed below are relevent for server-creation purposes.

The Name field contains the desired name of the server. Note that (at present) Rackspace permits more than one server with the same name; however, software should not depend on this. Not only will Rackspace support thank you, so will your own devops engineers. A name is required.

The ImageRef field contains the ID of the desired software image to place on the server. This ID must be found in the image slice returned by the Images() function. This field is required.

The FlavorRef field contains the ID of the server configuration desired for deployment. This ID must be found in the flavor slice returned by the Flavors() function. This field is required.

For OsDcfDiskConfig, refer to the Image or Server structure documentation. This field defaults to "AUTO" if not explicitly provided.

Metadata contains a small key/value association of arbitrary data. Neither Rackspace nor OpenStack places significance on this field in any way. This field defaults to an empty map if not provided.

Personality specifies the contents of certain files in the server's filesystem. The files and their contents are mapped through a slice of FileConfig structures. If not provided, all filesystem entities retain their image-specific configuration.

Networks specifies an affinity for the server's various networks and interfaces. Networks are identified through UUIDs; see NetworkConfig structure documentation for more details. If not provided, network affinity is determined automatically.

The AdminPass field may be used to provide a root- or administrator-password during the server provisioning process. If not provided, a random password will be automatically generated and returned in this field.

The following fields are intended to be used to communicate certain results about the server being provisioned. When attempting to create a new server, these fields MUST not be provided. They'll be filled in by the response received from the Rackspace APIs.

The Id field contains the server's unique identifier. The identifier's scope is best assumed to be bound by the user's account, unless other arrangements have been made with Rackspace.

The SecurityGroup field allows the user to specify a security group at launch.

Any Links provided are used to refer to the server specifically by URL. These links are useful for making additional REST calls not explicitly supported by Gorax.

type NewServerSettings 

type NewServerSettings struct {
	Name       string `json:"name,omitempty"`
	AccessIPv4 string `json:"accessIPv4,omitempty"`
	AccessIPv6 string `json:"accessIPv6,omitempty"`
}

NewServerSettings structures record those fields of the Server structure to change when updating a server (see UpdateServer method).

type PasswordCredentials 

type PasswordCredentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

PasswordCredentials provides a JSON encoding wrapper for passing credentials to the Identity service. You will not work with this structure directly.

type Provider 

type Provider struct {
	AuthEndpoint string
}

Provider structures exist for each tangible provider of OpenStack service. For example, Rackspace, Hewlett-Packard, and NASA might have their own instance of this structure.

At a minimum, a provider must expose an authentication endpoint.

type RaxBandwidth 

type RaxBandwidth struct {
	AuditPeriodEnd    string `json:"audit_period_end"`
	AuditPeriodStart  string `json:"audit_period_start"`
	BandwidthInbound  int64  `json:"bandwidth_inbound"`
	BandwidthOutbound int64  `json:"bandwidth_outbound"`
	Interface         string `json:"interface"`
}

RaxBandwidth provides measurement of server bandwidth consumed over a given audit interval.

type ReauthHandlerFunc 

type ReauthHandlerFunc func(AccessProvider) error

ReauthHandlerFunc functions are responsible for somehow performing the task of reauthentication.

type ResizeRequest 

type ResizeRequest struct {
	Name       string `json:"name,omitempty"`
	FlavorRef  string `json:"flavorRef"`
	DiskConfig string `json:"OS-DCF:diskConfig,omitempty"`
}

ResizeRequest structures are used internally to encode to JSON the parameters required to resize a server instance. Client applications will not use this structure (no API accepts an instance of this structure). See the Region method ResizeServer() for more details on how to resize a server.

type Role 

type Role struct {
	Description, Id, Name string
}

Role encapsulates a permission that a user can rely on.

type SGRule added in v0.1.0 

type SGRule struct {
	FromPort   int                    `json:"from_port,omitempty"`
	Id         int                    `json:"id,omitempty"`
	IpProtocol string                 `json:"ip_protocol,omitempty"`
	IpRange    map[string]interface{} `json:"ip_range,omitempty"`
	ToPort     int                    `json:"to_port,omitempty"`
}

SGRule encapsulates a single rule which applies to a security group. This definition is just a guess, based on the documentation found in another extension here: http://docs.openstack.org/api/openstack-compute/2/content/GET_os-security-group-default-rules-v2_listSecGroupDefaultRules_v2__tenant_id__os-security-group-rules_ext-os-security-group-default-rules.html

type SecurityGroup added in v0.1.0 

type SecurityGroup struct {
	Description string   `json:"description,omitempty"`
	Id          int      `json:"id,omitempty"`
	Name        string   `json:"name,omitempty"`
	Rules       []SGRule `json:"rules,omitempty"`
	TenantId    string   `json:"tenant_id,omitempty"`
}

SecurityGroup provides a description of a security group, including all its rules.

type Server 

type Server struct {
	AccessIPv4         string `json:"accessIPv4"`
	AccessIPv6         string `json:"accessIPv6"`
	Addresses          AddressSet
	Created            string            `json:"created"`
	Flavor             FlavorLink        `json:"flavor"`
	HostId             string            `json:"hostId"`
	Id                 string            `json:"id"`
	Image              ImageLink         `json:"image"`
	Links              []Link            `json:"links"`
	Metadata           map[string]string `json:"metadata"`
	Name               string            `json:"name"`
	Progress           int               `json:"progress"`
	Status             string            `json:"status"`
	TenantId           string            `json:"tenant_id"`
	Updated            string            `json:"updated"`
	UserId             string            `json:"user_id"`
	OsDcfDiskConfig    string            `json:"OS-DCF:diskConfig"`
	RaxBandwidth       []RaxBandwidth    `json:"rax-bandwidth:bandwidth"`
	OsExtStsPowerState int               `json:"OS-EXT-STS:power_state"`
	OsExtStsTaskState  string            `json:"OS-EXT-STS:task_state"`
	OsExtStsVmState    string            `json:"OS-EXT-STS:vm_state"`

	RawAddresses map[string]interface{} `json:"addresses"`
}

Server records represent (virtual) hardware instances (not configurations) accessible by the user.

The AccessIPv4 / AccessIPv6 fields provides IP addresses for the server in the IPv4 or IPv6 format, respectively.

Addresses provides addresses for any attached isolated networks. The version field indicates whether the IP address is version 4 or 6. Note: only public and private pools appear here. To get the complete set, use the AllAddressPools() method instead.

Created tells when the server entity was created.

The Flavor field includes the flavor ID and flavor links.

The compute provisioning algorithm has an anti-affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. The HostId field represents the host your server runs on and can be used to determine this scenario if it is relevant to your application. Note that HostId is unique only per account; it is not globally unique.

Id provides the server's unique identifier. This field must be treated opaquely.

Image indicates which image is installed on the server.

Links provides one or more means of accessing the server.

Metadata provides a small key-value store for application-specific information.

Name provides a human-readable name for the server.

Progress indicates how far along it is towards being provisioned. 100 represents complete, while 0 represents just beginning.

Status provides an indication of what the server's doing at the moment. A server will be in ACTIVE state if it's ready for use.

OsDcfDiskConfig indicates the server's boot volume configuration. Valid values are: 

AUTO
----
The server is built with a single partition the size of the target flavor disk.
The file system is automatically adjusted to fit the entire partition.
This keeps things simple and automated.
AUTO is valid only for images and servers with a single partition that use the EXT3 file system.
This is the default setting for applicable Rackspace base images.

MANUAL
------
The server is built using whatever partition scheme and file system is in the source image.
If the target flavor disk is larger,
the remaining disk space is left unpartitioned.
This enables images to have non-EXT3 file systems, multiple partitions, and so on,
and enables you to manage the disk configuration.

RaxBandwidth provides measures of the server's inbound and outbound bandwidth per interface.

OsExtStsPowerState provides an indication of the server's power. This field appears to be a set of flag bits: 

  ... 4  3   2   1   0
+--//--+---+---+---+---+
| .... | 0 | S | 0 | I |
+--//--+---+---+---+---+
             |       |
             |       +---  0=Instance is down.
             |             1=Instance is up.
             |
             +-----------  0=Server is switched ON.
                           1=Server is switched OFF.
                           (note reverse logic.)

Unused bits should be ignored when read, and written as 0 for future compatibility.

OsExtStsTaskState and OsExtStsVmState work together to provide visibility in the provisioning process for the instance. Consult Rackspace documentation at http://docs.rackspace.com/servers/api/v2/cs-devguide/content/ch_extensions.html#ext_status for more details. It's too lengthy to include here.

func (*Server) AllAddressPools added in v0.1.0 

func (s *Server) AllAddressPools() (map[string][]VersionedAddress, error)

AllAddressPools returns a complete set of address pools available on the server. The name of each pool supported keys the map. The value of the map contains the addresses provided in the corresponding pool.

type ServiceCatalogerForIdentityV2 

type ServiceCatalogerForIdentityV2 interface {
	V2ServiceCatalog() []CatalogEntry
}

ServiceCatalogerIdentityV2 interface provides direct access to the service catalog as offered by the Identity V2 API. We regret we need to fracture the namespace of what should otherwise be a simple concept; however, the OpenStack community saw fit to render V3's service catalog completely incompatible with V2.

type Tenant 

type Tenant struct {
	Id, Name string
}

Tenant encapsulates tenant authentication information. If, after authentication, no tenant information is supplied, both Id and Name will be "".

type Token 

type Token struct {
	Id, Expires string
	Tenant      Tenant
}

Token encapsulates an authentication token and when it expires. It also includes tenant information if available.

type User 

type User struct {
	Id, Name          string
	XRaxDefaultRegion string `json:"RAX-AUTH:defaultRegion"`
	Roles             []Role
}

User encapsulates the user credentials, and provides visibility in what the user can do through its role assignments.

type VersionedAddress 

type VersionedAddress struct {
	Addr    string `json:"addr"`
	Version int    `json:"version"`
}

A VersionedAddress denotes either an IPv4 or IPv6 (depending on version indicated) address.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.