github.com/wallyworld/juju@v0.0.0-20161013125918-6cf1bc9d917a/environs/broker.go (about) 1 // Copyright 2013 Canonical Ltd. 2 // Licensed under the AGPLv3, see LICENCE file for details. 3 4 package environs 5 6 import ( 7 "github.com/juju/juju/cloudconfig/instancecfg" 8 "github.com/juju/juju/constraints" 9 "github.com/juju/juju/environs/config" 10 "github.com/juju/juju/environs/imagemetadata" 11 "github.com/juju/juju/instance" 12 "github.com/juju/juju/network" 13 "github.com/juju/juju/status" 14 "github.com/juju/juju/storage" 15 "github.com/juju/juju/tools" 16 ) 17 18 // StartInstanceParams holds parameters for the 19 // InstanceBroker.StartInstance method. 20 type StartInstanceParams struct { 21 // ControllerUUID is the uuid of the controller. 22 ControllerUUID string 23 24 // Constraints is a set of constraints on 25 // the kind of instance to create. 26 Constraints constraints.Value 27 28 // Tools is a list of tools that may be used 29 // to start a Juju agent on the machine. 30 Tools tools.List 31 32 // InstanceConfig describes the machine's configuration. 33 InstanceConfig *instancecfg.InstanceConfig 34 35 // Placement, if non-empty, contains an environment-specific 36 // placement directive that may be used to decide how the 37 // instance should be started. 38 Placement string 39 40 // DistributionGroup, if non-nil, is a function 41 // that returns a slice of instance.Ids that belong 42 // to the same distribution group as the machine 43 // being provisioned. The InstanceBroker may use 44 // this information to distribute instances for 45 // high availability. 46 DistributionGroup func() ([]instance.Id, error) 47 48 // Volumes is a set of parameters for volumes that should be created. 49 // 50 // StartInstance need not check the value of the Attachment field, 51 // as it is guaranteed that any volumes in this list are designated 52 // for attachment to the instance being started. 53 Volumes []storage.VolumeParams 54 55 // NetworkInfo is an optional list of network interface details, 56 // necessary to configure on the instance. 57 NetworkInfo []network.InterfaceInfo 58 59 // SubnetsToZones is an optional map of provider-specific subnet 60 // id to a list of availability zone names the subnet is available 61 // in. It is only populated when valid positive spaces constraints 62 // are present. 63 SubnetsToZones map[network.Id][]string 64 65 // EndpointBindings holds the mapping between service endpoint names to 66 // provider-specific space IDs. It is populated when provisioning a machine 67 // to host a unit of a service with endpoint bindings. 68 EndpointBindings map[string]network.Id 69 // ImageMetadata is a collection of image metadata 70 // that may be used to start this instance. 71 ImageMetadata []*imagemetadata.ImageMetadata 72 73 // StatusCallback is a callback to be used by the instance to report 74 // changes in status. Its signature is consistent with other 75 // status-related functions to allow them to be used as callbacks. 76 StatusCallback func(settableStatus status.Status, info string, data map[string]interface{}) error 77 78 // CleanupCallback is a callback to be used to clean up any residual 79 // status-reporting output from StatusCallback. 80 CleanupCallback func(info string) error 81 } 82 83 // StartInstanceResult holds the result of an 84 // InstanceBroker.StartInstance method call. 85 type StartInstanceResult struct { 86 // Instance is an interface representing a cloud instance. 87 Instance instance.Instance 88 89 // Config holds the environment config to be used for any further 90 // operations, if the instance is for a controller. 91 Config *config.Config 92 93 // HardwareCharacteristics represents the hardware characteristics 94 // of the newly created instance. 95 Hardware *instance.HardwareCharacteristics 96 97 // NetworkInfo contains information about how to configure network 98 // interfaces on the instance. Depending on the provider, this 99 // might be the same StartInstanceParams.NetworkInfo or may be 100 // modified as needed. 101 NetworkInfo []network.InterfaceInfo 102 103 // Volumes contains a list of volumes created, each one having the 104 // same Name as one of the VolumeParams in StartInstanceParams.Volumes. 105 // VolumeAttachment information is reported separately. 106 Volumes []storage.Volume 107 108 // VolumeAttachments contains a attachment-specific information about 109 // volumes that were attached to the started instance. 110 VolumeAttachments []storage.VolumeAttachment 111 } 112 113 // TODO(wallyworld) - we want this in the environs/instance package but import loops 114 // stop that from being possible right now. 115 type InstanceBroker interface { 116 // StartInstance asks for a new instance to be created, associated with 117 // the provided config in machineConfig. The given config describes the juju 118 // state for the new instance to connect to. The config MachineNonce, which must be 119 // unique within an environment, is used by juju to protect against the 120 // consequences of multiple instances being started with the same machine 121 // id. 122 StartInstance(args StartInstanceParams) (*StartInstanceResult, error) 123 124 // StopInstances shuts down the instances with the specified IDs. 125 // Unknown instance IDs are ignored, to enable idempotency. 126 StopInstances(...instance.Id) error 127 128 // AllInstances returns all instances currently known to the broker. 129 AllInstances() ([]instance.Instance, error) 130 131 // MaintainInstance is used to run actions on jujud startup for existing 132 // instances. It is currently only used to ensure that LXC hosts have the 133 // correct network configuration. 134 MaintainInstance(args StartInstanceParams) error 135 }