Documentation

Overview

    Package lxdprofile defines a set of functions and constants that can interact with LXD Profiles. LXD Profiles are key/value YAML configuration files that the LXD provider and LXD container broker can consume and apply to a container.

    More information about a type of LXD configuration profile can found https://github.com/lxc/lxd/blob/master/doc/containers.md

    LXDProfile package defines core concepts that can be utilised from different packages of the codebase, that want to work with a LXD profile. Not all key/value configurations from the underlying LXD can be applied and some key/values need to be applied using `--force`. To validate the LXD Profile before attempting to apply it to a ubuntu LXD container, there are some validation functions.

    Each LXDProfile is given a unique name when applied to the container. This is for three reasons:

    1. readability - when an operator is attempting to debug if a LXD Profile
       has been applied for a given charm revision, it should be straightforward
       for the operator to read the output of `lxd profile list` to marry them.
    2. Collisions - to ensure that no other charm profile can't collide with in
       the LXC namespace for an existing LXD Profile, each profile
       namespaces in the following way `juju-<model>-<application>-<charm-revision>`
    3. Removability - juju needs to clean up LXD profiles that where applied to
       the LXD container, but are subsequently not required any more, either by
       an upgrade of the charm or the complete removal of the charm. Either way,
       the removal of the charms from the LXC profile list is to prevent orphan
       profiles from being left dangling.
    

    Index

    Constants

    View Source
    const (
    	// EmptyStatus represents the initial status
    	EmptyStatus = ""
    
    	// SuccessStatus defines if the lxd profile upgrade was a success
    	SuccessStatus = "Success"
    
    	// NotRequiredStatus defines when the lxd profile upgrade was not required
    	NotRequiredStatus = "Not Required"
    
    	// NotKnownStatus defines a state where the document for the lxd profile
    	// is removed, or never existed, but we don't know what the status should be.
    	NotKnownStatus = "Not known"
    
    	// ErrorStatus defines when the lxd profile is in an error state
    	ErrorStatus = "Error"
    
    	// NotSupportedStatus defines when a machine does not support lxd profiles.
    	NotSupportedStatus = "Not Supported"
    )
    View Source
    const AppName = "juju"

      AppName here is used as the application prefix name. We can't use names.Juju as that changes depending on platform.

      Variables

      View Source
      var Prefix = fmt.Sprintf("%s-", AppName)

        Prefix is used to prefix all the lxd profile programmable profiles. If a profile doesn't have the prefix, then it will be removed when ensuring the the validity of the names (see LXDProfileNames)

        Functions

        func AnnotateErrorStatus

        func AnnotateErrorStatus(err error) string

          AnnotateErrorStatus annotates an existing error with the correct status

          func IsValidName

          func IsValidName(name string) bool

            IsValidName returns if the name of the lxd profile looks valid.

            func LXDProfileNames

            func LXDProfileNames(names []string) []string

              LXDProfileNames ensures that the LXD profile names are unique yet preserve the same order as the input. It removes certain profile names from the list, for example "default" profile name will be removed.

              func MatchProfileNameByAppName

              func MatchProfileNameByAppName(names []string, appName string) (string, error)

                MatchProfileNameByApp returns the first profile which matches the provided appName. No match returns an empty string. Assumes there is not more than one profile for the same application.

                func Name

                func Name(modelName, appName string, revision int) string

                  Name returns a serialisable name that we can use to identify profiles juju-<model>-<application>-<charm-revision>

                  func NotEmpty

                  func NotEmpty(profiler LXDProfiler) bool

                    NotEmpty will return false if the profiler containers a profile, that is empty. If the profile is empty, we'll return false. If there is no valid profile in the profiler, it will return false

                    func ProfileReplaceRevision

                    func ProfileReplaceRevision(profile string, rev int) (string, error)

                      ProfileReplaceRevision replaces the old revision with a new revision in the profile.

                      func ProfileRevision

                      func ProfileRevision(profile string) (int, error)

                        ProfileRevision returns an int which is the charm revision of the given profile name.

                        func UpgradeStatusErrorred

                        func UpgradeStatusErrorred(status string) bool

                          UpgradeStatusErrorred defines if the status is in a error state.

                          func UpgradeStatusFinished

                          func UpgradeStatusFinished(status string) bool

                            UpgradeStatusFinished defines if the upgrade has completed

                            func UpgradeStatusTerminal

                            func UpgradeStatusTerminal(status string) bool

                              UpgradeStatusTerminal defines if the status is in a terminal state. Success or not required is also considered terminal.

                              func ValidateLXDProfile

                              func ValidateLXDProfile(profiler LXDProfiler) error

                                ValidateLXDProfile will validate the profile to determin if the configuration is valid or not before passing continuing on.

                                Types

                                type LXDProfile

                                type LXDProfile interface {
                                
                                	// ValidateConfigDevices validates the Config and Devices properties of the LXDProfile.
                                	// WhiteList devices: unix-char, unix-block, gpu, usb.
                                	// BlackList config: boot*, limits* and migration*.
                                	// An empty profile will not return an error.
                                	ValidateConfigDevices() error
                                
                                	// Empty returns true if there are no configurations or devices to be
                                	// applied for the LXD profile.
                                	// Having a description but having values in the configurations/devices
                                	// will still return empty, as it's what should be applied.
                                	Empty() bool
                                }

                                  LXDProfile represents a local implementation of a charm profile.

                                  type LXDProfiler

                                  type LXDProfiler interface {
                                  	// LXDProfile returns a charm LXDProfile
                                  	LXDProfile() LXDProfile
                                  }

                                    LXDProfiler represents a local implementation of a charm profile. This point of use interface normalises a LXDProfiler, so that we can validate configuration devices in one location, without having to roll your own implementation of what is valid for a LXDProfile. With this in mind shims from your existing types (charm.Charm, state.Charm, params.CharmInfo) will probably require a shim to massage the type into a LXDProfiler. This cleans up the interface for validation and keeps the core cleaner.

                                    type LXDProfiles

                                    type LXDProfiles struct {
                                    	Profile Profile
                                    }

                                    func (LXDProfiles) LXDProfile

                                    func (p LXDProfiles) LXDProfile() LXDProfile

                                      Implements LXDProfiler interface.

                                      type Profile

                                      type Profile struct {
                                      	Config      map[string]string
                                      	Description string
                                      	Devices     map[string]map[string]string
                                      }

                                        Profile is a representation of charm.v6 LXDProfile

                                        func (Profile) Empty

                                        func (p Profile) Empty() bool

                                          Implements LXDProfile interface.

                                          func (Profile) ValidateConfigDevices

                                          func (p Profile) ValidateConfigDevices() error

                                            Implements LXDProfile interface.

                                            type ProfilePost

                                            type ProfilePost struct {
                                            	Name    string
                                            	Profile *Profile
                                            }

                                              ProfilePost is a close representation of lxd api ProfilesPost

                                              Directories

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