github.com/niedbalski/juju@v0.0.0-20190215020005-8ff100488e47/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 "gopkg.in/juju/charm.v6" 8 9 "github.com/juju/juju/cloudconfig/instancecfg" 10 "github.com/juju/juju/core/constraints" 11 "github.com/juju/juju/core/instance" 12 "github.com/juju/juju/core/status" 13 "github.com/juju/juju/environs/config" 14 "github.com/juju/juju/environs/context" 15 "github.com/juju/juju/environs/imagemetadata" 16 "github.com/juju/juju/environs/instances" 17 "github.com/juju/juju/network" 18 "github.com/juju/juju/storage" 19 "github.com/juju/juju/tools" 20 ) 21 22 // StatusCallbackFunc represents a function that can be called to report a status. 23 type StatusCallbackFunc func(settableStatus status.Status, info string, data map[string]interface{}) error 24 25 // StartInstanceParams holds parameters for the 26 // InstanceBroker.StartInstance method. 27 type StartInstanceParams struct { 28 // ControllerUUID is the uuid of the controller. 29 ControllerUUID string 30 31 // Constraints is a set of constraints on 32 // the kind of instance to create. 33 Constraints constraints.Value 34 35 // Tools is a list of tools that may be used 36 // to start a Juju agent on the machine. 37 Tools tools.List 38 39 // InstanceConfig describes the machine's configuration. 40 InstanceConfig *instancecfg.InstanceConfig 41 42 // Placement, if non-empty, contains an environment-specific 43 // placement directive that may be used to decide how the 44 // instance should be started. 45 Placement string 46 47 // AvailabilityZone, provides the name of the availability 48 // zone required to start the instance. 49 AvailabilityZone string 50 51 // Volumes is a set of parameters for volumes that should be created. 52 // 53 // StartInstance need not check the value of the Attachment field, 54 // as it is guaranteed that any volumes in this list are designated 55 // for attachment to the instance being started. 56 Volumes []storage.VolumeParams 57 58 // VolumeAttachments is a set of parameters for existing volumes that 59 // should be attached. If the StartInstance method does not attach the 60 // volumes, they will be attached by the storage provisioner once the 61 // machine has been created. The attachments are presented here to 62 // give the provider an opportunity for the volume attachments to 63 // influence the instance creation, e.g. by restricting the machine 64 // to specific availability zones. 65 VolumeAttachments []storage.VolumeAttachmentParams 66 67 // NetworkInfo is an optional list of network interface details, 68 // necessary to configure on the instance. 69 NetworkInfo []network.InterfaceInfo 70 71 // SubnetsToZones is an optional map of provider-specific subnet 72 // id to a list of availability zone names the subnet is available 73 // in. It is only populated when valid positive spaces constraints 74 // are present. 75 SubnetsToZones map[network.Id][]string 76 77 // EndpointBindings holds the mapping between application endpoint names to 78 // provider-specific space IDs. It is populated when provisioning a machine 79 // to host a unit of an application with endpoint bindings. 80 EndpointBindings map[string]network.Id 81 82 // ImageMetadata is a collection of image metadata 83 // that may be used to start this instance. 84 ImageMetadata []*imagemetadata.ImageMetadata 85 86 // CleanupCallback is a callback to be used to clean up any residual 87 // status-reporting output from StatusCallback. 88 CleanupCallback func(info string) error 89 90 // StatusCallback is a callback to be used by the instance to report 91 // changes in status. Its signature is consistent with other 92 // status-related functions to allow them to be used as callbacks. 93 StatusCallback StatusCallbackFunc 94 95 // Abort is a channel that will be closed to indicate that the command 96 // should be aborted. 97 Abort <-chan struct{} 98 99 // CharmLXDProfiles is a slice of names of lxd profiles to be used creating 100 // the LXD container, if specified and an LXD container. The profiles 101 // come from charms deployed on the machine. 102 CharmLXDProfiles []string 103 } 104 105 // StartInstanceResult holds the result of an 106 // InstanceBroker.StartInstance method call. 107 type StartInstanceResult struct { 108 // DisplayName is an optional human-readable string that's used 109 // for display purposes only. 110 DisplayName string 111 112 // Instance is an interface representing a cloud instance. 113 Instance instances.Instance 114 115 // Config holds the environment config to be used for any further 116 // operations, if the instance is for a controller. 117 Config *config.Config 118 119 // HardwareCharacteristics represents the hardware characteristics 120 // of the newly created instance. 121 Hardware *instance.HardwareCharacteristics 122 123 // NetworkInfo contains information about how to configure network 124 // interfaces on the instance. Depending on the provider, this 125 // might be the same StartInstanceParams.NetworkInfo or may be 126 // modified as needed. 127 NetworkInfo []network.InterfaceInfo 128 129 // Volumes contains a list of volumes created, each one having the 130 // same Name as one of the VolumeParams in StartInstanceParams.Volumes. 131 // VolumeAttachment information is reported separately. 132 Volumes []storage.Volume 133 134 // VolumeAttachments contains a attachment-specific information about 135 // volumes that were attached to the started instance. 136 VolumeAttachments []storage.VolumeAttachment 137 } 138 139 // TODO(wallyworld) - we want this in the environs/instance package but import loops 140 // stop that from being possible right now. 141 type InstanceBroker interface { 142 // StartInstance asks for a new instance to be created, associated with 143 // the provided config in machineConfig. The given config describes the 144 // juju state for the new instance to connect to. The config 145 // MachineNonce, which must be unique within an environment, is used by 146 // juju to protect against the consequences of multiple instances being 147 // started with the same machine id. 148 // 149 // Callers may attempt to distribute instances across a set of 150 // availability zones. If one zone fails, then the caller is expected 151 // to attempt in another zone. If the provider can determine that 152 // the StartInstanceParams can never be fulfilled in any zone, then 153 // it may return an error satisfying the IsAvailabilityZoneIndependent 154 // function in this package. 155 StartInstance(ctx context.ProviderCallContext, args StartInstanceParams) (*StartInstanceResult, error) 156 157 // StopInstances shuts down the instances with the specified IDs. 158 // Unknown instance IDs are ignored, to enable idempotency. 159 StopInstances(context.ProviderCallContext, ...instance.Id) error 160 161 // AllInstances returns all instances currently known to the broker. 162 AllInstances(ctx context.ProviderCallContext) ([]instances.Instance, error) 163 164 // MaintainInstance is used to run actions on jujud startup for existing 165 // instances. It is currently only used to ensure that LXC hosts have the 166 // correct network configuration. 167 MaintainInstance(ctx context.ProviderCallContext, args StartInstanceParams) error 168 } 169 170 // LXDProfiler defines an interface for dealing with lxd profiles used to 171 // deploy juju machines and containers. 172 type LXDProfiler interface { 173 // MaybeWriteLXDProfile, write given LXDProfile to if not already there. 174 MaybeWriteLXDProfile(pName string, put *charm.LXDProfile) error 175 176 // LXDProfileNames returns all the profiles associated to a container name 177 LXDProfileNames(containerName string) ([]string, error) 178 179 // ReplaceOrAddInstanceProfile replaces, adds, a charm profile to 180 // the given instance and returns a slice of LXD profiles applied 181 // to the instance. Replace happens inplace in the current order of 182 // applied profiles. If the LXDProfile ptr is nil, replace becomes 183 // remove. 184 ReplaceOrAddInstanceProfile(instId, oldProfile, newProfile string, put *charm.LXDProfile) ([]string, error) 185 }