upgrades

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
• Variables
• func AddRemoteApplicationToHook(path string) error
• func AddRemoteApplicationToRunningHooks(pattern string) func(Context) error
• func BootstrapRaft(context Context) error
• func CheckFreeDiskSpace(dir string, thresholdMib uint64) error
• func MigrateLegacyLeases(context Context) error
• func PerformStateUpgrade(from version.Number, targets []Target, context Context) error
• func PerformUpgrade(from version.Number, targets []Target, context Context) error
• func PreUpgradeSteps(_ *state.StatePool, agentConf agent.Config, isController, isCaas bool) error
• func UpgradeAllowed(from, to version.Number) (bool, version.Number, error)
• func WriteServiceFiles(s service.SystemdServiceManager) error
• type Context
  • func NewContext(agentConfig agent.ConfigSetter, api api.Connection, st StateBackend) Context
• type Model
• type Operation
• type OperationSource
• type PreUpgradeStepsFunc
• type StateBackend
  • func NewStateBackend(pool *state.StatePool) StateBackend
• type Step
• type Target
• type UpgradeStepsClient

Constants

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

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.

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.

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, 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 {
	// TargetVersion is 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, 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(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
	UpdateDHCPAddressConfigs() error
	KubernetesInClusterCredentialSpec() (environscloudspec.CloudSpec, *config.Config, string, error)
	AddSpawnedTaskCountToOperations() error
	TransformEmptyManifestsToNil() error
	EnsureCharmOriginRisk() error
	RemoveOrphanedCrossModelProxies() error
	DropLegacyAssumesSectionsFromCharmMetadata() error
	MigrateLegacyCrossModelTokens() error
	CleanupDeadAssignUnits() error
	RemoveOrphanedLinkLayerDevices() 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
}