Documentation

Index

Constants

View Source
const (
	UserNamespacePrefix = "user."
	UserDataKey         = UserNamespacePrefix + "user-data"
	NetworkConfigKey    = UserNamespacePrefix + "network-config"
	JujuModelKey        = UserNamespacePrefix + "juju-model"
	AutoStartKey        = "boot.autostart"
)
View Source
const BridgeConfigFile = "/etc/default/lxd-bridge"
View Source
const SnapBridgeConfigFile = "/var/snap/lxd/common/lxd-bridge/config"

Variables

View Source
var CloudImagesDailyRemote = ServerSpec{
	Name:     "cloud-images.ubuntu.com",
	Host:     "https://cloud-images.ubuntu.com/daily",
	Protocol: SimpleStreamsProtocol,
}

CloudImagesDailyRemote hosts images from daily package builds. These images have not been independently tested, but should be sound for use, being build from packages in the released archive.

View Source
var CloudImagesRemote = ServerSpec{
	Name:     "cloud-images.ubuntu.com",
	Host:     "https://cloud-images.ubuntu.com/releases",
	Protocol: SimpleStreamsProtocol,
}

CloudImagesRemote hosts releases blessed by the Canonical team.

View Source
var ConnectImageRemote = connectImageRemote

ConnectImageRemote connects to a remote ImageServer using specified protocol.

Functions

func ConfigureLXDProxies

func ConfigureLXDProxies(proxies proxy.Settings) error

ConfigureLXDProxies will try to set the lxc config core.proxy_http and core.proxy_https configuration values based on the current environment. If LXD is not installed, we skip the configuration.

func ConnectRemote

func ConnectRemote(spec ServerSpec) (lxd.ContainerServer, error)

ConnectRemote connects to LXD on a remote socket.

func DevicesFromInterfaceInfo

func DevicesFromInterfaceInfo(interfaces corenetwork.InterfaceInfos, machineID string) (map[string]device, []string, error)

DevicesFromInterfaceInfo uses the input interface info collection to create a map of network device configuration in the LXD format. Names for any networks without a known CIDR are returned in a slice. The machineID arg is used for generating predictable host interface names for the container's ethernet devices.

func EnsureHTTPS

func EnsureHTTPS(address string) string

EnsureHTTPS takes a URI and ensures that it is a HTTPS URL. LXD Requires HTTPS.

func EnsureHostPort

func EnsureHostPort(address string) (string, error)

EnsureHostPort takes a URI and ensures that it has a port set, if it doesn't then it will ensure that port if added. The address supplied for the Host will be validated when parsed and if the address is not valid, then it will return an error.

func HasSupport

func HasSupport() bool

HasSupport returns true if the current OS supports LXD containers by default

func InterfaceInfoFromDevices

func InterfaceInfoFromDevices(nics map[string]device) (corenetwork.InterfaceInfos, error)

InterfaceInfoFromDevices returns a slice of interface info congruent with the input LXD NIC devices. The output is used to generate cloud-init user-data congruent with the NICs that end up in the container.

func IsLXDNotFound

func IsLXDNotFound(err error) bool

IsLXDNotFound checks if an error from the LXD API indicates that a requested entity was not found.

func NewContainerInitialiser

func NewContainerInitialiser(lxdSnapChannel string) container.Initialiser

NewContainerInitialiser returns an instance used to perform the steps required to allow a host machine to run a LXC container.

func NewContainerManager

func NewContainerManager(cfg container.ManagerConfig, svr *Server) (container.Manager, error)

NewContainerManager creates the entity that knows how to create and manage LXD containers. TODO(jam): This needs to grow support for things like LXC's ImageURLGetter functionality.

func SocketPath

func SocketPath(isSocket func(path string) bool) string

SocketPath returns the path to the local LXD socket. The following are tried in order of preference:

- LXD_DIR environment variable.
- Snap socket.
- Debian socket.

We give preference to LXD installed via Snap. isSocket defaults to socket detection from the LXD shared package. TODO (manadart 2018-04-30) This looks like it can be achieved by using a combination of VarPath and HostPath from lxd.shared, in which case this can be deprecated in their favour.

Types

type Certificate

type Certificate struct {
	// Name is the name that LXD will use for the cert.
	Name string
	// CertPEM is the PEM-encoded x.509 cert.
	CertPEM []byte
	// KeyPEM is the PEM-encoded x.509 private key.
	KeyPEM []byte
}

