Documentation

Overview

    The upgrades package provides infrastructure to upgrade previous Juju deployments to the current Juju version. The upgrade is performed on a per node basis, across all of the running Juju machines.

    Important exported APIs include:

    PerformUpgrade, which is invoked on each node by the machine agent with:
      fromVersion - the Juju version from which the upgrade is occurring
      target      - the type of Juju node being upgraded
      context     - provides API access to Juju controllers
    

    Index

    Constants

    View Source
    const (
    	// AllMachines applies to any machine.
    	AllMachines = Target("allMachines")
    
    	// HostMachine is a machine on which units are deployed.
    	HostMachine = Target("hostMachine")
    
    	// Controller is a machine participating in a Juju controller cluster.
    	Controller = Target("controller")
    
    	// DatabaseMaster is a Controller that has the master database, and as such
    	// is the only target that should run database schema upgrade steps.
    	DatabaseMaster = Target("databaseMaster")
    )

    Variables

    View Source
    var MinDiskSpaceMib = uint64(250)

      MinDiskSpaceMib is the standard amount of disk space free (in MiB) we'll require before downloading a binary or starting an upgrade.

      View Source
      var MinMajorUpgradeVersion = map[int]version.Number{
      	3: version.MustParse(MinMajorUpgradeVersionValue[3]),
      }

        MinMajorUpgradeVersion defines the minimum version all models must be running before a major version upgrade.

        View Source
        var MinMajorUpgradeVersionValue = map[int]string{
        	3: "2.8.9",
        }

          MinMajorUpgradeVersionValue defines the value to identify what the last version should be.

          Functions

          func AddRemoteApplicationToHook

          func AddRemoteApplicationToHook(path string) error

            AddRemoteApplicationToHook takes a the path to a uniter state file that doesn't validate, and sets hook.remote-application to the remote application so that it does. (If it doesn't validate for some other reason we won't change the file.)

            func AddRemoteApplicationToRunningHooks

            func AddRemoteApplicationToRunningHooks(pattern string) func(Context) error

              AddRemoteApplicationToRunningHooks finds any uniter state files on the machine with running hooks, and makes sure that they contain a remote-application key.

              func BootstrapRaft

              func BootstrapRaft(context Context) error

                BootstrapRaft initialises the raft cluster in a controller that is being upgraded.

                func CheckFreeDiskSpace

                func CheckFreeDiskSpace(dir string, thresholdMib uint64) error

                  CheckFreeDiskSpace returns a helpful error if there isn't at least thresholdMib MiB of free space available on the volume containing dir.

                  func MigrateLegacyLeases

                  func MigrateLegacyLeases(context Context) error

                    MigrateLegacyLeases converts leases in the legacy store into corresponding ones in the raft store.

                    func PerformStateUpgrade

                    func PerformStateUpgrade(from version.Number, targets []Target, context Context) error

                      PerformStateUpgrade runs the upgrades steps that target Controller or DatabaseMaster.

                      func PerformUpgrade

                      func PerformUpgrade(from version.Number, targets []Target, context Context) error

                        PerformUpgrade runs the business logic needed to upgrade the current "from" version to this version of Juju on the "target" type of machine.

                        func PreUpgradeSteps

                        func PreUpgradeSteps(_ *state.StatePool, agentConf agent.Config, isController, isMaster, isCaas bool) error

                          PreUpgradeSteps runs various checks and prepares for performing an upgrade. If any check fails, an error is returned which aborts the upgrade.

                          func UpgradeAllowed

                          func UpgradeAllowed(from, to version.Number) (bool, version.Number, error)

                            UpgradeAllowed returns true if a major version upgrade is allowed for the specified from and to versions.

                            func WriteServiceFiles

                            func WriteServiceFiles(s service.SystemdServiceManager) error

                              WriteServiceFiles writes service files to the standard /etc/systemd/system path. This implementation is moved here to allow the upgrade from very early 2.x to 2.9.

                              Types

                              type Context

                              type Context interface {
                              	// APIState returns an base APICaller to help make
                              	// an API connection to state.
                              	APIState() base.APICaller
                              
                              	// State returns a connection to state. This will be non-nil
                              	// only in the context of a controller.
                              	State() StateBackend
                              
                              	// AgentConfig returns the agent config for the machine that is being
                              	// upgraded.
                              	AgentConfig() agent.ConfigSetter
                              
                              	// StateContext returns a new Context suitable for State-based
                              	// upgrade steps.
                              	StateContext() Context
                              
                              	// APIContext returns a new Context suitable for API-based upgrade
                              	// steps.
                              	APIContext() Context
                              }

                                Context provides the dependencies used when executing upgrade steps.

                                func NewContext

                                func NewContext(
                                	agentConfig agent.ConfigSetter,
                                	api api.Connection,
                                	st StateBackend,
                                ) Context

                                  NewContext returns a new upgrade context.

                                  type Model

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

                                    Model is an interface providing access to the details of a model within the controller.

                                    type Operation

                                    type Operation interface {
                                    	// The Juju version for which this operation is applicable.
                                    	// Upgrade operations designed for versions of Juju earlier
                                    	// than we are upgrading from are not run since such steps would
                                    	// already have been used to get to the version we are running now.
                                    	TargetVersion() version.Number
                                    
                                    	// Steps to perform during an upgrade.
                                    	Steps() []Step
                                    }

                                      Operation defines what steps to perform to upgrade to a target version.

                                      type OperationSource

                                      type OperationSource interface {
                                      	// UpgradeOperations returns Operations to run during upgrade.
                                      	UpgradeOperations() []Operation
                                      }

                                        OperationSource provides a means of obtaining upgrade operations.

                                        type PreUpgradeStepsFunc

                                        type PreUpgradeStepsFunc func(_ *state.StatePool, _ agent.Config, isController, isMaster, isCaas bool) error

                                          PreUpgradeStepsFunc is the function type of PreUpgradeSteps. This may be used to provide an alternative to PreUpgradeSteps to the upgrade steps worker.

                                          type StateBackend

                                          type StateBackend interface {
                                          	ControllerUUID() string
                                          	StateServingInfo() (controller.StateServingInfo, error)
                                          	ControllerConfig() (controller.Config, error)
                                          	LeaseNotifyTarget(io.Writer, raftleasestore.Logger) raftlease.NotifyTarget
                                          
                                          	StripLocalUserDomain() error
                                          	RenameAddModelPermission() error
                                          	AddMigrationAttempt() error
                                          	AddLocalCharmSequences() error
                                          	UpdateLegacyLXDCloudCredentials(string, cloud.Credential) error
                                          	UpgradeNoProxyDefaults() error
                                          	AddNonDetachableStorageMachineId() error
                                          	RemoveNilValueApplicationSettings() error
                                          	AddControllerLogCollectionsSizeSettings() error
                                          	AddStatusHistoryPruneSettings() error
                                          	AddActionPruneSettings() error
                                          	AddStorageInstanceConstraints() error
                                          	SplitLogCollections() error
                                          	AddUpdateStatusHookSettings() error
                                          	CorrectRelationUnitCounts() error
                                          	AddModelEnvironVersion() error
                                          	AddModelType() error
                                          	MigrateLeasesToGlobalTime() error
                                          	MoveOldAuditLog() error
                                          	AddRelationStatus() error
                                          	DeleteCloudImageMetadata() error
                                          	EnsureContainerImageStreamDefault() error
                                          	RemoveContainerImageStreamFromNonModelSettings() error
                                          	MoveMongoSpaceToHASpaceConfig() error
                                          	CreateMissingApplicationConfig() error
                                          	RemoveVotingMachineIds() error
                                          	AddCloudModelCounts() error
                                          	ReplicaSetMembers() ([]replicaset.Member, error)
                                          	MigrateStorageMachineIdFields() error
                                          	MigrateAddModelPermissions() error
                                          	LegacyLeases(time.Time) (map[lease.Key]lease.Info, error)
                                          	SetEnableDiskUUIDOnVsphere() error
                                          	UpdateInheritedControllerConfig() error
                                          	UpdateKubernetesStorageConfig() error
                                          	EnsureDefaultModificationStatus() error
                                          	EnsureApplicationDeviceConstraints() error
                                          	RemoveInstanceCharmProfileDataCollection() error
                                          	UpdateK8sModelNameIndex() error
                                          	AddModelLogsSize() error
                                          	AddControllerNodeDocs() error
                                          	AddSpaceIdToSpaceDocs() error
                                          	ChangeSubnetAZtoSlice() error
                                          	ChangeSubnetSpaceNameToSpaceID() error
                                          	AddSubnetIdToSubnetDocs() error
                                          	ReplacePortsDocSubnetIDCIDR() error
                                          	EnsureRelationApplicationSettings() error
                                          	ConvertAddressSpaceIDs() error
                                          	ReplaceSpaceNameWithIDEndpointBindings() error
                                          	EnsureDefaultSpaceSetting() error
                                          	RemoveControllerConfigMaxLogAgeAndSize() error
                                          	IncrementTasksSequence() error
                                          	AddMachineIDToSubordinates() error
                                          	AddOriginToIPAddresses() error
                                          	DropPresenceDatabase() error
                                          	DropLeasesCollection() error
                                          	RemoveUnsupportedLinkLayer() error
                                          	AddBakeryConfig() error
                                          	ReplaceNeverSetWithUnset() error
                                          	ResetDefaultRelationLimitInCharmMetadata() error
                                          	RollUpAndConvertOpenedPortDocuments() error
                                          	AddCharmHubToModelConfig() error
                                          	AddCharmOriginToApplications() error
                                          	ExposeWildcardEndpointForExposedApplications() error
                                          	RemoveLinkLayerDevicesRefsCollection() error
                                          	RemoveUnusedLinkLayerDeviceProviderIDs() error
                                          	TranslateK8sServiceTypes() error
                                          	UpdateKubernetesCloudCredentials() error
                                          }

                                            StateBackend provides an interface for upgrading the global state database.

                                            func NewStateBackend

                                            func NewStateBackend(pool *state.StatePool) StateBackend

                                              NewStateBackend returns a new StateBackend using a *state.StatePool object.

                                              type Step

                                              type Step interface {
                                              	// Description is a human readable description of what the upgrade step does.
                                              	Description() string
                                              
                                              	// Targets returns the target machine types for which the upgrade step is applicable.
                                              	Targets() []Target
                                              
                                              	// Run executes the upgrade business logic.
                                              	Run(Context) error
                                              }

                                                Step defines an idempotent operation that is run to perform a specific upgrade step.

                                                type Target

                                                type Target string

                                                  Target defines the type of machine for which a particular upgrade step can be run.

                                                  type UpgradeStepsClient

                                                  type UpgradeStepsClient interface {
                                                  	WriteAgentState([]params.SetUnitStateArg) error
                                                  }

                                                  Directories

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