environs

package
v0.0.0-...-9ec3720 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 6, 2021 License: AGPL-3.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source 
const AdminUser = "admin"

AdminUser is the initial admin user created for all controllers.

Variables

View Source 
var (
	ErrNotBootstrapped  = errors.New("model is not bootstrapped")
	ErrNoInstances      = errors.NotFoundf("instances")
	ErrPartialInstances = errors.New("only some instances were found")
)
View Source 
var AddressesRefreshAttempt = utils.AttemptStrategy{
	Total: 3 * time.Minute,
	Delay: 1 * time.Second,
}

AddressesRefreshAttempt is the attempt strategy used when refreshing instance addresses.

View Source 
var DefaultSpaceInfo *network.SpaceInfo

DefaultSpaceInfo should be passed into Networking.ProviderSpaceInfo to get information about the default space.

View Source 
var SupportsNetworking = supportsNetworking

SupportsNetworking is a convenience helper to check if an environment supports networking. It returns an interface containing Environ and Networking in this case.

Functions

func APIInfo 

func APIInfo(
	ctx context.ProviderCallContext, controllerUUID, modelUUID, caCert string, apiPort int, env Environ,
) (*api.Info, error)

APIInfo returns an api.Info for the environment. The result is populated with addresses and CA certificate, but no tag or password.

func CheckProviderAPI 

func CheckProviderAPI(env InstanceBroker, ctx context.ProviderCallContext) error

CheckProviderAPI returns an error if a simple API call to check a basic response from the specified environ fails.

func Destroy 

func Destroy(
	controllerName string,
	env ControllerDestroyer,
	ctx context.ProviderCallContext,
	store jujuclient.ControllerStore,
) error

Destroy destroys the controller and, if successful, its associated configuration data from the given store.

func ImageMetadataSources 

func ImageMetadataSources(env BootstrapEnviron) ([]simplestreams.DataSource, error)

ImageMetadataSources returns the sources to use when looking for simplestreams image id metadata for the given stream.

func IsAvailabilityZoneIndependent 

func IsAvailabilityZoneIndependent(err error) bool

IsAvailabilityZoneIndependent reports whether or not the given error, or its cause, is independent of any particular availability zone. Juju uses this to decide whether or not to attempt the failed operation in another availability zone; zone-independent failures will not be reattempted.

If the error implements AvailabilityZoneError, then the result of calling its AvailabilityZoneIndependent method will be returned; otherwise this function returns false. That is, errors are assumed to be specific to an availability zone by default, so that they can be retried in another availability zone.

func RegisterImageDataSourceFunc 

func RegisterImageDataSourceFunc(id string, f ImageDataSourceFunc)

RegisterImageDataSourceFunc registers an ImageDataSourceFunc with the specified id, overwriting any function previously registered with the same id.

func RegisterProvider 

func RegisterProvider(name string, p CloudEnvironProvider, alias ...string) (unregister func())

RegisterProvider registers a new environment provider. Name gives the name of the provider, and p the interface to that provider.

RegisterProvider will panic if the provider name or any of the aliases are registered more than once. The return function can be used to unregister the provider and is used by tests.

func RegisterUserImageDataSourceFunc 

func RegisterUserImageDataSourceFunc(id string, f ImageDataSourceFunc)

RegisterUserImageDataSourceFunc registers an ImageDataSourceFunc with the specified id at the start of the search path, overwriting any function previously registered with the same id.

func RegisteredProviders 

func RegisteredProviders() []string

RegisteredProviders enumerate all the environ providers which have been registered.

func SupportsContainerAddresses 

func SupportsContainerAddresses(ctx context.ProviderCallContext, env BootstrapEnviron) bool

SupportsContainerAddresses checks if the environment will let us allocate addresses for containers from the host ranges.

func SupportsSpaces 

func SupportsSpaces(ctx context.ProviderCallContext, env BootstrapEnviron) bool

SupportsSpaces checks if the environment implements NetworkingEnviron and also if it supports spaces.

func UnregisterImageDataSourceFunc 

func UnregisterImageDataSourceFunc(id string)

UnregisterImageDataSourceFunc unregisters an ImageDataSourceFunc with the specified id.

Types

type AvailabilityZoneError 

type AvailabilityZoneError interface {
	error

	// AvailabilityZoneIndependent reports whether or not the
	// error is related to a specific availability zone.
	AvailabilityZoneIndependent() bool
}

AvailabilityZoneError provides an interface for compute providers to indicate whether or not an error is specific to, or independent of, any particular availability zone.

type BootstrapContext 

type BootstrapContext interface {
	GetStdin() io.Reader
	GetStdout() io.Writer
	GetStderr() io.Writer
	Infof(format string, params ...interface{})
	Verbosef(format string, params ...interface{})

	// InterruptNotify starts watching for interrupt signals
	// on behalf of the caller, sending them to the supplied
	// channel.
	InterruptNotify(sig chan<- os.Signal)

	// StopInterruptNotify undoes the effects of a previous
	// call to InterruptNotify with the same channel. After
	// StopInterruptNotify returns, no more signals will be
	// delivered to the channel.
	StopInterruptNotify(chan<- os.Signal)

	// ShouldVerifyCredentials indicates whether the caller's cloud
	// credentials should be verified.
	ShouldVerifyCredentials() bool

	// Context is the context.Context value for this bootstrap command.
	Context() context.Context
}

BootstrapContext is an interface that is passed to Environ.Bootstrap, providing a means of obtaining information about and manipulating the context in which it is being invoked.

type BootstrapDialOpts 

type BootstrapDialOpts struct {
	// Timeout is the amount of time to wait contacting a state
	// server.
	Timeout time.Duration

	// RetryDelay is the amount of time between attempts to connect to
	// an address.
	RetryDelay time.Duration

	// AddressesDelay is the amount of time between refreshing the
	// addresses.
	AddressesDelay time.Duration
}

