google

package
v0.0.0-...-4bd6544 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2016 License: AGPL-3.0 Imports: 19 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 (
	NetworkAccessOneToOneNAT = "ONE_TO_ONE_NAT" // the default
)

The different kinds of network access.

Variables

This section is empty.

Functions

func IsInvalidConfigValueError 

func IsInvalidConfigValueError(err error) bool

IsInvalidConfigValueError returns whether or not the cause of the provided error is a *InvalidConfigValueError.

func MinDiskSizeGB 

func MinDiskSizeGB(ser string) uint64

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 for ubuntu and 50 GB for windows due to the image size. See gceapi message.

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

func NewInvalidConfigValueError 

func NewInvalidConfigValueError(key, value string, reason error) error

NewInvalidConfigValueError returns a new InvalidConfigValueError 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.InvalidConfigValueError 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

	// ProjectID is the GCE project's ID that these credentials relate to.
	ProjectID 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
	// Description holds the description field for a disk, we store env UUID here.
	Description 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 {
	// Series is the OS series on which the disk size depends
	Series string
	// 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
	// Description holds a description of the disk, it currently holds
	// modelUUID.
	// This field is used instead of a tag or metadata because, at the moment of writing
	// this feature, compute (v1) API does not support any way to add extra data
	// to disks.
	// Description was picked because it is not mutable (actually no field is) for disks.
	// There is a metadata API but it is not supported for disks for the moment.
	Description 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 InvalidConfigValueError 

type InvalidConfigValueError 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{}
}

InvalidConfigValueError indicates that one of the config values failed validation.

func (*InvalidConfigValueError) Cause 

func (err *InvalidConfigValueError) Cause() error

Cause implements errors.Causer.Cause.

func (InvalidConfigValueError) Error 

func (err InvalidConfigValueError) Error() string

Error implements error.

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.

Source Files

View all Source files

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.