← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/environs/interface.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/environs/interface.go
 
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
        "gopkg.in/juju/environschema.v1"
 
8
 
 
9
        "github.com/juju/juju/cloud"
 
10
        "github.com/juju/juju/constraints"
 
11
        "github.com/juju/juju/environs/config"
 
12
        "github.com/juju/juju/instance"
 
13
        "github.com/juju/juju/network"
 
14
        "github.com/juju/juju/storage"
 
15
)
 
16
 
 
17
// A EnvironProvider represents a computing and storage provider.
 
18
type EnvironProvider interface {
 
19
        config.Validator
 
20
        ProviderCredentials
 
21
 
 
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
        // PrepareConfig prepares the configuration for a new model, based on
 
28
        // the provided arguments. PrepareConfig is expected to produce a
 
29
        // deterministic output. Any unique values should be based on the
 
30
        // "uuid" attribute of the base configuration. This is called for the
 
31
        // controller model during bootstrap, and also for new hosted models.
 
32
        PrepareConfig(PrepareConfigParams) (*config.Config, error)
 
33
 
 
34
        // Open opens the environment and returns it. The configuration must
 
35
        // have passed through PrepareConfig at some point in its lifecycle.
 
36
        //
 
37
        // Open should not perform any expensive operations, such as querying
 
38
        // the cloud API, as it will be called frequently.
 
39
        Open(OpenParams) (Environ, error)
 
40
 
 
41
        // SecretAttrs filters the supplied configuration returning only values
 
42
        // which are considered sensitive. All of the values of these secret
 
43
        // attributes need to be strings.
 
44
        SecretAttrs(cfg *config.Config) (map[string]string, error)
 
45
}
 
46
 
 
47
// OpenParams contains the parameters for EnvironProvider.Open.
 
48
type OpenParams struct {
 
49
        // Cloud is the cloud specification to use to connect to the cloud.
 
50
        Cloud CloudSpec
 
51
 
 
52
        // Config is the base configuration for the provider.
 
53
        Config *config.Config
 
54
}
 
55
 
 
56
// ProviderSchema can be implemented by a provider to provide
 
57
// access to its configuration schema. Once all providers implement
 
58
// this, it will be included in the EnvironProvider type and the
 
59
// information made available over the API.
 
60
type ProviderSchema interface {
 
61
        // Schema returns the schema for the provider. It should
 
62
        // include all fields defined in environs/config, conventionally
 
63
        // by calling config.Schema.
 
64
        Schema() environschema.Fields
 
65
}
 
66
 
 
67
// PrepareConfigParams contains the parameters for EnvironProvider.PrepareConfig.
 
68
type PrepareConfigParams struct {
 
69
        // ControllerUUID is the UUID of the controller to be bootstrapped.
 
70
        ControllerUUID string
 
71
 
 
72
        // Cloud is the cloud specification to use to connect to the cloud.
 
73
        Cloud CloudSpec
 
74
 
 
75
        // Config is the base configuration for the provider. This should
 
76
        // be updated with the region, endpoint and credentials.
 
77
        Config *config.Config
 
78
}
 
79
 
 
80
// ProviderCredentials is an interface that an EnvironProvider implements
 
81
// in order to validate and automatically detect credentials for clouds
 
82
// supported by the provider.
 
83
//
 
84
// TODO(axw) replace CredentialSchemas with an updated environschema.
 
85
// The GUI also needs to be able to handle multiple credential types,
 
86
// and dependencies in config attributes.
 
87
type ProviderCredentials interface {
 
88
        // CredentialSchemas returns credential schemas, keyed on
 
89
        // authentication type. These may be used to validate existing
 
90
        // credentials, or to generate new ones (e.g. to create an
 
91
        // interactive form.)
 
92
        CredentialSchemas() map[cloud.AuthType]cloud.CredentialSchema
 
93
 
 
94
        // DetectCredentials automatically detects one or more credentials
 
95
        // from the environment. This may involve, for example, inspecting
 
96
        // environment variables, or reading configuration files in
 
97
        // well-defined locations.
 
98
        //
 
99
        // If no credentials can be detected, DetectCredentials should
 
100
        // return an error satisfying errors.IsNotFound.
 
101
        DetectCredentials() (*cloud.CloudCredential, error)
 
102
}
 
103
 
 
104
// CloudRegionDetector is an interface that an EnvironProvider implements
 
105
// in order to automatically detect cloud regions from the environment.
 
