Documentation ¶
Index ¶
- Constants
- Variables
- func BoilerplateConfig() string
- func Bootstrap(environ Environ, cons constraints.Value) error
- func BootstrapConfig(cfg *config.Config) (*config.Config, error)
- func BootstrapUsers(st *state.State, cfg *config.Config, passwordHash string) error
- func CheckEnvironment(environ Environ) error
- func ConfigureBootstrapMachine(st *state.State, cfg *config.Config, cons constraints.Value, datadir string, ...) error
- func FindAvailableTools(environ Environ, majorVersion int) (list tools.List, err error)
- func FindBootstrapTools(environ Environ, cons constraints.Value) (list tools.List, err error)
- func FindExactTools(environ Environ, vers version.Binary) (t *state.Tools, err error)
- func FindInstanceTools(environ Environ, series string, cons constraints.Value) (list tools.List, err error)
- func FinishMachineConfig(mcfg *cloudinit.MachineConfig, cfg *config.Config, cons constraints.Value) (err error)
- func MongoStoragePath(series, architecture string) string
- func RegisterProvider(name string, p EnvironProvider)
- func RemoveAll(stor Storage) error
- func SaveState(storage StorageWriter, state *BootstrapState) error
- func StateInfo(env Environ) (*state.Info, *api.Info, error)
- func VerifyBootstrapInit(env Environ, shortAttempt utils.AttemptStrategy) error
- func VerifyStorage(storage Storage) error
- func WaitDNSName(inst instance.Instance) (string, error)
- func WriteCertAndKey(name string, cert, key []byte) error
- func WriteEnvirons(path string, fileContents string) (string, error)
- type BootstrapState
- type CreatedCert
- type Environ
- type EnvironProvider
- type Environs
- type Storage
- type StorageReader
- type StorageWriter
Constants ¶
const StateFile = "provider-state"
StateFile is the name of the file where the provider's state is stored.
Variables ¶
var ErrNoInstances = errors.New("no instances found")
var ErrPartialInstances = errors.New("only some instances were found")
var InvalidEnvironmentError error = fmt.Errorf(
"environment is not a juju-core environment")
var LongAttempt = utils.AttemptStrategy{ Total: 3 * time.Minute, Delay: 1 * time.Second, }
A request may fail to due "eventual consistency" semantics, which should resolve fairly quickly. These delays are specific to the provider and best tuned there. Other requests fail due to a slow state transition (e.g. an instance taking a while to release a security group after termination). If you need to poll for the latter kind, use LongAttempt.
var VerifyStorageError error = fmt.Errorf(
"provider storage is not writable")
Functions ¶
func BoilerplateConfig ¶
func BoilerplateConfig() string
BoilerplateConfig returns a sample juju configuration.
func Bootstrap ¶
func Bootstrap(environ Environ, cons constraints.Value) error
Bootstrap bootstraps the given environment. The supplied constraints are used to provision the instance, and are also set within the bootstrapped environment.
func BootstrapConfig ¶
BootstrapConfig returns a copy of the supplied configuration with secret attributes removed. If the resulting config is not suitable for bootstrapping an environment, an error is returned.
func BootstrapUsers ¶
BootstrapUsers creates the initial admin user for the database, and sets the initial password.
func CheckEnvironment ¶
CheckEnvironment checks if an environment has a bootstrap-verify that is written by juju-core commands (as compared to one being written by Python juju).
If there is no bootstrap-verify file in the storage, it is still considered to be a Juju-core environment since early versions have not written it out.
Returns InvalidEnvironmentError on failure, nil otherwise.
func ConfigureBootstrapMachine ¶
func ConfigureBootstrapMachine( st *state.State, cfg *config.Config, cons constraints.Value, datadir string, jobs []state.MachineJob, ) error
ConfigureBootstrapMachine adds the initial machine into state. As a part of this process the environmental constraints are saved as constraints used when bootstrapping are considered constraints for the entire environment.
func FindAvailableTools ¶
FindAvailableTools returns a tools.List containing all tools with a given major version number available in the environment. If *any* tools are present in private storage, *only* tools from private storage are available. If *no* tools are present in private storage, *only* tools from public storage are available. If no *available* tools have the supplied major version number, the function returns a *NotFoundError.
func FindBootstrapTools ¶
FindBootstrapTools returns a ToolsList containing only those tools with which it would be reasonable to launch an environment's first machine, given the supplied constraints. If the environment was not already configured to use a specific agent version, the newest available version will be chosen and set in the environment's configuration.
func FindExactTools ¶
FindExactTools returns only the tools that match the supplied version. TODO(fwereade) this should not exist: it's used by cmd/jujud/Upgrader, which needs to run on every agent and must absolutely *not* in general have access to an Environ.
func FindInstanceTools ¶
func FindInstanceTools(environ Environ, series string, cons constraints.Value) (list tools.List, err error)
FindInstanceTools returns a ToolsList containing only those tools with which it would be reasonable to start a new instance, given the supplied series and constraints. It is an error to call it with an environment not already configured to use a specific agent version.
func FinishMachineConfig ¶
func FinishMachineConfig(mcfg *cloudinit.MachineConfig, cfg *config.Config, cons constraints.Value) (err error)
FinishMachineConfig sets fields on a MachineConfig that can be determined by inspecting a plain config.Config and the machine constraints at the last moment before bootstrapping. It assumes that the supplied Config comes from an environment that has passed through all the validation checks in the Bootstrap func, and that has set an agent-version (via FindBootstrapTools, or otherwise). TODO(fwereade) This function is not meant to be "good" in any serious way: it is better that this functionality be collected in one place here than that it be spread out across 3 or 4 providers, but this is its only redeeming feature.
func MongoStoragePath ¶
MongoStoragePath returns the path that is used to retrieve the given version of mongodb in a Storage.
func RegisterProvider ¶
func RegisterProvider(name string, p EnvironProvider)
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 same provider name is registered more than once.
func RemoveAll ¶
RemoveAll is a default implementation for StorageWriter.RemoveAll. Providers may have more efficient implementations, or better error handling, or safeguards against races with other users of the same storage medium. But a simple way to implement RemoveAll would be to delegate to here.
func SaveState ¶
func SaveState(storage StorageWriter, state *BootstrapState) error
SaveState writes the given state to the given storage.
func StateInfo ¶
StateInfo is a reusable implementation of Environ.StateInfo, available to providers that also use the other functionality from this file.
func VerifyBootstrapInit ¶
func VerifyBootstrapInit(env Environ, shortAttempt utils.AttemptStrategy) error
VerifyBootstrapInit does the common initial check inside bootstrap to confirm that the environment isn't already running, and that the storage works.
func VerifyStorage ¶
func WaitDNSName ¶
WaitDNSName is an implementation that the providers can use. It builds on the provider's implementation of Instance.DNSName.
func WriteCertAndKey ¶
WriteCertAndKey writes the provided certificate and key to the juju home directory, creating it if necessary,
Types ¶
type BootstrapState ¶
type BootstrapState struct { // StateInstances are the state servers. StateInstances []instance.Id `yaml:"state-instances"` }
BootstrapState is the state information that is stored in StateFile.
Individual providers may define their own state structures instead of this one, and use their own code for loading and saving those, but this is the definition that most practically useful providers share unchanged.
func LoadState ¶
func LoadState(storage StorageReader) (*BootstrapState, error)
LoadState reads state from the given storage.
type CreatedCert ¶
type CreatedCert bool
const ( CertCreated CreatedCert = true CertExists CreatedCert = false )
func EnsureCertificate ¶
func EnsureCertificate(environ Environ, writeCertAndKey func(environName string, cert, key []byte) error) (CreatedCert, error)
EnsureCertificate makes sure that there is a certificate and private key for the specified environment. If one does not exist, then a certificate is generated.
type Environ ¶
type Environ interface { // Name returns the Environ's name. Name() string // Bootstrap initializes the state for the environment, possibly // starting one or more instances. If the configuration's // AdminSecret is non-empty, the adminstrator password on the // newly bootstrapped state will be set to a hash of it (see // utils.PasswordHash), When first connecting to the // environment via the juju package, the password hash will be // automatically replaced by the real password. // // The supplied constraints are used to choose the initial instance // specification, and will be stored in the new environment's state. Bootstrap(cons constraints.Value) error // StateInfo returns information on the state initialized // by Bootstrap. StateInfo() (*state.Info, *api.Info, error) // Config returns the current configuration of this Environ. Config() *config.Config // SetConfig updates the Environ's configuration. // // Calls to SetConfig do not affect the configuration of // values previously obtained from Storage and PublicStorage. SetConfig(cfg *config.Config) error // StartInstance asks for a new instance to be created, associated // with the provided machine identifier. The given info describes // the juju state for the new instance to connect to. The nonce, // 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(machineId, machineNonce string, series string, cons constraints.Value, info *state.Info, apiInfo *api.Info) (instance.Instance, *instance.HardwareCharacteristics, error) // StopInstances shuts down the given instances. StopInstances([]instance.Instance) 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) // AllInstances returns all instances currently known to the // environment. AllInstances() ([]instance.Instance, error) // Storage returns storage specific to the environment. Storage() Storage // PublicStorage returns storage shared between environments. PublicStorage() StorageReader // Destroy shuts down all known machines and destroys the // rest of the environment. A list of instances known to // be part of the environment can be given with insts. // This is because recently started machines might not // yet be visible in the environment, so this method // can wait until they are. // // When Destroy has been called, any Environ referring to the // same remote environment may become invalid Destroy(insts []instance.Instance) error // OpenPorts opens the given ports for the whole environment. // Must only be used if the environment was setup with the // FwGlobal firewall mode. OpenPorts(ports []instance.Port) error // ClosePorts closes the given ports for the whole environment. // Must only be used if the environment was setup with the // FwGlobal firewall mode. ClosePorts(ports []instance.Port) error // Ports returns the ports opened for the whole environment. // Must only be used if the environment was setup with the // FwGlobal firewall mode. Ports() ([]instance.Port, 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 NewFromAttrs ¶
NewFromAttrs returns a new environment based on the provided configuration attributes.
func NewFromName ¶
NewFromName opens the environment with the given name from the default environments file. If the name is blank, the default environment will be used.
type EnvironProvider ¶
type EnvironProvider interface { // Open opens the environment and returns it. 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. SecretAttrs(cfg *config.Config) (map[string]interface{}, error) // PublicAddress returns this machine's public host name. PublicAddress() (string, error) // PrivateAddress returns this machine's private host name. PrivateAddress() (string, error) // InstanceId returns this machine's instance id. InstanceId() (instance.Id, error) }
A EnvironProvider represents a computing and storage provider.
func Provider ¶
func Provider(typ string) (EnvironProvider, error)
Provider returns the previously registered provider with the given type.
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 ¶
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 ¶
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.
type Storage ¶
type Storage interface { StorageReader StorageWriter }
Storage represents storage that can be both read and written.
type StorageReader ¶
type StorageReader interface { // Get opens the given storage file and returns a ReadCloser // that can be used to read its contents. It is the caller's // responsibility to close it after use. If the name does not // exist, it should return a *NotFoundError. Get(name string) (io.ReadCloser, error) // List lists all names in the storage with the given prefix, in // alphabetical order. The names in the storage are considered // to be in a flat namespace, so the prefix may include slashes // and the names returned are the full names for the matching // entries. List(prefix string) ([]string, error) // URL returns a URL that can be used to access the given storage file. URL(name string) (string, error) }
A StorageReader can retrieve and list files from a storage provider.
var EmptyStorage StorageReader = emptyStorage{}
EmptyStorage holds a StorageReader object that contains no files and offers no URLs.
type StorageWriter ¶
type StorageWriter interface { // Put reads from r and writes to the given storage file. // The length must give the total length of the file. Put(name string, r io.Reader, length int64) error // Remove removes the given file from the environment's // storage. It should not return an error if the file does // not exist. Remove(name string) error // RemoveAll deletes all files that have been stored here. // If the underlying storage implementation may be shared // with other actors, it must be sure not to delete their // file as well. // Nevertheless, use with care! This method is only mean // for cleaning up an environment that's being destroyed. RemoveAll() error }
A StorageWriter adds and removes files in a storage provider.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
The dummy provider implements an environment provider for testing purposes, registered with environs under the name "dummy".
|
The dummy provider implements an environment provider for testing purposes, registered with environs under the name "dummy". |
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. |