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