106
type CloudRegionDetector interface {
 
107
        // DetectRetions automatically detects one or more regions
 
108
        // from the environment. This may involve, for example, inspecting
 
109
        // environment variables, or returning special hard-coded regions
 
110
        // (e.g. "localhost" for lxd). The first item in the list will be
 
111
        // considered the default region for bootstrapping if the user
 
112
        // does not specify one.
 
113
        //
 
114
        // If no regions can be detected, DetectRegions should return
 
115
        // an error satisfying errors.IsNotFound.
 
116
        DetectRegions() ([]cloud.Region, error)
 
117
}
 
118
 
 
119
// ModelConfigUpgrader is an interface that an EnvironProvider may
 
120
// implement in order to modify environment configuration on agent upgrade.
 
121
type ModelConfigUpgrader interface {
 
122
        // UpgradeConfig upgrades an old environment configuration by adding,
 
123
        // updating or removing attributes. UpgradeConfig must be idempotent,
 
124
        // as it may be called multiple times in the event of a partial upgrade.
 
125
        //
 
126
        // NOTE(axw) this is currently only called when upgrading to 1.25.
 
127
        // We should update the upgrade machinery to call this for every
 
128
        // version upgrade, so the upgrades package is not tightly coupled
 
129
        // to provider upgrades.
 
130
        UpgradeConfig(cfg *config.Config) (*config.Config, error)
 
131
}
 
132
 
 
133
// ConfigGetter implements access to an environment's configuration.
 
134
type ConfigGetter interface {
 
135
        // Config returns the configuration data with which the Environ was created.
 
136
        // Note that this is not necessarily current; the canonical location
 
137
        // for the configuration data is stored in the state.
 
138
        Config() *config.Config
 
139
}
 
140
 
 
141
// An Environ represents a Juju environment.
 
142
//
 
143
// Due to the limitations of some providers (for example ec2), the
 
144
// results of the Environ methods may not be fully sequentially
 
145
// consistent. In particular, while a provider may retry when it
 
146
// gets an error for an operation, it will not retry when
 
147
// an operation succeeds, even if that success is not
 
148
// consistent with a previous operation.
 
149
//
 
150
// Even though Juju takes care not to share an Environ between concurrent
 
151
// workers, it does allow concurrent method calls into the provider
 
152
// implementation.  The typical provider implementation needs locking to
 
153
// avoid undefined behaviour when the configuration changes.
 