BootstrapDialOpts contains the options for the synchronous part of the bootstrap procedure, where the CLI connects to the bootstrap machine to complete the process.

type BootstrapEnviron 

type BootstrapEnviron interface {
	Configer
	Bootstrapper
	ConstraintsChecker

	CloudDestroyer
	ControllerDestroyer

	// Environ implements storage.ProviderRegistry for acquiring
	// environ-scoped storage providers supported by the Environ.
	// StorageProviders returned from Environ.StorageProvider will
	// be scoped specifically to that Environ.
	storage.ProviderRegistry

	// Create creates the environment for a new hosted model.
	//
	// This will be called before any workers begin operating on the
	// Environ, to give an Environ a chance to perform operations that
	// are required for further use.
	//
	// Create is not called for the initial controller model; it is
	// the Bootstrap method's job to create the controller model.
	Create(context.ProviderCallContext, CreateParams) error
}

BootstrapEnviron is an interface that an EnvironProvider implements in order to bootstrap a controller.

type BootstrapParams 

type BootstrapParams struct {
	// Cloud contains the name of the cloud that Juju will be
	// bootstrapped in. Used for printing feedback during bootstrap.
	CloudName string

	// CloudRegion is the name of the cloud region that Juju will be
	// bootstrapped in. Used for printing feedback during bootstrap.
	CloudRegion string

	// ControllerConfig contains the configuration attributes for the
	// bootstrapped controller.
	ControllerConfig controller.Config

	// ModelConstraints are merged with the bootstrap constraints
	// to choose the initial instance, and will be stored in the new
	// environment's state.
	ModelConstraints constraints.Value

	// BootstrapConstraints, in conjunction with ModelConstraints,
	// are used to choose the initial instance. BootstrapConstraints
	// will not be stored in state for the environment.
	BootstrapConstraints constraints.Value

	// StoragePools is one or more named storage pools to create
	// in the controller model.
	StoragePools map[string]storage.Attrs

	// BootstrapSeries, if specified, is the series to use for the
	// initial bootstrap machine.
	BootstrapSeries string

	// SupportedBootstrapSeries is a supported set of series to use for
	// validating against the bootstrap series.
	SupportedBootstrapSeries set.Strings

	// Placement, if non-empty, holds an environment-specific placement
	// directive used to choose the initial instance.
	Placement string

	// AvailableTools is a collection of tools which the Bootstrap method
	// may use to decide which architecture/series to instantiate.
	AvailableTools tools.List

	// ContainerBridgeName, if non-empty, overrides the default
	// network bridge device to use for LXC and KVM containers. See
	// also instancecfg.DefaultBridgeName.
	ContainerBridgeName string

	// ImageMetadata contains simplestreams image metadata for providers
	// that rely on it for selecting images. This will be empty for
	// providers that do not implements simplestreams.HasRegion.
	ImageMetadata []*imagemetadata.ImageMetadata

	// ExtraAgentValuesForTesting are testing only values written to the agent config file.
	ExtraAgentValuesForTesting map[string]string

	// Force is used to allow a bootstrap to be run on unsupported series.
	Force bool
}

BootstrapParams holds the parameters for bootstrapping an environment.

type BootstrapResult 

type BootstrapResult struct {
	// Arch is the instance's architecture.
	Arch string

	// Series is the instance's series.
	Series string

	// CloudBootstrapFinalizer is a function that must be called finalize the
	// bootstrap process by transferring the tools and installing the
	// initial Juju controller.
	CloudBootstrapFinalizer

	// CaasBootstrapFinalizer is the finalizer for caas.
	CaasBootstrapFinalizer
}

BootstrapResult holds the data returned by calls to Environ.Bootstrap.

type Bootstrapper 

type Bootstrapper interface {
	// This will be called very early in the bootstrap procedure, to
	// give an Environ a chance to perform interactive operations that
	// are required for bootstrapping.
	PrepareForBootstrap(ctx BootstrapContext, controllerName string) error

	// Bootstrap creates a new environment, and an instance to host the
	// controller for that environment. The instance will have the
	// series and architecture of the Environ's choice, constrained to
	// those of the available tools. Bootstrap will return the instance's
	// architecture, series, and a function that must be called to finalize
	// the bootstrap process by transferring the tools and installing the
	// initial Juju controller.
	//
	// It is possible to direct Bootstrap to use a specific architecture
	// (or fail if it cannot start an instance of that architecture) by
	// using an architecture constraint; this will have the effect of
	// limiting the available tools to just those matching the specified
	// architecture.
	Bootstrap(ctx BootstrapContext, callCtx context.ProviderCallContext, params BootstrapParams) (*BootstrapResult, error)
}

Bootstrapper provides the way for bootstrapping controller.

type CaasBootstrapFinalizer 

type CaasBootstrapFinalizer func(BootstrapContext, *podcfg.ControllerPodConfig, BootstrapDialOpts) error

CaasBootstrapFinalizer is a function returned from Environ.Bootstrap. The caller must pass a ControllerPodConfig with the Tools field set.

type CloudBootstrapFinalizer 

type CloudBootstrapFinalizer func(BootstrapContext, *instancecfg.InstanceConfig, BootstrapDialOpts) error

CloudBootstrapFinalizer is a function returned from Environ.Bootstrap. The caller must pass a InstanceConfig with the Tools field set.

type CloudDestroyer 

type CloudDestroyer interface {
	// Destroy shuts down all known machines and destroys the
	// rest of the environment. Note that on some providers,
	// very recently started instances may not be destroyed
	// because they are not yet visible.
	//
	// When Destroy has been called, any Environ referring to the
	// same remote environment may become invalid.
	Destroy(ctx context.ProviderCallContext) error
}

CloudDestroyer provides the API to cleanup cloud resources.

type CloudDetector 