Certificate holds the information for a single certificate that a client may use to connect to a remote server.

func GenerateClientCertificate

func GenerateClientCertificate() (*Certificate, error)

GenerateClientCertificate creates and returns a new certificate for client communication with an LXD server.

func NewCertificate

func NewCertificate(certPEM, keyPEM []byte) *Certificate

NewCertificate creates a new Certificate for the given cert and key.

func (*Certificate) AsCreateRequest

func (c *Certificate) AsCreateRequest() (api.CertificatesPost, error)

AsCreateRequest creates a payload for the LXD API, suitable for posting the client certificate to an LXD server.

func (*Certificate) Fingerprint

func (c *Certificate) Fingerprint() (string, error)

Fingerprint returns the cert's LXD fingerprint.

func (*Certificate) Validate

func (c *Certificate) Validate() error

Validate ensures that the cert is valid.

func (*Certificate) WriteCertPEM

func (c *Certificate) WriteCertPEM(out io.Writer) error

WriteCertPEM writes the cert's x.509 PEM data to the given writer.

func (*Certificate) WriteKeyPEM

func (c *Certificate) WriteKeyPEM(out io.Writer) error

WriteKeyPEM writes the key's x.509 PEM data to the given writer.

func (*Certificate) X509

func (c *Certificate) X509() (*x509.Certificate, error)

X509 returns the x.509 certificate.

type Container

type Container struct {
	api.Container
}

Container extends the upstream LXD container type.

func (*Container) AddDisk

func (c *Container) AddDisk(name, path, source, pool string, readOnly bool) error

AddDisk modifies updates the container's devices map to represent a disk device described by the input arguments. If the device already exists, an error is returned.

func (*Container) Arch

func (c *Container) Arch() string

Arch returns the architecture of the container.

func (*Container) CPUs

func (c *Container) CPUs() uint

CPUs returns the configured limit for number of container CPU cores. If unset, zero is returned.

func (*Container) Mem

func (c *Container) Mem() uint

Mem returns the configured limit for container memory in MiB.

func (*Container) Metadata

func (c *Container) Metadata(key string) string

Metadata returns the value from container config for the input key. Such values are stored with the "user" namespace prefix.

type ContainerSpec

type ContainerSpec struct {
	Name         string
	Image        SourcedImage
	Devices      map[string]device
	Config       map[string]string
	Profiles     []string
	InstanceType string
}

ContainerSpec represents the data required to create a new container.

func (*ContainerSpec) ApplyConstraints

func (c *ContainerSpec) ApplyConstraints(serverVersion string, cons constraints.Value)

ApplyConstraints applies the input constraints as valid LXD container configuration to the container spec. Note that we pass these through as supplied. If an instance type constraint has been specified along with specific cores/mem constraints, LXD behaviour is to override with the specific ones even when lower.

type Protocol

type Protocol string
const (
	LXDProtocol           Protocol = "lxd"
	SimpleStreamsProtocol Protocol = "simplestreams"
)

type ProxyFunc

type ProxyFunc func(*http.Request) (*url.URL, error)

ProxyFunc defines a function that can act as a proxy for requests

type Server

type Server struct {
	lxd.ContainerServer
	// contains filtered or unexported fields
}

Server extends the upstream LXD container server.

func MaybeNewLocalServer

func MaybeNewLocalServer() (*Server, error)

MaybeNewLocalServer returns a Server based on a local socket connection, if running on an OS supporting LXD containers by default. Otherwise a nil server is returned.

func NewLocalServer

func NewLocalServer() (*Server, error)

NewLocalServer returns a Server based on a local socket connection.

func NewRemoteServer

func NewRemoteServer(spec ServerSpec) (*Server, error)

NewRemoteServer returns a Server based on a remote connection.

func NewServer

func NewServer(svr lxd.ContainerServer) (*Server, error)

NewServer builds and returns a Server for high-level interaction with the input LXD container server.

func (*Server) AliveContainers

func (s *Server) AliveContainers(prefix string) ([]Container, error)

AliveContainers returns the list of containers based on the input namespace prefixed that are in a status indicating they are "alive".

func (*Server) Clock

func (s *Server) Clock() clock.Clock

func (*Server) ClusterSupported