154
type Environ interface {
 
155
        // Environ implements storage.ProviderRegistry for acquiring
 
156
        // environ-scoped storage providers supported by the Environ.
 
157
        // StorageProviders returned from Environ.StorageProvider will
 
158
        // be scoped specifically to that Environ.
 
159
        storage.ProviderRegistry
 
160
 
 
161
        // PrepareForBootstrap prepares an environment for bootstrapping.
 
162
        //
 
163
        // This will be called very early in the bootstrap procedure, to
 
164
        // give an Environ a chance to perform interactive operations that
 
165
        // are required for bootstrapping.
 
166
        PrepareForBootstrap(ctx BootstrapContext) error
 
167
 
 
168
        // Bootstrap creates a new environment, and an instance to host the
 
169
        // controller for that environment. The instnace will have have the
 
170
        // series and architecture of the Environ's choice, constrained to
 
171
        // those of the available tools. Bootstrap will return the instance's
 
172
        // architecture, series, and a function that must be called to finalize
 
173
        // the bootstrap process by transferring the tools and installing the
 
174
        // initial Juju controller.
 
175
        //
 
176
        // It is possible to direct Bootstrap to use a specific architecture
 
177
        // (or fail if it cannot start an instance of that architecture) by
 
178
        // using an architecture constraint; this will have the effect of
 
179
        // limiting the available tools to just those matching the specified
 
180
        // architecture.
 
181
        Bootstrap(ctx BootstrapContext, params BootstrapParams) (*BootstrapResult, error)
 
182
 
 
183
        // Create creates the environment for a new hosted model.
 
184
        //
 
185
        // This will be called before any workers begin operating on the
 
186
        // Environ, to give an Environ a chance to perform operations that
 
187
        // are required for further use.
 
188
        //
 
189
        // Create is not called for the initial controller model; it is
 
190
        // the Bootstrap method's job to create the controller model.
 
191
        Create(CreateParams) error
 
192
 
 
193
        // InstanceBroker defines methods for starting and stopping
 
194
        // instances.
 
195
        InstanceBroker
 
196
 
 
197
        // ConfigGetter allows the retrieval of the configuration data.
 
198
        ConfigGetter
 
199
 
 
200
        // ConstraintsValidator returns a Validator instance which
 
201
        // is used to validate and merge constraints.
 
202
        ConstraintsValidator() (constraints.Validator, error)
 
203
 
 
204
        // SetConfig updates the Environ's configuration.
 
205
        //
 
206
        // Calls to SetConfig do not affect the configuration of
 
207
        // values previously obtained from Storage.
 
208
        SetConfig(cfg *config.Config) error
 
209
 
 
210
        // Instances returns a slice of instances corresponding to the
 
211
        // given instance ids.  If no instances were found, but there
 
212
        // was no other error, it will return ErrNoInstances.  If
 
213
        // some but not all the instances were found, the returned slice
 
214
        // will have some nil slots, and an ErrPartialInstances error
 
215
        // will be returned.
 
216
        Instances(ids []instance.Id) ([]instance.Instance, error)
 
217
 
 
218
        // ControllerInstances returns the IDs of instances corresponding
 
219
        // to Juju controller, having the specified controller UUID.
 
220
        // If there are no controller instances, ErrNoInstances is returned.
 
221
        // If it can be determined that the environment has not been bootstrapped,
 
222
        // then ErrNotBootstrapped should be returned instead.
 
223
        ControllerInstances(controllerUUID string) ([]instance.Id, error)
 
224
 
 
225
        // Destroy shuts down all known machines and destroys the
 
226
        // rest of the environment. Note that on some providers,
 
227
        // very recently started instances may not be destroyed
 
228
        // because they are not yet visible.
 
229
        //
 
230
        // When Destroy has been called, any Environ referring to the
 
231
        // same remote environment may become invalid.
 
232
        Destroy() error
 
233
 
 
234
        // DestroyController is similar to Destroy() in that it destroys
 
235
        // the model, which in this case will be the controller model.
 
236
        //
 
237
        // In addition, this method also destroys any resources relating
 
238
        // to hosted models on the controller on which it is invoked.
 
239
        // This ensures that "kill-controller" can clean up hosted models
 
240
        // when the Juju controller process is unavailable.
 
241
        DestroyController(controllerUUID string) error
 
242
 
 
243
        Firewaller
 
244
 
 
245
        // Provider returns the EnvironProvider that created this Environ.
 
246
        Provider() EnvironProvider
 
247
 
 
248
        // PrecheckInstance performs a preflight check on the specified
 
249
        // series and constraints, ensuring that they are possibly valid for
 
250
        // creating an instance in this model.
 
251
        //
 
252
        // PrecheckInstance is best effort, and not guaranteed to eliminate
 
253
        // all invalid parameters. If PrecheckInstance returns nil, it is not
 
254
        // guaranteed that the constraints are valid; if a non-nil error is
 
255
        // returned, then the constraints are definitely invalid.
 
256
        //
 
257
        // TODO(axw) find a home for state.Prechecker that isn't state and
 
258
        // isn't environs, so both packages can refer to it. Maybe the
 
259
        // constraints package? Can't be instance, because constraints
 
260
        // import instance...
 
261
        PrecheckInstance(series string, cons constraints.Value, placement string) error
 
262
}
 
263
 
 
264
// CreateParams contains the parameters for Environ.Create.
 
265
type CreateParams struct {
 
266
        // ControllerUUID is the UUID of the controller to be that is creating
 
267
        // the Environ.
 
268
        ControllerUUID string
 
269
}
 
270
 
 
271
// Firewaller exposes methods for managing network ports.
 
272
type Firewaller interface {
 
273
        // OpenPorts opens the given port ranges for the whole environment.
 
274
        // Must only be used if the environment was setup with the
 
275
        // FwGlobal firewall mode.
 
276
        OpenPorts(ports []network.PortRange) error
 
277
 
 
278
        // ClosePorts closes the given port ranges for the whole environment.
 
279
        // Must only be used if the environment was setup with the
 
280
        // FwGlobal firewall mode.
 
281
        ClosePorts(ports []network.PortRange) error
 
282
 
 
283
        // Ports returns the port ranges opened for the whole environment.
 
284
        // Must only be used if the environment was setup with the
 
285
        // FwGlobal firewall mode.
 
286
        Ports() ([]network.PortRange, error)
 
287
}
 
288
 
 
289
// InstanceTagger is an interface that can be used for tagging instances.
 
290
type InstanceTagger interface {
 
291
        // TagInstance tags the given instance with the specified tags.
 
292
        //
 
293
        // The specified tags will replace any existing ones with the
 
294
        // same names, but other existing tags will be left alone.
 
295
        TagInstance(id instance.Id, tags map[string]string) error
 
296
}