type CloudDetector interface {
	// DetectCloud attempts to detect a cloud with the given name
	// from the environment. This may involve, for example,
	// inspecting environment variables, or returning special
	// hard-coded regions (e.g. "localhost" for lxd).
	//
	// If no cloud can be detected, DetectCloud should return
	// an error satisfying errors.IsNotFound.
	//
	// DetectCloud should be used in preference to DetectClouds
	// when a specific cloud is identified, as this may be more
	// efficient.
	DetectCloud(name string) (cloud.Cloud, error)

	// DetectClouds detects clouds from the environment. This may
	// involve, for example, inspecting environment variables, or
	// returning special hard-coded regions (e.g. "localhost" for lxd).
	DetectClouds() ([]cloud.Cloud, error)
}

CloudDetector is an interface that an EnvironProvider implements in order to automatically detect clouds from the environment.

type CloudEnvironProvider 

type CloudEnvironProvider interface {
	EnvironProvider
	// Open opens the environment and returns it. The configuration must
	// have passed through PrepareConfig at some point in its lifecycle.
	//
	// Open should not perform any expensive operations, such as querying
	// the cloud API, as it will be called frequently.
	Open(OpenParams) (Environ, error)
}

A CloudEnvironProvider represents a computing and storage provider for a traditional cloud like AWS or Openstack.

type CloudFinalizer 

type CloudFinalizer interface {
	// FinalizeCloud finalizes a cloud definition, updating any attributes
	// as necessary. This is always done client-side, before bootstrapping.
	FinalizeCloud(FinalizeCloudContext, cloud.Cloud) (cloud.Cloud, error)
}

CloudFinalizer is an interface that an EnvironProvider implements in order to finalize a cloud.Cloud definition before bootstrapping.

type CloudRegionDetector 

type CloudRegionDetector interface {
	// DetectRegions automatically detects one or more regions
	// from the environment. This may involve, for example, inspecting
	// environment variables, or returning special hard-coded regions
	// (e.g. "localhost" for lxd). The first item in the list will be
	// considered the default region for bootstrapping if the user
	// does not specify one.
	//
	// If no regions can be detected, DetectRegions should return
	// an error satisfying errors.IsNotFound.
	DetectRegions() ([]cloud.Region, error)
}

CloudRegionDetector is an interface that an EnvironProvider implements in order to automatically detect cloud regions from the environment.

type CloudSpecSetter 

type CloudSpecSetter interface {
	// SetConfig updates the Environ's configuration.
	SetCloudSpec(spec environscloudspec.CloudSpec) error
}

CloudSpecSetter implements access to an environment's cloud spec.

type ConfigGetter 

type ConfigGetter interface {
	// Config returns the configuration data with which the Environ was created.
	// Note that this is not necessarily current; the canonical location
	// for the configuration data is stored in the state.
	Config() *config.Config
}

ConfigGetter implements access to an environment's configuration.

type ConfigSetter 

type ConfigSetter interface {
	// SetConfig updates the Environ's configuration.
	//
	// Calls to SetConfig do not affect the configuration of
	// values previously obtained from Storage.
	SetConfig(cfg *config.Config) error
}

ConfigSetter implements access to an environment's configuration.

type Configer 

type Configer interface {
	ConfigGetter
	ConfigSetter
}

Configer implements access to an environment's configuration.

type ConnectorInfo 

type ConnectorInfo interface {
	ConnectionProxyInfo() (proxy.Proxier, error)
}

type ConstraintsChecker 

type ConstraintsChecker interface {
	// ConstraintsValidator returns a Validator instance which
	// is used to validate and merge constraints.
	ConstraintsValidator(ctx context.ProviderCallContext) (constraints.Validator, error)
}

ConstraintsChecker provides a means to check that constraints are valid.

type ControllerDestroyer 

type ControllerDestroyer interface {
	DestroyController(ctx context.ProviderCallContext, controllerUUID string) error
}

ControllerDestroyer is similar to Destroy() in that it destroys the model, which in this case will be the controller model.

In addition, this method also destroys any resources relating to hosted models on the controller on which it is invoked. This ensures that "kill-controller" can clean up hosted models when the Juju controller process is unavailable.

type CreateParams 

type CreateParams struct {
	// ControllerUUID is the UUID of the controller to be that is creating
	// the Environ.
	ControllerUUID string
}

CreateParams contains the parameters for Environ.Create.

type DefaultConstraintsChecker 

type DefaultConstraintsChecker interface {
	// ShouldApplyControllerConstraints returns if bootstrapping logic should
	// use default constraints
	ShouldApplyControllerConstraints() bool
}

DefaultConstraintsChecker defines an interface for checking if the default constraints should be applied for the Environ provider when bootstrapping the provider.

type Environ 

type Environ interface {
	BootstrapEnviron

	// ResourceAdopter defines methods for adopting resources.
	ResourceAdopter

	// InstanceBroker defines methods for starting and stopping
	// instances.
	InstanceBroker

	InstanceLister

	// ControllerInstances returns the IDs of instances corresponding
	// to Juju controller, having the specified controller UUID.
	// If there are no controller instances, ErrNoInstances is returned.
	// If it can be determined that the environment has not been bootstrapped,
	// then ErrNotBootstrapped should be returned instead.
	ControllerInstances(ctx context.ProviderCallContext, controllerUUID string) ([]instance.Id, error)

	// Provider returns the EnvironProvider that created this Environ.
	Provider() EnvironProvider

	InstancePrechecker

	// InstanceTypesFetcher represents an environment that can return
	// information about the available instance types.
	InstanceTypesFetcher
}

An Environ represents a Juju environment.

Due to the limitations of some providers (for example ec2), the results of the Environ methods may not be fully sequentially consistent. In particular, while a provider may retry when it gets an error for an operation, it will not retry when an operation succeeds, even if that success is not consistent with a previous operation.

