github.com/altoros/juju-vmware@v0.0.0-20150312064031-f19ae857ccca/environs/interface.go (about) 1 // Copyright 2011, 2012, 2013 Canonical Ltd. 2 // Licensed under the AGPLv3, see LICENCE file for details. 3 4 package environs 5 6 import ( 7 "io" 8 "os" 9 10 "github.com/juju/juju/constraints" 11 "github.com/juju/juju/environs/cloudinit" 12 "github.com/juju/juju/environs/config" 13 "github.com/juju/juju/environs/storage" 14 "github.com/juju/juju/instance" 15 "github.com/juju/juju/network" 16 "github.com/juju/juju/state" 17 "github.com/juju/juju/tools" 18 ) 19 20 // A EnvironProvider represents a computing and storage provider. 21 type EnvironProvider interface { 22 // RestrictedConfigAttributes are provider specific attributes stored in 23 // the config that really cannot or should not be changed across 24 // environments running inside a single juju server. 25 RestrictedConfigAttributes() []string 26 27 // PrepareForCreateEnvironment prepares an environment for creation. Any 28 // additional configuration attributes are added to the config passed in 29 // and returned. This allows providers to add additional required config 30 // for new environments that may be created in an existing juju server. 31 PrepareForCreateEnvironment(cfg *config.Config) (*config.Config, error) 32 33 // PrepareForBootstrap prepares an environment for use. Any additional 34 // configuration attributes in the returned environment should 35 // be saved to be used later. If the environment is already 36 // prepared, this call is equivalent to Open. 37 PrepareForBootstrap(ctx BootstrapContext, cfg *config.Config) (Environ, error) 38 39 // Open opens the environment and returns it. 40 // The configuration must have come from a previously 41 // prepared environment. 42 Open(cfg *config.Config) (Environ, error) 43 44 // Validate ensures that config is a valid configuration for this 45 // provider, applying changes to it if necessary, and returns the 46 // validated configuration. 47 // If old is not nil, it holds the previous environment configuration 48 // for consideration when validating changes. 49 Validate(cfg, old *config.Config) (valid *config.Config, err error) 50 51 // Boilerplate returns a default configuration for the environment in yaml format. 52 // The text should be a key followed by some number of attributes: 53 // `environName: 54 // type: environTypeName 55 // attr1: val1 56 // ` 57 // The text is used as a template (see the template package) with one extra template 58 // function available, rand, which expands to a random hexadecimal string when invoked. 59 BoilerplateConfig() string 60 61 // SecretAttrs filters the supplied configuration returning only values 62 // which are considered sensitive. All of the values of these secret 63 // attributes need to be strings. 64 SecretAttrs(cfg *config.Config) (map[string]string, error) 65 } 66 67 // EnvironStorage implements storage access for an environment. 68 type EnvironStorage interface { 69 // Storage returns storage specific to the environment. 70 Storage() storage.Storage 71 } 72 73 // ConfigGetter implements access to an environment's configuration. 74 type ConfigGetter interface { 75 // Config returns the configuration data with which the Environ was created. 76 // Note that this is not necessarily current; the canonical location 77 // for the configuration data is stored in the state. 78 Config() *config.Config 79 } 80 81 // BootstrapParams holds the parameters for bootstrapping an environment. 82 type BootstrapParams struct { 83 // Constraints are used to choose the initial instance specification, 84 // and will be stored in the new environment's state. 85 Constraints constraints.Value 86 87 // Placement, if non-empty, holds an environment-specific placement 88 // directive used to choose the initial instance. 89 Placement string 90 91 // AvailableTools is a collection of tools which the Bootstrap method 92 // may use to decide which architecture/series to instantiate. 93 AvailableTools tools.List 94 95 // ContainerBridgeName, if non-empty, overrides the default 96 // network bridge device to use for LXC and KVM containers. See 97 // environs.DefaultBridgeName. 98 ContainerBridgeName string 99 } 100 101 // BootstrapFinalizer is a function returned from Environ.Bootstrap. 102 // The caller must pass a MachineConfig with the Tools field set. 103 type BootstrapFinalizer func(BootstrapContext, *cloudinit.MachineConfig) error 104 105 // An Environ represents a juju environment as specified 106 // in the environments.yaml file. 107 // 108 // Due to the limitations of some providers (for example ec2), the 109 // results of the Environ methods may not be fully sequentially 110 // consistent. In particular, while a provider may retry when it 111 // gets an error for an operation, it will not retry when 112 // an operation succeeds, even if that success is not 113 // consistent with a previous operation. 114 // 115 // Even though Juju takes care not to share an Environ between concurrent 116 // workers, it does allow concurrent method calls into the provider 117 // implementation. The typical provider implementation needs locking to 118 // avoid undefined behaviour when the configuration changes. 119 type Environ interface { 120 // Bootstrap creates a new instance with the series and architecture 121 // of its choice, constrained to those of the available tools, and 122 // returns the instance's architecture, series, and a function that 123 // must be called to finalize the bootstrap process by transferring 124 // the tools and installing the initial Juju state server. 125 // 126 // It is possible to direct Bootstrap to use a specific architecture 127 // (or fail if it cannot start an instance of that architecture) by 128 // using an architecture constraint; this will have the effect of 129 // limiting the available tools to just those matching the specified 130 // architecture. 131 Bootstrap(ctx BootstrapContext, params BootstrapParams) (arch, series string, _ BootstrapFinalizer, _ error) 132 133 // InstanceBroker defines methods for starting and stopping 134 // instances. 135 InstanceBroker 136 137 // ConfigGetter allows the retrieval of the configuration data. 138 ConfigGetter 139 140 // EnvironCapability allows access to this environment's capabilities. 141 state.EnvironCapability 142 143 // ConstraintsValidator returns a Validator instance which 144 // is used to validate and merge constraints. 145 ConstraintsValidator() (constraints.Validator, error) 146 147 // SetConfig updates the Environ's configuration. 148 // 149 // Calls to SetConfig do not affect the configuration of 150 // values previously obtained from Storage. 151 SetConfig(cfg *config.Config) error 152 153 // Instances returns a slice of instances corresponding to the 154 // given instance ids. If no instances were found, but there 155 // was no other error, it will return ErrNoInstances. If 156 // some but not all the instances were found, the returned slice 157 // will have some nil slots, and an ErrPartialInstances error 158 // will be returned. 159 Instances(ids []instance.Id) ([]instance.Instance, error) 160 161 // StateServerInstances returns the IDs of instances corresponding 162 // to Juju state servers. If there are no state server instances, 163 // ErrNoInstances is returned. If it can be determined that the 164 // environment has not been bootstrapped, then ErrNotBootstrapped 165 // should be returned instead. 166 StateServerInstances() ([]instance.Id, error) 167 168 // Destroy shuts down all known machines and destroys the 169 // rest of the environment. Note that on some providers, 170 // very recently started instances may not be destroyed 171 // because they are not yet visible. 172 // 173 // When Destroy has been called, any Environ referring to the 174 // same remote environment may become invalid 175 Destroy() error 176 177 // OpenPorts opens the given port ranges for the whole environment. 178 // Must only be used if the environment was setup with the 179 // FwGlobal firewall mode. 180 OpenPorts(ports []network.PortRange) error 181 182 // ClosePorts closes the given port ranges for the whole environment. 183 // Must only be used if the environment was setup with the 184 // FwGlobal firewall mode. 185 ClosePorts(ports []network.PortRange) error 186 187 // Ports returns the port ranges opened for the whole environment. 188 // Must only be used if the environment was setup with the 189 // FwGlobal firewall mode. 190 Ports() ([]network.PortRange, error) 191 192 // Provider returns the EnvironProvider that created this Environ. 193 Provider() EnvironProvider 194 195 state.Prechecker 196 } 197 198 // BootstrapContext is an interface that is passed to 199 // Environ.Bootstrap, providing a means of obtaining 200 // information about and manipulating the context in which 201 // it is being invoked. 202 type BootstrapContext interface { 203 GetStdin() io.Reader 204 GetStdout() io.Writer 205 GetStderr() io.Writer 206 Infof(format string, params ...interface{}) 207 Verbosef(format string, params ...interface{}) 208 209 // InterruptNotify starts watching for interrupt signals 210 // on behalf of the caller, sending them to the supplied 211 // channel. 212 InterruptNotify(sig chan<- os.Signal) 213 214 // StopInterruptNotify undoes the effects of a previous 215 // call to InterruptNotify with the same channel. After 216 // StopInterruptNotify returns, no more signals will be 217 // delivered to the channel. 218 StopInterruptNotify(chan<- os.Signal) 219 220 // ShouldVerifyCredentials indicates whether the caller's cloud 221 // credentials should be verified. 222 ShouldVerifyCredentials() bool 223 }