Documentation

Index

Constants

View Source
const (
	// MinRootDiskSizeGiB is the minimum size for the root disk of an
	// instance, in Gigabytes. This value accommodates the anticipated
	// size of the initial image, any updates, and future application
	// data.
	MinRootDiskSizeGiB uint64 = 8
)
View Source
const StateFile = "provider-state"

    StateFile is the name of the file where the provider's state is stored.

    Variables

    View Source
    var FinishBootstrap = func(
    	ctx environs.BootstrapContext,
    	client ssh.Client,
    	env environs.Environ,
    	inst instance.Instance,
    	instanceConfig *instancecfg.InstanceConfig,
    ) error {
    	interrupted := make(chan os.Signal, 1)
    	ctx.InterruptNotify(interrupted)
    	defer ctx.StopInterruptNotify(interrupted)
    
    	nonceFile := utils.ShQuote(path.Join(instanceConfig.DataDir, cloudconfig.NonceFile))
    	checkNonceCommand := fmt.Sprintf(`
    	noncefile=%s
    	if [ ! -e "$noncefile" ]; then
    		echo "$noncefile does not exist" >&2
    		exit 1
    	fi
    	content=$(cat $noncefile)
    	if [ "$content" != %s ]; then
    		echo "$noncefile contents do not match machine nonce" >&2
    		exit 1
    	fi
    	`, nonceFile, utils.ShQuote(instanceConfig.MachineNonce))
    	addr, err := waitSSH(
    		ctx,
    		interrupted,
    		client,
    		checkNonceCommand,
    		&refreshableInstance{inst, env},
    		instanceConfig.Config.BootstrapSSHOpts(),
    	)
    	if err != nil {
    		return err
    	}
    	return ConfigureMachine(ctx, client, addr, instanceConfig)
    }

      FinishBootstrap completes the bootstrap process by connecting to the instance via SSH and carrying out the cloud-config.

      Note: FinishBootstrap is exposed so it can be replaced for testing.

      View Source
      var LongAttempt = utils.AttemptStrategy{
      	Total: 3 * time.Minute,
      	Delay: 1 * time.Second,
      }

        A request may fail to due "eventual consistency" semantics, which should resolve fairly quickly. These delays are specific to the provider and best tuned there. Other requests fail due to a slow state transition (e.g. an instance taking a while to release a security group after termination). If you need to poll for the latter kind, use LongAttempt.

        View Source
        var ShortAttempt = utils.AttemptStrategy{
        	Total: 5 * time.Second,
        	Delay: 200 * time.Millisecond,
        }

          Use ShortAttempt to poll for short-term events. TODO: This may need tuning for different providers (or even environments).

          Functions

          func AddStateInstance

          func AddStateInstance(stor storage.Storage, id instance.Id) error

            AddStateInstance adds a state-server instance ID to the provider-state file in storage.

            func Bootstrap

            func Bootstrap(ctx environs.BootstrapContext, env environs.Environ, args environs.BootstrapParams,
            ) (arch, series string, _ environs.BootstrapFinalizer, err error)

              Bootstrap is a common implementation of the Bootstrap method defined on environs.Environ; we strongly recommend that this implementation be used when writing a new provider.

              func BootstrapInstance

                BootstrapInstance creates a new instance with the series and architecture of its choice, constrained to those of the available tools, and returns the instance result, series, and a function that must be called to finalize the bootstrap process by transferring the tools and installing the initial Juju state server. This method is called by Bootstrap above, which implements environs.Bootstrap, but is also exported so that providers can manipulate the started instance.

                func ConfigureMachine

                func ConfigureMachine(ctx environs.BootstrapContext, client ssh.Client, host string, instanceConfig *instancecfg.InstanceConfig) error

                func CreateStateFile

                func CreateStateFile(stor storage.Storage) (string, error)

                  CreateStateFile creates an empty state file on the given storage, and returns its URL.

                  func DeleteStateFile

                  func DeleteStateFile(stor storage.Storage) error

                    DeleteStateFile deletes the state file on the given storage.

                    func Destroy

                    func Destroy(env environs.Environ) error

                      Destroy is a common implementation of the Destroy method defined on environs.Environ; we strongly recommend that this implementation be used when writing a new provider.

                      func DistributeInstances

                      func DistributeInstances(env ZonedEnviron, candidates, group []instance.Id) ([]instance.Id, error)

                        DistributeInstances is a common function for implement the state.InstanceDistributor policy based on availability zone spread.

                        func EnvFullName

                        func EnvFullName(env environs.Environ) string

                          EnvFullName returns a string based on the provided environment that is suitable for identifying the env on a provider. The resulting string clearly associates the value with juju, whereas the environment's UUID alone isn't very distinctive for humans. This benefits users by helping them quickly identify in their hosting management tools which instances are juju related.

                          func MachineFullName

                          func MachineFullName(env environs.Environ, machineID string) string

                            MachineFullName returns a string based on the provided environment and machine ID that is suitable for identifying instances on a provider. See EnvFullName for an explanation on how this function helps juju users.

                            func MiBToGiB

                            func MiBToGiB(m uint64) uint64

                              MiBToGiB converts the provided megabytes (base-2) into the nearest gigabytes (base-2), rounding up. This is useful for providers that deal in gigabytes (while juju deals in megabytes).

                              func ProviderStateInstances

                              func ProviderStateInstances(
                              	env environs.Environ,
                              	stor storage.StorageReader,
                              ) ([]instance.Id, error)

                                ProviderStateInstances extracts the instance IDs from provider-state.

                                func RemoveStateInstances

                                func RemoveStateInstances(stor storage.Storage, ids ...instance.Id) error

                                  RemoveStateInstances removes state-server instance IDs from the provider-state file in storage. Instance IDs that are not found in the file are ignored.

                                  func SaveState

                                  func SaveState(storage storage.StorageWriter, state *BootstrapState) error

                                    SaveState writes the given state to the given storage.

                                    func SupportedArchitectures

                                    func SupportedArchitectures(env environs.Environ, imageConstraint *imagemetadata.ImageConstraint) ([]string, error)

                                      SupportedArchitectures returns all the image architectures for env matching the constraints.

                                      Types

                                      type AvailabilityZone

                                      type AvailabilityZone interface {
                                      	// Name returns the name of the availability zone.
                                      	Name() string
                                      
                                      	// Available reports whether the availability zone is currently available.
                                      	Available() bool
                                      }

                                        AvailabilityZone describes a provider availability zone.

                                        type AvailabilityZoneInstances

                                        type AvailabilityZoneInstances struct {
                                        	// ZoneName is the name of the availability zone.
                                        	ZoneName string
                                        
                                        	// Instances is a set of instances within the availability zone.
                                        	Instances []instance.Id
                                        }

                                          AvailabilityZoneInstances describes an availability zone and a set of instances in that zone.

                                          func AvailabilityZoneAllocations

                                          func AvailabilityZoneAllocations(env ZonedEnviron, group []instance.Id) ([]AvailabilityZoneInstances, error)

                                            AvailabilityZoneAllocations returns the availability zones and their instance allocations from the specified group, in ascending order of population. Availability zones with the same population size are ordered by name.

                                            If the specified group is empty, then it will behave as if the result of AllInstances were provided.

                                            type BootstrapState

                                            type BootstrapState struct {
                                            	// StateInstances are the state servers.
                                            	StateInstances []instance.Id `yaml:"state-instances"`
                                            }

                                              BootstrapState is the state information that is stored in StateFile.

                                              Individual providers may define their own state structures instead of this one, and use their own code for loading and saving those, but this is the definition that most practically useful providers share unchanged.

                                              func LoadState

                                              func LoadState(stor storage.StorageReader) (*BootstrapState, error)

                                                LoadState reads state from the given storage.

                                                type SupportsUnitPlacementPolicy

                                                type SupportsUnitPlacementPolicy struct{}

                                                  SupportsUnitPlacementPolicy provides an implementation of SupportsUnitPlacement that never returns an error, and is intended for embedding in environs.Environ implementations.

                                                  func (*SupportsUnitPlacementPolicy) SupportsUnitPlacement

                                                  func (*SupportsUnitPlacementPolicy) SupportsUnitPlacement() error

                                                  type ZonedEnviron

                                                  type ZonedEnviron interface {
                                                  	environs.Environ
                                                  
                                                  	// AvailabilityZones returns all availability zones in the environment.
                                                  	AvailabilityZones() ([]AvailabilityZone, error)
                                                  
                                                  	// InstanceAvailabilityZoneNames returns the names of the availability
                                                  	// zones for the specified instances. The error returned follows the same
                                                  	// rules as Environ.Instances.
                                                  	InstanceAvailabilityZoneNames(ids []instance.Id) ([]string, error)
                                                  }

                                                    ZonedEnviron is an environs.Environ that has support for availability zones.