Even though Juju takes care not to share an Environ between concurrent workers, it does allow concurrent method calls into the provider implementation. The typical provider implementation needs locking to avoid undefined behaviour when the configuration changes.

func GetEnviron 

func GetEnviron(st EnvironConfigGetter, newEnviron NewEnvironFunc) (Environ, error)

GetEnviron returns the environs.Environ ("provider") associated with the model.

func GetEnvironAndCloud 

func GetEnvironAndCloud(st EnvironConfigGetter, newEnviron NewEnvironFunc) (Environ, *environscloudspec.CloudSpec, error)

GetEnvironAndCloud returns the environs.Environ ("provider") and cloud associated with the model.

func New 

func New(args OpenParams) (Environ, error)

New returns a new environment based on the provided configuration.

func Open 

func Open(p EnvironProvider, args OpenParams) (Environ, error)

Open creates an Environ instance and errors if the provider is not for a cloud.

type EnvironConfigGetter 

type EnvironConfigGetter interface {
	ModelConfig() (*config.Config, error)
	CloudSpec() (environscloudspec.CloudSpec, error)
}

EnvironConfigGetter exposes a model configuration to its clients.

type EnvironProvider 

type EnvironProvider interface {
	config.Validator
	ProviderCredentials

	// Version returns the version of the provider. This is recorded as the
	// environ version for each model, and used to identify which upgrade
	// operations to run when upgrading a model's environ. Providers should
	// start out at version 0.
	Version() int

	// CloudSchema returns the schema used to validate input for add-cloud.  If
	// a provider does not support custom clouds, CloudSchema should return
	// nil.
	CloudSchema() *jsonschema.Schema

	// Ping tests the connection to the cloud, to verify the endpoint is valid.
	Ping(ctx context.ProviderCallContext, endpoint string) error

	// PrepareConfig prepares the configuration for a new model, based on
	// the provided arguments. PrepareConfig is expected to produce a
	// deterministic output. Any unique values should be based on the
	// "uuid" attribute of the base configuration. This is called for the
	// controller model during bootstrap, and also for new hosted models.
	PrepareConfig(PrepareConfigParams) (*config.Config, error)
}

A EnvironProvider represents a computing and storage provider for either a traditional cloud or a container substrate like k8s.

func Provider 

func Provider(providerType string) (EnvironProvider, error)

Provider returns the previously registered provider with the given type.

type FinalizeCloudContext 

type FinalizeCloudContext interface {
	// Verbosef will write the formatted string to Stderr if the
	// verbose flag is true, and to the logger if not.
	Verbosef(string, ...interface{})
}

FinalizeCloudContext is an interface passed into FinalizeCloud to provide a means of interacting with the user when finalizing a cloud definition.

type FinalizeCredentialContext 

type FinalizeCredentialContext interface {
	GetStderr() io.Writer
}

FinalizeCredentialContext is an interface passed into FinalizeCredential to provide a means of interacting with the user when finalizing credentials.

type FinalizeCredentialParams 

type FinalizeCredentialParams struct {
	// Credential is the credential that the provider should finalize.
	Credential cloud.Credential

	// CloudEndpoint is the endpoint for the cloud that the credentials are
	// for. This may be used by the provider to communicate with the cloud
	// to finalize the credentials.
	CloudEndpoint string

	// CloudStorageEndpoint is the storage endpoint for the cloud that the
	// credentials are for. This may be used by the provider to communicate
	// with the cloud to finalize the credentials.
	CloudStorageEndpoint string

	// CloudIdentityEndpoint is the identity endpoint for the cloud that the
	// credentials are for. This may be used by the provider to communicate
	// with the cloud to finalize the credentials.
	CloudIdentityEndpoint string
}

FinalizeCredentialParams contains the parameters for ProviderCredentials.FinalizeCredential.

type FirewallFeatureQuerier 

type FirewallFeatureQuerier interface {
	// SupportsRulesWithIPV6CIDRs returns true if the environment supports
	// ingress rules containing IPV6 CIDRs.
	SupportsRulesWithIPV6CIDRs(ctx context.ProviderCallContext) (bool, error)
}

FirewallFeatureQuerier exposes methods for detecting what features the environment firewall supports.

type Firewaller 

type Firewaller interface {
	// OpenPorts opens the given port ranges for the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	OpenPorts(ctx context.ProviderCallContext, rules firewall.IngressRules) error

	// ClosePorts closes the given port ranges for the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	ClosePorts(ctx context.ProviderCallContext, rules firewall.IngressRules) error

	// IngressRules returns the ingress rules applied to the whole environment.
	// Must only be used if the environment was setup with the
	// FwGlobal firewall mode.
	// It is expected that there be only one ingress rule result for a given
	// port range - the rule's SourceCIDRs will contain all applicable source
	// address rules for that port range.
	IngressRules(ctx context.ProviderCallContext) (firewall.IngressRules, error)
}

Firewaller exposes methods for managing network ports.

type HardwareCharacteristicsDetector 

type HardwareCharacteristicsDetector interface {
	// DetectSeries returns the series for the controller instance.
	DetectSeries() (string, error)
	// DetectHardware returns the hardware characteristics for the
	// controller instance.
	DetectHardware() (*instance.HardwareCharacteristics, error)
}

HardwareCharacteristicsDetector is implemented by environments that can provide advance information about the series and hardware for controller instances that have not been provisioned yet.

type ImageDataSourceFunc 

type ImageDataSourceFunc func(Environ) (simplestreams.DataSource, error)

ImageDataSourceFunc is a function type that takes an environment and returns a simplestreams datasource.

ImageDataSourceFunc will be used in ImageMetadataSources. Any error satisfying errors.IsNotSupported will be ignored; any other error will be cause ImageMetadataSources to fail.

type InstanceBroker 

