google

package
v0.0.0-...-a002913 Latest Latest
Warning

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

Go to latest
Published: Oct 2, 2015 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	OSEnvPrivateKey    = "GCE_PRIVATE_KEY"
	OSEnvClientID      = "GCE_CLIENT_ID"
	OSEnvClientEmail   = "GCE_CLIENT_EMAIL"
	OSEnvRegion        = "GCE_REGION"
	OSEnvProjectID     = "GCE_PROJECT_ID"
	OSEnvImageEndpoint = "GCE_IMAGE_URL"
)

The names of OS environment variables related to GCE.

Note that these are not specified by Google. Instead they are defined by juju for use with the GCE provider. If Google defines equivalent environment variables they should be used instead.

View Source
const (
	StatusDone         = "DONE"
	StatusDown         = "DOWN"
	StatusPending      = "PENDING"
	StatusProvisioning = "PROVISIONING"
	StatusRunning      = "RUNNING"
	StatusStaging      = "STAGING"
	StatusStopped      = "STOPPED"
	StatusStopping     = "STOPPING"
	StatusTerminated   = "TERMINATED"
	StatusUp           = "UP"
)

The various status values used by GCE.

View Source
const MinDiskSizeGB uint64 = 10

MinDiskSizeGB is the minimum/default size (in megabytes) for GCE disks.

Note: GCE does not currently have an official minimum disk size. However, in testing we found the minimum size to be 10 GB due to the image size. See gceapi messsage.

gceapi: Requested disk size cannot be smaller than the image size (10 GB)

View Source
const (
	NetworkAccessOneToOneNAT = "ONE_TO_ONE_NAT" // the default
)

The different kinds of network access.

Variables

This section is empty.

Functions

func FormatAuthorizedKeys

func FormatAuthorizedKeys(rawAuthorizedKeys, user string) (string, error)

FormatAuthorizedKeys returns our authorizedKeys with the username prepended to it. This is the format that GCE expects when we upload sshKeys metadata. The sshKeys metadata is what is used by our scripts and commands like juju ssh to connect to juju machines.

func IsInvalidConfigValue

func IsInvalidConfigValue(err error) bool

IsInvalidConfigValue returns whether or not the provided error is an InvalidConfigValue (or caused by one).

func NewInvalidConfigValue

func NewInvalidConfigValue(key string, value, reason interface{}) error

NewInvalidConfigValue returns a new InvalidConfigValue for the given info. If the provided reason is an error then Reason is set to that error. Otherwise a non-nil value is treated as a string and Reason is set to a non-nil value that wraps it.

func NewMissingConfigValue

func NewMissingConfigValue(key, field string) error

NewMissingConfigValue returns a new error for a missing config field.

Types

type AttachedDisk

type AttachedDisk struct {
	// VolumeName is the name of the volume that is attached, this is unique
	// and used by gce as an identifier.
	VolumeName string
	// DeviceName is the name of the device in the instance, typycally
	// is reflected into the /dev/disk/by-id/google-*
	DeviceName string
	// Mode is the read/write mode of the disk.
	Mode DiskMode
}

AttachedDisk represents a disk that is attached to an instance.

type AvailabilityZone

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

AvailabilityZone represents a single GCE zone. It satisfies the {provider/common}.AvailabilityZone interface.

func NewZone

func NewZone(name, status, state, replacement string) AvailabilityZone

NewZone build an availability zone from the provided name, status state, and replacement and returns it.

func (AvailabilityZone) Available

func (z AvailabilityZone) Available() bool

Available returns whether or not the zone is available for provisioning.

func (AvailabilityZone) Deprecated

func (z AvailabilityZone) Deprecated() bool

Deprecated returns true if the zone has been deprecated.

func (AvailabilityZone) Name

func (z AvailabilityZone) Name() string

Name returns the zone's name.

func (AvailabilityZone) Status

func (z AvailabilityZone) Status() string

Status returns the status string for the zone. It will match one of the Status* constants defined in the package.

type Connection

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

Connection provides methods for interacting with the GCE API. The methods are limited to those needed by the juju GCE provider.

Before calling any of the methods, the Connect method should be called to authenticate and open the raw connection to the GCE API. Otherwise a panic will result.

func Connect

func Connect(connCfg ConnectionConfig, creds *Credentials) (*Connection, error)

Connect authenticates using the provided credentials and opens a low-level connection to the GCE API for the Connection. Calling Connect after a successful connection has already been made will result in an error. All errors that happen while authenticating and connecting are returned by Connect.

