Version: v0.0.0-...-a002913 Latest Latest

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

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




This section is empty.


View Source
var (
	ErrNotBootstrapped     = errors.New("environment is not bootstrapped")
	ErrAlreadyBootstrapped = errors.New("environment is already bootstrapped")
	ErrNoInstances         = errors.NotFoundf("instances")
	ErrPartialInstances    = errors.New("only some instances were found")

	// Errors indicating that the provider can't allocate an IP address to an
	// instance.
	ErrIPAddressesExhausted = errors.New("can't allocate a new IP address")
	ErrIPAddressUnavailable = errors.New("the requested IP address is unavailable")
View Source
var AddressesRefreshAttempt = utils.AttemptStrategy{
	Total: 3 * time.Minute,
	Delay: 1 * time.Second,

AddressesRefreshAttempt is the attempt strategy used when refreshing instance addresses.

View Source
var EmptyStorage storage.StorageReader = emptyStorage{}

EmptyStorage holds a StorageReader object that contains no files and offers no URLs.

View Source
var (
	InvalidEnvironmentError = fmt.Errorf(
		"environment is not a juju-core environment")
View Source
var PrepareFromName = prepareFromNameProductionFunc

PrepareFromName is the same as NewFromName except that the environment is is prepared as well as opened, and environment information is created using the given store. If the environment is already prepared, it behaves like NewFromName.


func APIInfo

func APIInfo(env Environ) (*api.Info, error)

APIInfo returns an api.Info for the environment. The result is populated with addresses and CA certificate, but no tag or password.

func AddressAllocationEnabled

func AddressAllocationEnabled() bool

AddressAllocationEnabled is a shortcut for checking if the AddressAllocation feature flag is enabled.

func BoilerplateConfig

func BoilerplateConfig() string

BoilerplateConfig returns a sample juju configuration.

func BootstrapConfig

func BootstrapConfig(cfg *config.Config) (*config.Config, error)

BootstrapConfig returns a copy of the supplied configuration with the admin-secret and ca-private-key attributes removed. If the resulting config is not suitable for bootstrapping an environment, an error is returned.

func Destroy

func Destroy(env Environ, store configstore.Storage) error

Destroy destroys the environment and, if successful, its associated configuration data from the given store.

func DestroyInfo

func DestroyInfo(envName string, store configstore.Storage) error

DestroyInfo destroys the configuration data for the named environment from the given store.

func ImageMetadataSources

func ImageMetadataSources(env Environ) ([]simplestreams.DataSource, error)

ImageMetadataSources returns the sources to use when looking for simplestreams image id metadata for the given stream.

func IsEmptyConfig

func IsEmptyConfig(err error) bool

IsEmptyConfig reports whether err is a EmptyConfig.

func IsNoEnv

func IsNoEnv(err error) bool

IsNoEnv reports whether err is a NoEnvError.

func LegacyStorage

func LegacyStorage(st *state.State) (storage.Storage, error)

LegacyStorage creates an Environ from the config in state and returns its provider storage interface if it supports one. If the environment does not support provider storage, then it will return an error satisfying errors.IsNotSupported.

func NewStatePolicy

func NewStatePolicy() state.Policy

NewStatePolicy returns a state.Policy that is implemented in terms of Environ and related types.

func RegisterImageDataSourceFunc

func RegisterImageDataSourceFunc(id string, f ImageDataSourceFunc)

RegisterImageDataSourceFunc registers an ImageDataSourceFunc with the specified id, overwriting any function previously registered with the same id.

func RegisterProvider

func RegisterProvider(name string, p EnvironProvider, alias ...string)

RegisterProvider registers a new environment provider. Name gives the name of the provider, and p the interface to that provider.

RegisterProvider will panic if the provider name or any of the aliases are registered more than once.

func RegisterUserImageDataSourceFunc

func RegisterUserImageDataSourceFunc(id string, f ImageDataSourceFunc)

RegisterUserImageDataSourceFunc registers an ImageDataSourceFunc with the specified id at the start of the search path, overwriting any function previously registered with the same id.

func RegisteredProviders

func RegisteredProviders() []string

RegisteredProviders enumerate all the environ providers which have been registered.

func UnregisterImageDataSourceFunc

func UnregisterImageDataSourceFunc(id string)

UnregisterImageDataSourceFunc unregisters an ImageDataSourceFunc with the specified id.

func WriteEnvirons

func WriteEnvirons(path string, fileContents string) (string, error)

WriteEnvirons creates a new juju environments.yaml file with the specified contents.


type BootstrapContext

type BootstrapContext interface {
	GetStdin() io.Reader
	GetStdout() io.Writer
	GetStderr() io.Writer
	Infof(format string, params ...interface{})
	Verbosef(format string, params ...interface{})

	// InterruptNotify starts watching for interrupt signals
	// on behalf of the caller, sending them to the supplied
	// channel.
	InterruptNotify(sig chan<- os.Signal)

	// StopInterruptNotify undoes the effects of a previous
	// call to InterruptNotify with the same channel. After
	// StopInterruptNotify returns, no more signals will be
	// delivered to the channel.
	StopInterruptNotify(chan<- os.Signal)

	// ShouldVerifyCredentials indicates whether the caller's cloud
	// credentials should be verified.
	ShouldVerifyCredentials() bool

BootstrapContext is an interface that is passed to Environ.Bootstrap, providing a means of obtaining information about and manipulating the context in which it is being invoked.

type BootstrapFinalizer

type BootstrapFinalizer func(BootstrapContext, *instancecfg.InstanceConfig) error

BootstrapFinalizer is a function returned from Environ.Bootstrap. The caller must pass a InstanceConfig with the Tools field set.

type BootstrapParams

type BootstrapParams struct {
	// Constraints are used to choose the initial instance specification,
	// and will be stored in the new environment's state.
	Constraints constraints.Value

	// Placement, if non-empty, holds an environment-specific placement
	// directive used to choose the initial instance.
	Placement string

	// AvailableTools is a collection of tools which the Bootstrap method
	// may use to decide which architecture/series to instantiate.
	AvailableTools tools.List

	// ContainerBridgeName, if non-empty, overrides the default
	// network bridge device to use for LXC and KVM containers. See
	// also instancecfg.DefaultBridgeName.
	ContainerBridgeName string

BootstrapParams holds the parameters for bootstrapping an environment.

type ConfigGetter

type ConfigGetter interface {
	// Config returns the configuration data with which the Environ was created.
	// Note that this is not necessarily current; the canonical location
	// for the configuration data is stored in the state.
	Config() *config.Config

ConfigGetter implements access to an environment's configuration.

type ConfigSource

type ConfigSource int

ConfigSource represents where some configuration data has come from. TODO(rog) remove this when we don't have to support old environments with no configstore info. See lp#1235217

const (
	ConfigFromNowhere ConfigSource = iota

func ConfigForName

func ConfigForName(name string, store configstore.Storage) (*config.Config, ConfigSource, error)

ConfigForName returns the configuration for the environment with the given name from the default environments file. If the name is blank, the default environment will be used. If the configuration is not found, an errors.NotFoundError is returned. If the given store contains an entry for the environment and it has associated bootstrap config, that configuration will be returned. ConfigForName also returns where the configuration was sourced from (this is also valid even when there is an error.

type EmptyConfig

type EmptyConfig struct {
	// contains filtered or unexported fields

EmptyConfig indicates the .jenv file is empty.

type Environ

type Environ interface {
	// Bootstrap creates a new instance with the series and architecture
	// of its choice, constrained to those of the available tools, and
	// returns the instance's architecture, series, and a function that
	// must be called to finalize the bootstrap process by transferring
	// the tools and installing the initial Juju state server.
	// It is possible to direct Bootstrap to use a specific architecture
	// (or fail if it cannot start an instance of that architecture) by
	// using an architecture constraint; this will have the effect of
	// limiting the available tools to just those matching the specified
	// architecture.
	Bootstrap(ctx BootstrapContext, params BootstrapParams) (arch, series string, _ BootstrapFinalizer, _ error)

	// InstanceBroker defines methods for starting and stopping
	// instances.

	// ConfigGetter allows the retrieval of the configuration data.

	// EnvironCapability allows access to this environment's capabilities.

	// ConstraintsValidator returns a Validator instance which
	// is used to validate and merge constraints.
	ConstraintsValidator() (constraints.Validator, error)

	// SetConfig updates the Environ's configuration.
	// Calls to SetConfig do not affect the configuration of
	// values previously obtained from Storage.
	SetConfig(cfg *config.Config) error

	// Instances returns a slice of instances corresponding to the
	// given instance ids.  If no instances were found, but there
	// was no other error, it will return ErrNoInstances.  If
	// some but not all the instances were found, the returned slice
	// will have some nil slots, and an ErrPartialInstances error
	// will be returned.
	Instances(ids []instance.Id) ([]instance.Instance, error)

	// StateServerInstances returns the IDs of instances corresponding
	// to Juju state servers. If there are no state server instances,
	// ErrNoInstances is returned. If it can be determined that the
	// environment has not been bootstrapped, then ErrNotBootstrapped
	// should be returned instead.
	StateServerInstances() ([]instance.Id, error)

	// Destroy shuts down all known machines and destroys the
	// rest of the environment. Note that on some providers,
	// very recently started instances may not be destroyed
	// because they are not yet visible.
	// When Destroy has been called, any Environ referring to the
	// same remote environment may become invalid
	Destroy() error

	// OpenPorts opens the given port ranges for the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	OpenPorts(ports []network.PortRange) error

	// ClosePorts closes the given port ranges for the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	ClosePorts(ports []network.PortRange) error

	// Ports returns the port ranges opened for the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	Ports() ([]network.PortRange, error)

	// Provider returns the EnvironProvider that created this Environ.
	Provider() EnvironProvider


An Environ represents a juju environment as specified in the environments.yaml file.

Due to the limitations of some providers (for example ec2), the results of the Environ methods may not be fully sequentially consistent. In particular, while a provider may retry when it gets an error for an operation, it will not retry when an operation succeeds, even if that success is not consistent with a previous operation.

Even though Juju takes care not to share an Environ between concurrent workers, it does allow concurrent method calls into the provider implementation. The typical provider implementation needs locking to avoid undefined behaviour when the configuration changes.

func New

func New(config *config.Config) (Environ, error)

New returns a new environment based on the provided configuration.

func NewFromAttrs

func NewFromAttrs(attrs map[string]interface{}) (Environ, error)

NewFromAttrs returns a new environment based on the provided configuration attributes. TODO(rog) remove this function - it's almost always wrong to use it.

func NewFromName

func NewFromName(name string, store configstore.Storage) (Environ, error)

NewFromName opens the environment with the given name from the default environments file. If the name is blank, the default environment will be used. If the given store contains an entry for the environment and it has associated bootstrap config, that configuration will be returned.

func Prepare

func Prepare(cfg *config.Config, ctx BootstrapContext, store configstore.Storage) (Environ, error)

Prepare prepares a new environment based on the provided configuration. If the environment is already prepared, it behaves like New.

type EnvironConfigUpgrader

type EnvironConfigUpgrader interface {
	// UpgradeConfig upgrades an old environment configuration by adding,
	// updating or removing attributes. UpgradeConfig must be idempotent,
	// as it may be called multiple times in the event of a partial upgrade.
	// NOTE(axw) this is currently only called when upgrading to 1.25.
	// We should update the upgrade machinery to call this for every
	// version upgrade, so the upgrades package is not tightly coupled
	// to provider upgrades.
	UpgradeConfig(cfg *config.Config) (*config.Config, error)

EnvironConfigUpgrader is an interface that an EnvironProvider may implement in order to modify environment configuration on agent upgrade.

type EnvironProvider

type EnvironProvider interface {
	// RestrictedConfigAttributes are provider specific attributes stored in
	// the config that really cannot or should not be changed across
	// environments running inside a single juju server.
	RestrictedConfigAttributes() []string

	// PrepareForCreateEnvironment prepares an environment for creation. Any
	// additional configuration attributes are added to the config passed in
	// and returned.  This allows providers to add additional required config
	// for new environments that may be created in an existing juju server.
	// Note that this is not called in a client context, so environment variables,
	// local files, etc are not available.
	PrepareForCreateEnvironment(cfg *config.Config) (*config.Config, error)

	// PrepareForBootstrap prepares an environment for use. Any additional
	// configuration attributes in the returned environment should
	// be saved to be used later. If the environment is already
	// prepared, this call is equivalent to Open.
	PrepareForBootstrap(ctx BootstrapContext, cfg *config.Config) (Environ, error)

	// Open opens the environment and returns it.
	// The configuration must have come from a previously
	// prepared environment.
	Open(cfg *config.Config) (Environ, error)

	// Validate ensures that config is a valid configuration for this
	// provider, applying changes to it if necessary, and returns the
	// validated configuration.
	// If old is not nil, it holds the previous environment configuration
	// for consideration when validating changes.
	Validate(cfg, old *config.Config) (valid *config.Config, err error)

	// Boilerplate returns a default configuration for the environment in yaml format.
	// The text should be a key followed by some number of attributes:
	//    `environName:
	//        type: environTypeName
	//        attr1: val1
	//    `
	// The text is used as a template (see the template package) with one extra template
	// function available, rand, which expands to a random hexadecimal string when invoked.
	BoilerplateConfig() string

	// SecretAttrs filters the supplied configuration returning only values
	// which are considered sensitive. All of the values of these secret
	// attributes need to be strings.
	SecretAttrs(cfg *config.Config) (map[string]string, error)

A EnvironProvider represents a computing and storage provider.

func Provider

func Provider(providerType string) (EnvironProvider, error)

Provider returns the previously registered provider with the given type.

type EnvironStorage

type EnvironStorage interface {
	// Storage returns storage specific to the environment.
	Storage() storage.Storage

EnvironStorage implements storage access for an environment.

type Environs

type Environs struct {
	Default string // The name of the default environment.
	// contains filtered or unexported fields

Environs holds information about each named environment in an environments.yaml file.

func ReadEnvirons

func ReadEnvirons(path string) (*Environs, error)

ReadEnvirons reads the juju environments.yaml file and returns the result of running ParseEnvironments on the file's contents. If path is empty, $HOME/.juju/environments.yaml is used.

func ReadEnvironsBytes

func ReadEnvironsBytes(data []byte) (*Environs, error)

ReadEnvironsBytes parses the contents of an environments.yaml file and returns its representation. An environment with an unknown type will only generate an error when New is called for that environment. Attributes for environments with known types are checked.

func (*Environs) Config

func (envs *Environs) Config(name string) (*config.Config, error)

Config returns the environment configuration for the environment with the given name. If the configuration is not found, an errors.NotFoundError is returned.

func (*Environs) Names

func (e *Environs) Names() (names []string)

Names returns the list of environment names.

type ImageDataSourceFunc

type ImageDataSourceFunc func(Environ) (simplestreams.DataSource, error)

ImageDataSourceFunc is a function type that takes an environment and returns a simplestreams datasource.

ImageDataSourceFunc will be used in ImageMetadataSources. Any error satisfying errors.IsNotSupported will be ignored; any other error will be cause ImageMetadataSources to fail.

type InstanceBroker

type InstanceBroker interface {
	// StartInstance asks for a new instance to be created, associated with
	// the provided config in machineConfig. The given config describes the juju
	// state for the new instance to connect to. The config MachineNonce, which must be
	// unique within an environment, is used by juju to protect against the
	// consequences of multiple instances being started with the same machine
	// id.
	StartInstance(args StartInstanceParams) (*StartInstanceResult, error)

	// StopInstances shuts down the instances with the specified IDs.
	// Unknown instance IDs are ignored, to enable idempotency.
	StopInstances(...instance.Id) error

	// AllInstances returns all instances currently known to the broker.
	AllInstances() ([]instance.Instance, error)

	// MaintainInstance is used to run actions on jujud startup for existing
	// instances. It is currently only used to ensure that LXC hosts have the
	// correct network configuration.
	MaintainInstance(args StartInstanceParams) error

TODO(wallyworld) - we want this in the environs/instance package but import loops stop that from being possible right now.

type InstanceTagger

type InstanceTagger interface {
	// TagInstance tags the given instance with the specified tags.
	// The specified tags will replace any existing ones with the
	// same names, but other existing tags will be left alone.
	TagInstance(id instance.Id, tags map[string]string) error

InstanceTagger is an interface that can be used for tagging instances.

type Networking

type Networking interface {
	// AllocateAddress requests a specific address to be allocated for the
	// given instance on the given subnet.
	AllocateAddress(instId instance.Id, subnetId network.Id, addr network.Address, macAddress, hostname string) error

	// ReleaseAddress releases a specific address previously allocated with
	// AllocateAddress.
	ReleaseAddress(instId instance.Id, subnetId network.Id, addr network.Address, macAddress string) error

	// Subnets returns basic information about subnets known
	// by the provider for the environment.
	Subnets(inst instance.Id, subnetIds []network.Id) ([]network.SubnetInfo, error)

	// NetworkInterfaces requests information about the network
	// interfaces on the given instance.
	NetworkInterfaces(instId instance.Id) ([]network.InterfaceInfo, error)

	// SupportsAddressAllocation returns whether the given subnetId
	// supports static IP address allocation using AllocateAddress and
	// ReleaseAddress. If subnetId is network.AnySubnet, the provider
	// can decide whether it can return true or a false and an error
	// (e.g. "subnetId must be set").
	SupportsAddressAllocation(subnetId network.Id) (bool, error)

	// SupportsSpaces returns whether the current environment supports spaces. The
	// returned error satisfies errors.IsNotSupported(), unless a general API failure occurs.
	SupportsSpaces() (bool, error)

Networking interface defines methods that environments with networking capabilities must implement.

type NetworkingEnviron

type NetworkingEnviron interface {
	// Environ represents a juju environment.

	// Networking defines the methods of networking capable environments.

NetworkingEnviron combines the standard Environ interface with the functionality for networking.

func SupportsNetworking

func SupportsNetworking(environ Environ) (NetworkingEnviron, bool)

SupportsNetworking is a convenience helper to check if an environment supports networking. It returns an interface containing Environ and Networking in this case.

type NoEnvError

type NoEnvError struct {
	// contains filtered or unexported fields

NoEnvError indicates the default environment config file is missing.

type ProviderRegistry

type ProviderRegistry interface {
	// RegisterProvider registers a new environment provider with the given
	// name, and zero or more aliases. If a provider already exists with the
	// given name or alias, an error will be returned.
	RegisterProvider(p EnvironProvider, providerType string, providerTypeAliases ...string) error

	// RegisteredProviders returns the names of the registered environment
	// providers.
	RegisteredProviders() []string

	// Provider returns the environment provider with the specified name.
	Provider(providerType string) (EnvironProvider, error)

ProviderRegistry is an interface that provides methods for registering and obtaining environment providers by provider name.

func GlobalProviderRegistry

func GlobalProviderRegistry() ProviderRegistry

GlobalProviderRegistry returns the global provider registry.

type StartInstanceParams

type StartInstanceParams struct {
	// Constraints is a set of constraints on
	// the kind of instance to create.
	Constraints constraints.Value

	// Tools is a list of tools that may be used
	// to start a Juju agent on the machine.
	Tools tools.List

	// InstanceConfig describes the machine's configuration.
	InstanceConfig *instancecfg.InstanceConfig

	// Placement, if non-empty, contains an environment-specific
	// placement directive that may be used to decide how the
	// instance should be started.
	Placement string

	// DistributionGroup, if non-nil, is a function
	// that returns a slice of instance.Ids that belong
	// to the same distribution group as the machine
	// being provisioned. The InstanceBroker may use
	// this information to distribute instances for
	// high availability.
	DistributionGroup func() ([]instance.Id, error)

	// Volumes is a set of parameters for volumes that should be created.
	// StartInstance need not check the value of the Attachment field,
	// as it is guaranteed that any volumes in this list are designated
	// for attachment to the instance being started.
	Volumes []storage.VolumeParams

	// NetworkInfo is an optional list of network interface details,
	// necessary to configure on the instance.
	NetworkInfo []network.InterfaceInfo

	// SubnetsToZones is an optional map of provider-specific subnet
	// id to a list of availability zone names the subnet is available
	// in. It is only populated when valid positive spaces constraints
	// are present.
	SubnetsToZones map[network.Id][]string

StartInstanceParams holds parameters for the InstanceBroker.StartInstance method.

type StartInstanceResult

type StartInstanceResult struct {
	// Instance is an interface representing a cloud instance.
	Instance instance.Instance

	// HardwareCharacteristics represents the hardware characteristics
	// of the newly created instance.
	Hardware *instance.HardwareCharacteristics

	// NetworkInfo contains information about how to configure network
	// interfaces on the instance. Depending on the provider, this
	// might be the same StartInstanceParams.NetworkInfo or may be
	// modified as needed.
	NetworkInfo []network.InterfaceInfo

	// Volumes contains a list of volumes created, each one having the
	// same Name as one of the VolumeParams in StartInstanceParams.Volumes.
	// VolumeAttachment information is reported separately.
	Volumes []storage.Volume

	// VolumeAttachments contains a attachment-specific information about
	// volumes that were attached to the started instance.
	VolumeAttachments []storage.VolumeAttachment

StartInstanceResult holds the result of an InstanceBroker.StartInstance method call.


Path Synopsis
The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.
The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.

Jump to

Keyboard shortcuts

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