type InstanceBroker interface {
	// StartInstance asks for a new instance to be created, associated with
	// the provided config in machineConfig. The given config describes the
	// juju state for the new instance to connect to. The config
	// MachineNonce, which must be unique within an environment, is used by
	// juju to protect against the consequences of multiple instances being
	// started with the same machine id.
	//
	// Callers may attempt to distribute instances across a set of
	// availability zones. If one zone fails, then the caller is expected
	// to attempt in another zone. If the provider can determine that
	// the StartInstanceParams can never be fulfilled in any zone, then
	// it may return an error satisfying the IsAvailabilityZoneIndependent
	// function in this package.
	StartInstance(ctx context.ProviderCallContext, args StartInstanceParams) (*StartInstanceResult, error)

	// StopInstances shuts down the instances with the specified IDs.
	// Unknown instance IDs are ignored, to enable idempotency.
	StopInstances(context.ProviderCallContext, ...instance.Id) error

	// AllInstances returns all instances currently known to the broker.
	AllInstances(ctx context.ProviderCallContext) ([]instances.Instance, error)

	// AllRunningInstances returns all running, available instances currently known to the broker.
	AllRunningInstances(ctx context.ProviderCallContext) ([]instances.Instance, error)
}

TODO(wallyworld) - we want this in the environs/instance package but import loops stop that from being possible right now.

type InstanceLister 

type InstanceLister interface {
	// Instances returns a slice of instances corresponding to the
	// given instance ids.  If no instances were found, but there
	// was no other error, it will return ErrNoInstances.  If
	// some but not all the instances were found, the returned slice
	// will have some nil slots, and an ErrPartialInstances error
	// will be returned.
	Instances(ctx context.ProviderCallContext, ids []instance.Id) ([]instances.Instance, error)
}

InstanceLister provider api to list instances for specified instance ids.

type InstancePrechecker 

type InstancePrechecker interface {
	// PrecheckInstance performs a preflight check on the specified
	// series and constraints, ensuring that they are possibly valid for
	// creating an instance in this model.
	//
	// PrecheckInstance is best effort, and not guaranteed to eliminate
	// all invalid parameters. If PrecheckInstance returns nil, it is not
	// guaranteed that the constraints are valid; if a non-nil error is
	// returned, then the constraints are definitely invalid.
	PrecheckInstance(context.ProviderCallContext, PrecheckInstanceParams) error
}

InstancePrechecker provides a means of "prechecking" instance arguments before recording them in state.

type InstanceTagger 

type InstanceTagger interface {
	// TagInstance tags the given instance with the specified tags.
	//
	// The specified tags will replace any existing ones with the
	// same names, but other existing tags will be left alone.
	TagInstance(ctx context.ProviderCallContext, id instance.Id, tags map[string]string) error
}

InstanceTagger is an interface that can be used for tagging instances.

type InstanceTypesFetcher 

type InstanceTypesFetcher interface {
	InstanceTypes(context.ProviderCallContext, constraints.Value) (instances.InstanceTypesWithCostMetadata, error)
}

InstanceTypesFetcher is an interface that allows for instance information from a provider to be obtained.

type JujuUpgradePrechecker 

type JujuUpgradePrechecker interface {
	// PreparePrechecker is called to to give an Environ a chance to
	// perform interactive operations that are required for prechecking
	// an upgrade.
	PreparePrechecker() error

	// PrecheckUpgradeOperations returns a list of
	// PrecheckJujuUpgradeOperations for checking if juju can be upgrade.
	PrecheckUpgradeOperations() []PrecheckJujuUpgradeOperation
}

JujuUpgradePrechecker is an interface that can be used to precheck the Environs before upgrading juju. If an Environ implements this interface, its PrecheckUpgradeOperations method will be invoked to identify operations that should be run to check if an juju upgrade is possible.

type LXDProfiler 

type LXDProfiler interface {
	// AssignLXDProfiles assigns the given profile names to the lxd instance
	// provided.  The slice of ProfilePosts provides details for adding to
	// and removing profiles from the lxd server.
	AssignLXDProfiles(instID string, profilesNames []string, profilePosts []lxdprofile.ProfilePost) ([]string, error)

	// MaybeWriteLXDProfile, write given LXDProfile to if not already there.
	MaybeWriteLXDProfile(pName string, put lxdprofile.Profile) error

	// LXDProfileNames returns all the profiles associated to a container name
	LXDProfileNames(containerName string) ([]string, error)
}

LXDProfiler defines an interface for dealing with lxd profiles used to deploy juju machines and containers.

type ModelConfigUpgrader 

type ModelConfigUpgrader interface {
	// UpgradeConfig upgrades an old environment configuration by adding,
	// updating or removing attributes. UpgradeConfig must be idempotent,
	// as it may be called multiple times in the event of a partial upgrade.
	//
	// NOTE(axw) this is currently only called when upgrading to 1.25.
	// We should update the upgrade machinery to call this for every
	// version upgrade, so the upgrades package is not tightly coupled
	// to provider upgrades.
	// TODO (anastasiamac 2018-04-27) Since it is only for 1.25, do we still need it?
	UpgradeConfig(cfg *config.Config) (*config.Config, error)
}

ModelConfigUpgrader is an interface that an EnvironProvider may implement in order to modify environment configuration on agent upgrade.

type Networking 

