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
- Variables
- func ActualResponseCode(e error) (int, error)
- type Access
- type AccessProvider
- type AddressSet
- type ApiCriteria
- type ApiKeyCredentials
- type Auth
- type AuthContainer
- type AuthError
- type AuthOptions
- type CatalogEntry
- type CloudServersProvider
- type Context
- func (c *Context) Authenticate(provider string, options AuthOptions) (*Access, error)
- func (c *Context) ProviderByName(name string) (p Provider, err error)
- func (c *Context) RegisterProvider(name string, p Provider) error
- func (c *Context) ResponseWithReauth(ap AccessProvider, f func() (*perigee.Response, error)) (*perigee.Response, error)
- func (c *Context) ServersApi(provider AccessProvider, criteria ApiCriteria) (CloudServersProvider, error)
- func (c *Context) UseCustomClient(hc *http.Client) *Context
- func (c *Context) WithProvider(name string, p Provider) *Context
- func (c *Context) WithReauth(ap AccessProvider, f func() error) error
- func (c *Context) WithReauthHandler(f ReauthHandlerFunc) *Context
- type CreateImage
- type EntryEndpoint
- type FileConfig
- type Flavor
- type FlavorLink
- type FloatingIp
- type Image
- type ImageLink
- type KeyPair
- type Link
- type NetworkAddress
- type NetworkConfig
- type NewKeyPair
- type NewServer
- type NewServerSettings
- type PasswordCredentials
- type Provider
- type RaxBandwidth
- type ReauthHandlerFunc
- type ResizeRequest
- type Role
- type SGRule
- type SecurityGroup
- type Server
- type ServiceCatalogerForIdentityV2
- type Tenant
- type Token
- type User
- type VersionedAddress
Constants ¶
const ( PublicURL = iota InternalURL )
The choices available for UrlChoice. See the ApiCriteria structure for details.
Variables ¶
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.
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.
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.
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.
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.
var OpenstackApi = map[string]interface{}{ "Type": "compute", "UrlChoice": PublicURL, }
The default generic openstack api
var RackspaceApi = map[string]interface{}{ "Name": "cloudServersOpenStack", "VersionId": "2", "UrlChoice": PublicURL, }
Api for use with rackspace
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 ¶
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) FirstEndpointUrlByCriteria ¶
func (a *Access) FirstEndpointUrlByCriteria(ac ApiCriteria) string
See AccessProvider interface definition for details.
func (*Access) Reauthenticate ¶
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) 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 ¶
func PopulateApi(variant string) (ApiCriteria, error)
Populates an ApiCriteria struct with the api values from one of the api maps
type ApiKeyCredentials ¶
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) // ListServersByFilters provides a list of servers hosted by the user in a // given region. This function let you requests servers by certain URI // paramaters defined by the API endpoint. This is sometimes more suitable // if you have many servers and you only want to pick servers on certain // criterias. An example usage could be : // // filter := url.Values{} // filter.Set("name", "MyServer") // filter.Set("status", "ACTIVE") // // filteredServers, err := c.ListServersByFilters(filter) // // Here, filteredServers only contains servers whose name started with // "MyServer" and are in "ACTIVE" status. ListServersByFilter(filter url.Values) ([]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 ¶
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 ¶
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(provider AccessProvider, criteria ApiCriteria) (CloudServersProvider, error)
Instantiates a Cloud Servers API for the provider given.
func (*Context) UseCustomClient ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
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 ¶
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 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 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"` ConfigDrive bool `json:"config_drive"` UserData string `json:"user_data"` }
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
A VersionedAddress denotes either an IPv4 or IPv6 (depending on version indicated) address.