func (s *Server) ClusterSupported() bool

func (*Server) ContainerAddresses

func (s *Server) ContainerAddresses(name string) ([]corenetwork.ProviderAddress, error)

ContainerAddresses gets usable network addresses for the container identified by the input name.

func (*Server) CopyRemoteImage

func (s *Server) CopyRemoteImage(
	sourced SourcedImage, aliases []string, callback environs.StatusCallbackFunc,
) error

CopyRemoteImage accepts an image sourced from a remote server and copies it to the local cache

func (*Server) CreateClientCertificate

func (s *Server) CreateClientCertificate(cert *Certificate) error

CreateClientCertificate adds the input certificate to the server, indicating that is for use in client communication.

func (*Server) CreateContainerFromSpec

func (s *Server) CreateContainerFromSpec(spec ContainerSpec) (*Container, error)

CreateContainerFromSpec creates a new container based on the input spec, and starts it immediately. If the container fails to be started, it is removed. Upon successful creation and start, the container is returned.

func (*Server) CreatePool

func (s *Server) CreatePool(name, driver string, cfg map[string]string) error

func (*Server) CreateProfileWithConfig

func (s *Server) CreateProfileWithConfig(name string, cfg map[string]string) error

CreateProfileWithConfig creates a new profile with the input name and config.

func (*Server) CreateVolume

func (s *Server) CreateVolume(pool, name string, cfg map[string]string) error

func (*Server) EnableHTTPSListener

func (s *Server) EnableHTTPSListener() error

EnableHTTPSListener configures LXD to listen for HTTPS requests, rather than only via a Unix socket. Attempts to listen on all protocols, but falls back to IPv4 only if IPv6 has been disabled with in kernel. Returns an error if updating the server configuration fails.

func (*Server) EnsureDefaultStorage

func (s *Server) EnsureDefaultStorage(profile *api.Profile, eTag string) error

EnsureDefaultStorage ensures that the input profile is configured with a disk device, creating a new storage pool and a device if required.

func (*Server) EnsureIPv4

func (s *Server) EnsureIPv4(netName string) (bool, error)

EnsureIPv4 retrieves the network for the input name and checks its IPv4 configuration. If none is detected, it is set to "auto". The boolean return indicates if modification was necessary.

func (*Server) FilterContainers

func (s *Server) FilterContainers(prefix string, statuses ...string) ([]Container, error)

FilterContainers retrieves the list of containers from the server and filters them based on the input namespace prefix and any supplied statuses.

func (*Server) FindImage

func (s *Server) FindImage(
	series, arch string,
	sources []ServerSpec,
	copyLocal bool,
	callback environs.StatusCallbackFunc,
) (SourcedImage, error)

FindImage searches the input sources in supplied order, looking for an OS image matching the supplied series and architecture. If found, the image and the server from which it was acquired are returned. If the server is remote the image will be cached by LXD when used to create a container. Supplying true for copyLocal will copy the image to the local cache. Copied images will have the juju/series/arch alias added to them. The callback argument is used to report copy progress.

func (*Server) GetContainerProfiles

func (s *Server) GetContainerProfiles(name string) ([]string, error)

GetContainerProfiles returns the list of profiles that are assocated with a container.

func (*Server) GetNICsFromProfile

func (s *Server) GetNICsFromProfile(profileName string) (map[string]device, error)

GetNICsFromProfile returns all NIC devices in the profile with the input name. All returned devices have a MAC address; generated if required.

func (*Server) HasProfile

func (s *Server) HasProfile(name string) (bool, error)

HasProfile interrogates the known profile names and returns a boolean indicating whether a profile with the input name exists.

func (*Server) HostArch

func (s *Server) HostArch() string

HostArch returns the current host architecture

func (*Server) LocalBridgeName

func (s *Server) LocalBridgeName() string

LocalBridgeName returns the name of the local LXD network bridge.

func (*Server) Name

func (s *Server) Name() string

Name returns the name of this LXD server.

func (*Server) RemoveContainer

func (s *Server) RemoveContainer(name string) error

Remove container first ensures that the container is stopped, then deletes it.

func (*Server) RemoveContainers

func (s *Server) RemoveContainers(names []string) error

Remove containers stops and deletes containers matching the input list of names. Any failed removals are indicated in the returned error.

func (*Server) ReplaceOrAddContainerProfile