type Networking interface {
	// Subnets returns basic information about subnets known
	// by the provider for the environment.
	Subnets(
		ctx context.ProviderCallContext, inst instance.Id, subnetIds []network.Id,
	) ([]network.SubnetInfo, error)

	// SuperSubnets returns information about aggregated subnets - eg. global CIDR
	// for EC2 VPC.
	SuperSubnets(ctx context.ProviderCallContext) ([]string, error)

	// NetworkInterfaces returns a slice with the network interfaces that
	// correspond to the given instance IDs. If no instances where found,
	// but there was no other error, it will return ErrNoInstances. If some
	// but not all of the instances were found, the returned slice will
	// have some nil slots, and an ErrPartialInstances error will be
	// returned.
	NetworkInterfaces(ctx context.ProviderCallContext, ids []instance.Id) ([]network.InterfaceInfos, error)

	// SupportsSpaces returns whether the current environment supports
	// spaces. The returned error satisfies errors.IsNotSupported(),
	// unless a general API failure occurs.
	SupportsSpaces(ctx context.ProviderCallContext) (bool, error)

	// SupportsSpaceDiscovery returns whether the current environment
	// supports discovering spaces from the provider. The returned error
	// satisfies errors.IsNotSupported(), unless a general API failure occurs.
	SupportsSpaceDiscovery(ctx context.ProviderCallContext) (bool, error)

	// Spaces returns a slice of network.SpaceInfo with info, including
	// details of all associated subnets, about all spaces known to the
	// provider that have subnets available.
	Spaces(ctx context.ProviderCallContext) ([]network.SpaceInfo, error)

	// ProviderSpaceInfo returns the details of the space requested as
	// a ProviderSpaceInfo. This will contain everything needed to
	// decide whether an Environ of the same type in another
	// controller could route to the space. Details for the default
	// space can be retrieved by passing DefaultSpaceInfo (which is nil).
	//
	// This method accepts a SpaceInfo with details of the space that
	// we need provider details for - this is the Juju model's view of
	// what subnets are in the space. If the provider supports spaces
	// and space discovery then it is the authority on what subnets
	// are actually in the space, and it's free to collect the full
	// space and subnet info using the space's ProviderId (discarding
	// the subnet details passed in which might be out-of date).
	//
	// If the provider doesn't support space discovery then the Juju
	// model's opinion of what subnets are in the space is
	// authoritative. In that case the provider should collect up any
	// other information needed to determine routability and include
	// the passed-in space info in the ProviderSpaceInfo returned.
	ProviderSpaceInfo(ctx context.ProviderCallContext, space *network.SpaceInfo) (*ProviderSpaceInfo, error)

	// AreSpacesRoutable returns whether the communication between the
	// two spaces can use cloud-local addresses.
	AreSpacesRoutable(ctx context.ProviderCallContext, space1, space2 *ProviderSpaceInfo) (bool, error)

	// SupportsContainerAddresses returns true if the current environment is
	// able to allocate addresses for containers. If returning false, we also
	// return an IsNotSupported error.
	SupportsContainerAddresses(ctx context.ProviderCallContext) (bool, error)

	// AllocateContainerAddresses allocates a static address for each of the
	// container NICs in preparedInfo, hosted by the hostInstanceID. Returns the
	// network config including all allocated addresses on success.
	AllocateContainerAddresses(ctx context.ProviderCallContext, hostInstanceID instance.Id, containerTag names.MachineTag, preparedInfo network.InterfaceInfos) (network.InterfaceInfos, error)

	// ReleaseContainerAddresses releases the previously allocated
	// addresses matching the interface details passed in.
	ReleaseContainerAddresses(ctx context.ProviderCallContext, interfaces []network.ProviderInterfaceInfo) error

	// SSHAddresses filters the input addresses to those suitable for SSH use.
	// Usually we would have the provider deal only with ProviderAddresses.
	// This method is called from the sshclient API facade to filter addresses
	// obtained from a `state.Machine` (which are SpaceAddresses).
	// At the time of writing, each provider generally does one of two things:
	// - just returns all the addresses back or;
	// - returns a subset based on public scope matching.
	// The address `Value` is then returned to the client,
	// which is just a string, so we do not actually leak a SpaceAddress.
	SSHAddresses(ctx context.ProviderCallContext, addresses network.SpaceAddresses) (network.SpaceAddresses, error)
}

Networking interface defines methods that environments with networking capabilities must implement.

type NetworkingEnviron 

type NetworkingEnviron interface {
	// Environ represents a juju environment.
	Environ

	// Networking defines the methods of networking capable environments.
	Networking
}

NetworkingEnviron combines the standard Environ interface with the functionality for networking.

type NewEnvironFunc 

type NewEnvironFunc func(OpenParams) (Environ, error)

NewEnvironFunc is the type of a function that, given a model config, returns an Environ. This will typically be environs.New.

type OpenParams 

type OpenParams struct {
	// ControllerUUID is the controller UUID.
	ControllerUUID string

	// Cloud is the cloud specification to use to connect to the cloud.
	Cloud environscloudspec.CloudSpec

	// Config is the base configuration for the provider.
	Config *config.Config
}

OpenParams contains the parameters for EnvironProvider.Open.

type PrecheckInstanceParams 

type PrecheckInstanceParams struct {
	// Series contains the series of the machine.
	Series string

	// Constraints contains the machine constraints.
	Constraints constraints.Value

	// Placement contains the machine placement directive, if any.
	Placement string

	// VolumeAttachments contains the parameters for attaching existing
	// volumes to the instance. The PrecheckInstance method should not
	// expect the attachment's Machine field to be set, as PrecheckInstance
	// may be called before a machine ID is allocated.
	VolumeAttachments []storage.VolumeAttachmentParams
}

PrecheckInstanceParams contains the parameters for InstancePrechecker.PrecheckInstance.

type PrecheckJujuUpgradeOperation 

type PrecheckJujuUpgradeOperation struct {
	// TargetVersion is the target juju version.
	TargetVersion version.Number

	// Steps contains the sequence of upgrade steps to apply when
	// upgrading to the accompanying target version number.
	Steps []PrecheckJujuUpgradeStep
}

PrecheckJujuUpgradeOperation contains a target agent version and sequence of upgrade precheck steps to apply to get to that version.

type PrecheckJujuUpgradeStep 

type PrecheckJujuUpgradeStep interface {
	// Description is a human readable description of what the
	// precheck upgrade step does.
	Description() string

	// Run executes the precheck upgrade business logic.
	Run() error
}