func (*Connection) AddInstance

func (gce *Connection) AddInstance(spec InstanceSpec, zones ...string) (*Instance, error)

AddInstance creates a new instance based on the spec's data and returns it. The instance will be created using the provided connection and in one of the provided zones.

func (*Connection) AttachDisk

func (gce *Connection) AttachDisk(zone, volumeName, instanceId string, mode DiskMode) (*AttachedDisk, error)

AttachDisk implements storage section of gceConnection.

func (*Connection) AvailabilityZones

func (gc *Connection) AvailabilityZones(region string) ([]AvailabilityZone, error)

AvailabilityZones returns the list of availability zones for a given GCE region. If none are found the the list is empty. Any failure in the low-level request is returned as an error.

func (Connection) ClosePorts

func (gce Connection) ClosePorts(fwname string, ports ...network.PortRange) error

ClosePorts sends a request to the GCE API to close the provided port ranges on the named firewall. If the firewall does not exist nothing happens. If the firewall is left with no ports then it is removed. Otherwise it will be left with just the open ports it has that do not match the provided port ranges. The call blocks until the ports are closed or the request fails.

func (*Connection) CreateDisks

func (gce *Connection) CreateDisks(zone string, disks []DiskSpec) ([]*Disk, error)

CreateDisks implements storage section of gceConnection.

func (*Connection) DetachDisk

func (gce *Connection) DetachDisk(zone, instanceId, volumeName string) error

DetachDisk implements storage section of gceConnection. disk existence is checked but not instance nor is attachment.

func (*Connection) Disk

func (gce *Connection) Disk(zone, name string) (*Disk, error)

Disk implements storage section of gceConnection.

func (*Connection) Disks

func (gce *Connection) Disks(zone string) ([]*Disk, error)

Disks implements storage section of gceConnection.

func (*Connection) Instance

func (gce *Connection) Instance(id, zone string) (Instance, error)

Instance gets the up-to-date info about the given instance and returns it.

func (*Connection) InstanceDisks

func (gce *Connection) InstanceDisks(zone, instanceId string) ([]*AttachedDisk, error)

InstanceDisks implements storage section of gceConnection.

func (*Connection) Instances

func (gce *Connection) Instances(prefix string, statuses ...string) ([]Instance, error)