func (s *Server) ReplaceOrAddContainerProfile(name, oldProfile, newProfile string) error

TODO: HML 2-apr-2019 remove when provisioner_task processProfileChanges() is removed. ReplaceOrAddContainerProfile updates the profiles for the container with the input name, using the input values.

func (*Server) ServerCertificate

func (s *Server) ServerCertificate() string

ServerCertificate returns the current server environment certificate

func (*Server) ServerVersion

func (s *Server) ServerVersion() string

func (*Server) StartContainer

func (s *Server) StartContainer(name string) error

StartContainer starts the extant container identified by the input name.

func (*Server) StorageSupported

func (s *Server) StorageSupported() bool

func (*Server) UpdateContainerConfig

func (s *Server) UpdateContainerConfig(name string, cfg map[string]string) error

UpdateContainerConfig updates the configuration for the container with the input name, using the input values.

func (*Server) UpdateContainerProfiles

func (s *Server) UpdateContainerProfiles(name string, profiles []string) error

UpdateContainerProfiles applies the given profiles (by name) to the named container. It is assumed the profiles have all been added to the server before hand.

func (*Server) UpdateServerConfig

func (s *Server) UpdateServerConfig(cfg map[string]string) error

UpdateServerConfig updates the server configuration with the input values.

func (Server) UseTargetServer

func (s Server) UseTargetServer(name string) (*Server, error)

UseTargetServer returns a new Server based on the input target node name. It is intended for use when operations must target specific nodes in a cluster.

func (*Server) VerifyNetworkDevice

func (s *Server) VerifyNetworkDevice(profile *api.Profile, eTag string) error

VerifyNetworkDevice attempts to ensure that there is a network usable by LXD and that there is a NIC device with said network as its parent. If there are no NIC devices, and this server is *not* in cluster mode, an attempt is made to create an new device in the input profile, with the default LXD bridge as its parent.

func (*Server) WriteContainer

func (s *Server) WriteContainer(c *Container) error

WriteContainer writes the current representation of the input container to the server.

type ServerSpec

type ServerSpec struct {
	Name     string
	Host     string
	Protocol Protocol
	// contains filtered or unexported fields
}

ServerSpec describes the location and connection details for a server utilized in LXD workflows.

func MakeSimpleStreamsServerSpec

func MakeSimpleStreamsServerSpec(name, host string) ServerSpec

MakeSimpleStreamsServerSpec creates a ServerSpec for the SimpleStreams protocol, ensuring that the host is HTTPS

func NewInsecureServerSpec

func NewInsecureServerSpec(host string) ServerSpec

NewInsecureServerSpec creates a ServerSpec without certificate requirements, which also bypasses the TLS verification. It also ensures the HTTPS for the host implicitly

func NewServerSpec

func NewServerSpec(host, serverCert string, clientCert *Certificate) ServerSpec

NewServerSpec creates a ServerSpec with default values where needed. It also ensures the HTTPS for the host implicitly

func (*ServerSpec) Validate

func (s *ServerSpec) Validate() error

Validate ensures that the ServerSpec is valid.

func (ServerSpec) WithClientCertificate

func (s ServerSpec) WithClientCertificate(clientCert *Certificate) ServerSpec

WithClientCertificate adds the optional client Certificate to the server spec. Returns the ServerSpec to enable chaining of optional values

func (ServerSpec) WithProxy

func (s ServerSpec) WithProxy(proxy ProxyFunc) ServerSpec

WithProxy adds the optional proxy to the server spec. Returns the ServerSpec to enable chaining of optional values

func (ServerSpec) WithSkipGetServer

func (s ServerSpec) WithSkipGetServer(b bool) ServerSpec

WithSkipGetServer adds the option skipping of the get server verification to the server spec.

type SnapManager

type SnapManager interface {
	InstalledChannel(string) string
	ChangeChannel(string, string) error
}

SnapManager defines an interface implemented by types that can query and/or change the channel for installed snaps.

type SourcedImage

type SourcedImage struct {
	// Image is the actual image data that was located.
	Image *api.Image
	// LXDServer is the image server that supplied the image.
	LXDServer lxd.ImageServer
}

SourcedImage is the result of a successful image acquisition. It includes the relevant data that located the image.

Directories

Path Synopsis
mocks Package mocks is a generated GoMock package.
testing Package testing is a generated GoMock package.