PrecheckJujuUpgradeStep defines an idempotent operation that is run a specific precheck upgrade step on an Environ.

type PrepareConfigParams 

type PrepareConfigParams struct {
	// Cloud is the cloud specification to use to connect to the cloud.
	Cloud environscloudspec.CloudSpec

	// Config is the base configuration for the provider. This should
	// be updated with the region, endpoint and credentials.
	Config *config.Config
}

PrepareConfigParams contains the parameters for EnvironProvider.PrepareConfig.

type ProviderCredentials 

type ProviderCredentials interface {
	// CredentialSchemas returns credential schemas, keyed on
	// authentication type. These may be used to validate existing
	// credentials, or to generate new ones (e.g. to create an
	// interactive form.)
	CredentialSchemas() map[cloud.AuthType]cloud.CredentialSchema

	// DetectCredentials automatically detects one or more credentials
	// from the environment. This may involve, for example, inspecting
	// environment variables, or reading configuration files in
	// well-defined locations.
	//
	// If no credentials can be detected, DetectCredentials should
	// return an error satisfying errors.IsNotFound.
	DetectCredentials() (*cloud.CloudCredential, error)

	// FinalizeCredential finalizes a credential, updating any attributes
	// as necessary. This is always done client-side, when adding the
	// credential to credentials.yaml and before uploading credentials to
	// the controller. The provider may completely alter a credential, even
	// going as far as changing the auth-type, but the output must be a
	// fully formed credential.
	FinalizeCredential(
		FinalizeCredentialContext,
		FinalizeCredentialParams,
	) (*cloud.Credential, error)
}

ProviderCredentials is an interface that an EnvironProvider implements in order to validate and automatically detect credentials for clouds supported by the provider.

TODO(axw) replace CredentialSchemas with an updated environschema. The Dashboard also needs to be able to handle multiple credential types, and dependencies in config attributes.

type ProviderCredentialsRegister 

type ProviderCredentialsRegister interface {

	// RegisterCredentials will return any credentials that need to be
	// registered for the provider.
	//
	// If no credentials can be found, RegisterCredentials should return
	// an error satisfying errors.IsNotFound.
	RegisterCredentials(cloud.Cloud) (map[string]*cloud.CloudCredential, error)
}

ProviderCredentialsRegister is an interface that an EnvironProvider implements in order to validate and automatically register credentials for clouds supported by the provider.

type ProviderRegistry 

type ProviderRegistry interface {
	// RegisterProvider registers a new environment provider with the given
	// name, and zero or more aliases. If a provider already exists with the
	// given name or alias, an error will be returned.
	RegisterProvider(p EnvironProvider, providerType string, providerTypeAliases ...string) error

	// UnregisterProvider unregisters the environment provider with the given name.
	UnregisterProvider(providerType string)

	// RegisteredProviders returns the names of the registered environment
	// providers.
	RegisteredProviders() []string

	// Provider returns the environment provider with the specified name.
	Provider(providerType string) (EnvironProvider, error)
}

ProviderRegistry is an interface that provides methods for registering and obtaining environment providers by provider name.

func GlobalProviderRegistry 

func GlobalProviderRegistry() ProviderRegistry

GlobalProviderRegistry returns the global provider registry.

type ProviderSchema 

type ProviderSchema interface {
	// Schema returns the schema for the provider. It should
	// include all fields defined in environs/config, conventionally
	// by calling config.Schema.
	Schema() environschema.Fields
}

ProviderSchema can be implemented by a provider to provide access to its configuration schema. Once all providers implement this, it will be included in the EnvironProvider type and the information made available over the API.

type ProviderSpaceInfo 

type ProviderSpaceInfo struct {
	network.SpaceInfo

	// Cloud type governs what attributes will exist in the
	// provider-specific map.
	CloudType string

	// Any provider-specific information to needed to identify the
	// network within the cloud, e.g. VPC ID for EC2.
	ProviderAttributes map[string]interface{}
}

ProviderSpaceInfo contains all the information about a space needed by another environ to decide whether it can be routed to.

type RequestFinalizeCredential 

type RequestFinalizeCredential interface {

	// ShouldFinalizeCredential asks if a EnvironProvider wants to strictly
	// finalize a credential. The provider just returns true if they want to
	// call FinalizeCredential from ProviderCredentials when asked.
	ShouldFinalizeCredential(cloud.Credential) bool
}

RequestFinalizeCredential is an interface that an EnvironProvider implements in order to call ProviderCredentials.FinalizeCredential strictly rather than lazily to gather fully formed credentials.

type ResourceAdopter 

type ResourceAdopter interface {
	// AdoptResources is called when the model is moved from one
	// controller to another using model migration. Some providers tag
	// instances, disks, and cloud storage with the controller UUID to
	// aid in clean destruction. This method will be called on the
	// environ for the target controller so it can update the
	// controller tags for all of those things. For providers that do
	// not track the controller UUID, a simple method returning nil
	// will suffice. The version number of the source controller is
	// provided for backwards compatibility - if the technique used to
	// tag items changes, the version number can be used to decide how
	// to remove the old tags correctly.
	AdoptResources(ctx context.ProviderCallContext, controllerUUID string, fromVersion version.Number) error
}

type StartInstanceParams 

type StartInstanceParams struct {
	// ControllerUUID is the uuid of the controller.
	ControllerUUID string

	// Constraints is a set of constraints on
	// the kind of instance to create.
	Constraints constraints.Value

	// Tools is a list of tools that may be used
	// to start a Juju agent on the machine.
	Tools tools.List

	// InstanceConfig describes the machine's configuration.
	InstanceConfig *instancecfg.InstanceConfig

	// Placement, if non-empty, contains an environment-specific
	// placement directive that may be used to decide how the
	// instance should be started.
	Placement string

	// AvailabilityZone, provides the name of the availability
	// zone required to start the instance.
	AvailabilityZone string

	// RootDisk is a set of parameters for creating the root disk volume.
	RootDisk *storage.VolumeParams

	// Volumes is a set of parameters for volumes that should be created.
	//
	// StartInstance need not check the value of the Attachment field,
	// as it is guaranteed that any volumes in this list are designated
	// for attachment to the instance being started.
	Volumes []storage.VolumeParams

	// VolumeAttachments is a set of parameters for existing volumes that
	// should be attached. If the StartInstance method does not attach the
	// volumes, they will be attached by the storage provisioner once the
	// machine has been created. The attachments are presented here to
	// give the provider an opportunity for the volume attachments to
	// influence the instance creation, e.g. by restricting the machine
	// to specific availability zones.
	VolumeAttachments []storage.VolumeAttachmentParams

	// NetworkInfo is an optional list of network interface details,
	// necessary to configure on the instance.
	NetworkInfo corenetwork.InterfaceInfos

	// SubnetsToZones is an optional collection of maps of provider-specific
	// subnet IDs to a list of availability zone names each subnet is available
	// in.
	// It is populated when valid positive spaces constraints are present,
	// or when the instance to be started will host an application with bound
	// endpoints.
	// The subnets present are derived from the union of
	// constrained/bound spaces.
	// Negative space constraints will have already been validated when
	// retrieving `ProvisioningInfo`.
	SubnetsToZones []map[corenetwork.Id][]string

	// EndpointBindings holds the mapping between application endpoint names to
	// provider-specific space IDs. It is populated when provisioning a machine
	// to host a unit of an application with endpoint bindings.
	EndpointBindings map[string]corenetwork.Id

	// ImageMetadata is a collection of image metadata
	// that may be used to start this instance.
	ImageMetadata []*imagemetadata.ImageMetadata

	// CleanupCallback is a callback to be used to clean up any residual
	// status-reporting output from StatusCallback.
	CleanupCallback func(info string) error

	// StatusCallback is a callback to be used by the instance to report
	// changes in status. Its signature is consistent with other
	// status-related functions to allow them to be used as callbacks.
	StatusCallback StatusCallbackFunc

	// Abort is a channel that will be closed to indicate that the command
	// should be aborted.
	Abort <-chan struct{}

	// CharmLXDProfiles is a slice of names of lxd profiles to be used creating
	// the LXD container, if specified and an LXD container.  The profiles
	// come from charms deployed on the machine.
	CharmLXDProfiles []string
}

StartInstanceParams holds parameters for the InstanceBroker.StartInstance method.

type StartInstanceResult 

type StartInstanceResult struct {
	// DisplayName is an optional human-readable string that's used
	// for display purposes only.
	DisplayName string

	// Instance is an interface representing a cloud instance.
	Instance instances.Instance

	// Config holds the environment config to be used for any further
	// operations, if the instance is for a controller.
	Config *config.Config

	// HardwareCharacteristics represents the hardware characteristics
	// of the newly created instance.
	Hardware *instance.HardwareCharacteristics

	// NetworkInfo contains information about how to configure network
	// interfaces on the instance. Depending on the provider, this
	// might be the same StartInstanceParams.NetworkInfo or may be
	// modified as needed.
	NetworkInfo corenetwork.InterfaceInfos

	// Volumes contains a list of volumes created, each one having the
	// same Name as one of the VolumeParams in StartInstanceParams.Volumes.
	// VolumeAttachment information is reported separately.
	Volumes []storage.Volume

	// VolumeAttachments contains a attachment-specific information about
	// volumes that were attached to the started instance.
	VolumeAttachments []storage.VolumeAttachment
}

StartInstanceResult holds the result of an InstanceBroker.StartInstance method call.

type StatusCallbackFunc 

type StatusCallbackFunc func(settableStatus status.Status, info string, data map[string]interface{}) error

StatusCallbackFunc represents a function that can be called to report a status.

type UpgradeOperation 

type UpgradeOperation struct {
	// TargetVersion is the target environ provider version number to
	// which the upgrade steps pertain. When a model is upgraded, all
	// upgrade operations will be run for versions greater than the
	// recorded environ version. This version number is independent of
	// the agent and controller versions.
	TargetVersion int

	// Steps contains the sequence of upgrade steps to apply when
	// upgrading to the accompanying target version number.
	Steps []UpgradeStep
}

UpgradeOperation contains a target agent version and sequence of upgrade steps to apply to get to that version.

type UpgradeOperationsParams 

type UpgradeOperationsParams struct {
	// ControllerUUID is the UUID of the controller that manages
	// the Environ being upgraded.
	ControllerUUID string
}

UpgradeOperationsParams contains the parameters for Upgrader.UpgradeOperations.

type UpgradeStep 

type UpgradeStep interface {
	// Description is a human readable description of what the upgrade
	// step does.
	Description() string

	// Run executes the upgrade business logic.
	Run(ctx context.ProviderCallContext) error
}

UpgradeStep defines an idempotent operation that is run to perform a specific upgrade step on an Environ.

type Upgrader 

type Upgrader interface {
	// UpgradeOperations returns a list of UpgradeOperations for upgrading
	// an Environ.
	UpgradeOperations(context.ProviderCallContext, UpgradeOperationsParams) []UpgradeOperation
}

Upgrader is an interface that can be used for upgrading Environs. If an Environ implements this interface, its UpgradeOperations method will be invoked to identify operations that should be run on upgrade.

Source Files

View all Source files

Directories

Path Synopsis
Package imagedownloads implements image-downloads metadata from simplestreams.
 Package imagedownloads implements image-downloads metadata from simplestreams.
The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
 The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
testing
instancetest
sshprovisioner
winrmprovisioner
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
 The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
testing
Package testing is a generated GoMock package.
 Package testing is a generated GoMock package.
Package tools supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.
 Package tools supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.
testing

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.