environs

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: 32 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

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.

Functions

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.

Types

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
	ConfigFromInfo
	ConfigFromEnvirons
)

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.
	InstanceBroker

	// ConfigGetter allows the retrieval of the configuration data.
	ConfigGetter

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

	// 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

	state.Prechecker
}

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.
	Environ

	// Networking defines the methods of networking capable environments.
	Networking
}

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.

Source Files

View all Source files

Directories

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.
testing
The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
 The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
testing
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.
testing

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.