Instances sends a request to the GCE API for a list of all instances (in the Connection's project) for which the name starts with the provided prefix. The result is also limited to those instances with one of the specified statuses (if any).

func (Connection) OpenPorts

func (gce Connection) OpenPorts(fwname string, ports ...network.PortRange) error

OpenPorts sends a request to the GCE API to open the provided port ranges on the named firewall. If the firewall does not exist yet it is created, with the provided port ranges opened. Otherwise the existing firewall is updated to add the provided port ranges to the ports it already has open. The call blocks until the ports are opened or the request fails.

func (Connection) Ports

func (gce Connection) Ports(fwname string) ([]network.PortRange, error)

Ports build a list of all open port ranges for a given firewall name (within the Connection's project) and returns it. If the firewall does not exist then the list will be empty and no error is returned.

func (*Connection) RemoveDisk

func (gce *Connection) RemoveDisk(zone, name string) error

RemoveDisk implements storage section of gceConnection. TODO(perrito666) handle non existing disk, perhaps catch 404.

func (*Connection) RemoveInstances

func (gce *Connection) RemoveInstances(prefix string, ids ...string) error

RemoveInstances sends a request to the GCE API to terminate all instances (in the Connection's project) that match one of the provided IDs. If a prefix is provided, only IDs that start with the prefix will be considered. The call blocks until all the instances are removed or the request fails.

func (Connection) VerifyCredentials

func (gc Connection) VerifyCredentials() error

VerifyCredentials ensures that the authentication credentials used to connect are valid for use in the project and region defined for the Connection. If they are not then an error is returned.

type ConnectionConfig

type ConnectionConfig struct {
	// Region is the GCE region in which to operate for the connection.
	Region string

	// ProjectID is the project ID to use in all GCE API requests for
	// the connection.
	ProjectID string
}

ConnectionConfig contains the config values used for a connection to the GCE API.

func (ConnectionConfig) Validate

func (gc ConnectionConfig) Validate() error

Validate checks the connection's fields for invalid values. If the values are not valid, it returns a config.InvalidConfigValue error with the key set to the corresponding OS environment variable name.

To be considered valid, each of the connection's must be set to some non-empty value.

type Credentials

type Credentials struct {
	// JSONKey is the content of the JSON key file for these credentials.
	JSONKey []byte

	// ClientID is the GCE account's OAuth ID. It is part of the OAuth
	// config used in the OAuth-wrapping network transport.
	ClientID string

	// ClientEmail is the email address associatd with the GCE account.
	// It is used to generate a new OAuth token to use in the
	// OAuth-wrapping network transport.
	ClientEmail string

	// PrivateKey is the private key that matches the public key
	// associatd with the GCE account. It is used to generate a new
	// OAuth token to use in the OAuth-wrapping network transport.
	PrivateKey []byte
}

Credentials holds the OAuth2 credentials needed to authenticate on GCE.

func NewCredentials

func NewCredentials(values map[string]string) (*Credentials, error)

NewCredentials returns a new Credentials based on the provided values. The keys must be recognized OS env var names for the different credential fields.

func ParseJSONKey

func ParseJSONKey(jsonKeyFile io.Reader) (*Credentials, error)

ParseJSONKey returns a new Credentials with values based on the provided JSON key file contents.

func (Credentials) Validate

func (gc Credentials) Validate() error

Validate checks the credentialss for invalid values. If the values are not valid, it returns errors.NotValid with the message set to the corresponding OS environment variable name.

To be considered valid, each of the credentials must be set to some non-empty value. Furthermore, ClientEmail must be a proper email address.

func (Credentials) Values

func (gc Credentials) Values() map[string]string

Values returns the credentials as a simple mapping with the corresponding OS env variable names as the keys.

type Disk

type Disk struct {
	// Id is an unique identifier google adds to the disk, it usually
	// is not used in the API.
	Id uint64
	// Name is a unique identifier string for each disk.
	Name string
	// Size is the size in mbit.
	Size uint64
	// Type is one of the available disk types supported by
	// gce (persistent or ephemeral).
	Type DiskType
	// Zone indicates the zone in which the disk lives.
	Zone string
	// DiskStatus holds the status of he aforementioned disk.
	Status DiskStatus
}

Disk represents a gce disk.

func NewDisk

func NewDisk(cd *compute.Disk) *Disk

type DiskMode

type DiskMode string
const (
	ModeRW DiskMode = "READ_WRITE"
	ModeRO DiskMode = "READ_ONLY"
)

The different disk modes supported by GCE.

type DiskSpec

type DiskSpec struct {
	// SizeHintGB is the requested disk size in Gigabytes. It must be
	// greater than 0.
	SizeHintGB uint64
	// ImageURL is the location of the image to which the disk should
	// be initialized.
	ImageURL string
	// Boot indicates that this is a boot disk. An instance may only
	// have one boot disk. (attached only)
	Boot bool
	// Scratch indicates that the disk should be a "scratch" disk
	// instead of a "persistent" disk (the default).
	Scratch bool
	// Readonly indicates that the disk should not support writes.
	Readonly bool
	// AutoDelete indicates that the attached disk should be removed
	// when the instance to which it is attached is removed.
	AutoDelete bool
	// PersistenDiskType is exclusive to persistent disks and indicates which of the
	// persistent types available this disk should be.
	PersistentDiskType DiskType
	// Name: Name of the resource; provided by the client when the resource
	// is created. The name must be 1-63 characters long, and comply with
	// RFC1035. Specifically, the name must be 1-63 characters long and
	// match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means
	// the first character must be a lowercase letter, and all following
	// characters must be a dash, lowercase letter, or digit, except the
	// last character, which cannot be a dash.
	Name string
}

DiskSpec holds all the data needed to request a new disk on GCE. Some fields are used only for attached disks (i.e. in association with instances).

func (*DiskSpec) SizeGB

func (ds *DiskSpec) SizeGB() uint64

SizeGB returns the disk size to use for a new disk. The size hint is returned if it isn't too small (otherwise the min size is returned).

func (*DiskSpec) TooSmall

func (ds *DiskSpec) TooSmall() bool

TooSmall checks the spec's size hint and indicates whether or not it is smaller than the minimum disk size.

type DiskStatus

type DiskStatus string
const (
	StatusCreating  DiskStatus = "CREATING"
	StatusFailed    DiskStatus = "FAILED"
	StatusReady     DiskStatus = "READY"
	StatusRestoring DiskStatus = "RESTORING"
)

type DiskType

type DiskType string
const (
	// persistent
	DiskPersistentStandard DiskType = "pd-standard"
	DiskPersistentSSD      DiskType = "pd-ssd"
	// scratch
	DiskLocalSSD DiskType = "local-ssd"
)

The types of disk supported by GCE

type Instance

type Instance struct {
	InstanceSummary
	// contains filtered or unexported fields
}

Instance represents a single realized GCE compute instance.

func NewInstance

func NewInstance(summary InstanceSummary, spec *InstanceSpec) *Instance

NewInstance builds an instance from the provided summary and spec and returns it.

func (Instance) Addresses

func (gi Instance) Addresses() []network.Address

Addresses identifies information about the network addresses associated with the instance and returns it.

func (Instance) Metadata

func (gi Instance) Metadata() map[string]string

Metadata returns the user-specified metadata for the instance.

func (Instance) RootDisk

func (gi Instance) RootDisk() *compute.AttachedDisk

RootDisk returns an AttachedDisk

func (Instance) RootDiskGB

func (gi Instance) RootDiskGB() uint64

RootDiskGB returns the size of the instance's root disk. If it cannot be determined then 0 is returned.

func (Instance) Status

func (gi Instance) Status() string

Status returns a string identifying the status of the instance. The value will match one of the Status* constants in the package.

type InstanceSpec

type InstanceSpec struct {
	// ID is the "name" of the instance.
	ID string
	// Type is the name of the GCE instance type. The value is resolved
	// relative to an availability zone when the API request is sent.
	// The type must match one of the GCE-recognized types.
	Type string
	// Disks holds the information needed to request each of the disks
	// that should be attached to a new instance. This must include a
	// single root disk.
	Disks []DiskSpec
	// Network identifies the information for the network that a new
	// instance should use. If the network does not exist then it will
	// be added when the instance is. At least the network's name must
	// be set.
	Network NetworkSpec
	// NetworkInterfaces is the names of the network interfaces to
	// associate with the instance. They will be connected to the the
	// network identified by the instance spec. At least one name must
	// be provided.
	NetworkInterfaces []string
	// Metadata is the GCE instance "user-specified" metadata that will
	// be initialized on the new instance.
	Metadata map[string]string
	// Tags are the labels to associate with the instance. This is
	// useful when making bulk calls or in relation to some API methods
	// (e.g. related to firewalls access rules).
	Tags []string
}

InstanceSpec holds all the information needed to create a new GCE instance within some zone. TODO(ericsnow) Validate the invariants?

func (InstanceSpec) RootDisk

func (is InstanceSpec) RootDisk() *compute.AttachedDisk

RootDisk identifies the root disk for a given instance (or instance spec) and returns it. If the root disk could not be determined then nil is returned. TODO(ericsnow) Return an error?

func (InstanceSpec) Summary

func (is InstanceSpec) Summary() InstanceSummary

Summary builds an InstanceSummary based on the spec and returns it.

type InstanceSummary

type InstanceSummary struct {
	// ID is the "name" of the instance.
	ID string
	// ZoneName is the unqualified name of the zone in which the
	// instance was provisioned.
	ZoneName string
	// Status holds the status of the instance at a certain point in time.
	Status string
	// Metadata is the instance metadata.
	Metadata map[string]string
	// Addresses are the IP Addresses associated with the instance.
	Addresses []network.Address
}

InstanceSummary captures all the data needed by Instance.

type InvalidConfigValue

type InvalidConfigValue struct {
	errors.Err

	// Key is the OS env var corresponding to the field with the bad value.
	Key string

	// Value is the invalid value.
	Value interface{}

	// Reason is the underlying error.
	Reason error
	// contains filtered or unexported fields
}

InvalidConfigValue indicates that one of the config values failed validation.

func (*InvalidConfigValue) Cause

func (err *InvalidConfigValue) Cause() error

Cause implements errors.causer. This is necessary so that errors.IsNotValid works.

func (InvalidConfigValue) Error

func (err InvalidConfigValue) Error() string

Error implements error.

func (InvalidConfigValue) Underlying

func (err InvalidConfigValue) Underlying() error

Underlying implements errors.wrapper.

type NetworkSpec

type NetworkSpec struct {
	// Name is the unqualified name of the network.
	Name string
}

NetworkSpec holds all the information needed to identify and create a GCE network.

func (*NetworkSpec) Path

func (ns *NetworkSpec) Path() string

Path returns the qualified name of the network.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL