service

package
v0.0.0-...-d7ebd26 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2026 License: AGPL-3.0 Imports: 22 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentBinaryFinder 

type AgentBinaryFinder interface {
	// HasBinariesForVersion will interrogate agent binaries available in the
	// system and return true or false if agent binaries exist for the provided
	// version.
	HasBinariesForVersion(semversion.Number) (bool, error)
}

AgentBinaryFinder defines a helper for asserting if agent binaries are available for provided agent version.

func DefaultAgentBinaryFinder 

func DefaultAgentBinaryFinder() AgentBinaryFinder

DefaultAgentBinaryFinder provides a default implementation of AgentBinaryFinder to construct a Service with. This implementation currently does not check if agent binaries exist and always returns true.

There will be future work to wire up this support.

type ControllerState 

type ControllerState interface {
	// GetControllerAgentVersions has the responsibility of
	// getting the agent versions of all the controllers.
	GetControllerAgentVersions(context.Context) ([]semversion.Number, error)

	// GetAllMachineTargetAgentVersionByArches returns all the given machine
	// architectures for a given agent version that have an associated agent binary
	// in the agent binary store.
	GetAllMachineTargetAgentVersionByArches(
		ctx context.Context,
		version string,
	) ([]string, error)
}

ControllerState defines the interface for interacting with the underlying model that hosts the current controller(s).

type ModelState 

type ModelState interface {
	// GetMachineAgentBinaryMetadata reports the agent binary metadata that is
	// currently running a given machine.
	GetMachineAgentBinaryMetadata(ctx context.Context, machineName string) (agentbinary.Metadata, error)

	// GetMachinesAgentBinaryMetadata reports the agent binary metadata that
	// each machine in the model is currently running. This is a bulk call to
	// support operations such as model export where it is expected that the
	// state of a model stays relatively static over the operation. This
	// function will never provide enough granularity into what machine fails as
	// part of the checks.
	GetMachinesAgentBinaryMetadata(context.Context) (map[machine.Name]agentbinary.Metadata, error)

	// GetMachinesNotAtTargetAgentVersion returns the list of machines where
	// their agent version is not the same as the model's target agent version
	// or who have no agent version reproted at all. If no machines exist that
	// match this criteria an empty slice is returned.
	GetMachinesNotAtTargetAgentVersion(context.Context) ([]machine.Name, error)

	// GetMachineRunningAgentBinaryVersion returns the running machine agent
	// binary version for the given machine uuid.
	GetMachineRunningAgentBinaryVersion(context.Context, string) (agentbinary.Version, error)

	// GetMachineTargetAgentVersion returns the target agent version for the
	// specified machine.
	GetMachineTargetAgentVersion(context.Context, string) (agentbinary.Version, error)

	// GetMachineUUIDByName returns the UUID of a machine identified by its
	// name. If no machine exists for this name an error satisfying
	// [machineerroros.MachineNotFound] is returned.
	GetMachineUUIDByName(context.Context, machine.Name) (string, error)

	// GetModelTargetAgentVersion returns the target agent version for this
	// model.
	GetModelTargetAgentVersion(context.Context) (semversion.Number, error)

	// GetUnitsAgentBinaryMetadata reports the agent binary metadata that each
	// unit in the model is currently running. This is a bulk call to support
	// operations such as model export where it is expected that the state of a
	// model stays relatively static over the operation. This function will
	// never provide enough granularity into what unit fails as part of the
	// checks.
	GetUnitsAgentBinaryMetadata(context.Context) (map[coreunit.Name]agentbinary.Metadata, error)

	// GetUnitsNotAtTargetAgentVersion returns the list of units where their
	// agent version is not the same as the models target agent version or who
	// have no agent version reported at all. If no units exist that match the
	// criteria an empty slice is returned.
	GetUnitsNotAtTargetAgentVersion(context.Context) ([]coreunit.Name, error)

	// GetUnitRunningAgentBinaryVersion returns the running unit agent binary
	// version for the given unit uuid.
	GetUnitRunningAgentBinaryVersion(context.Context, coreunit.UUID) (agentbinary.Version, error)

	// GetUnitTargetAgentVersion returns the target agent version for the
	// specified unit.
	GetUnitTargetAgentVersion(context.Context, coreunit.UUID) (agentbinary.Version, error)

	// GetUnitUUIDByName returns the UUID for the named unit, returning an
	// error satisfying [applicationerrors.UnitNotFound] if the unit doesn't
	// exist.
	GetUnitUUIDByName(context.Context, coreunit.Name) (coreunit.UUID, error)

	// IsControllerModel indicates if this model is running the Juju controller
	// that owns this model. True is returned when this is the case.
	IsControllerModel(context.Context) (bool, error)

	// NamespaceForWatchAgentVersion returns the namespace identifier
	// to watch for the agent version.
	NamespaceForWatchAgentVersion() string

	// SetMachineRunningAgentBinaryVersion sets the running agent version for
	// the machine.
	SetMachineRunningAgentBinaryVersion(context.Context, string, agentbinary.Version) error

	// SetModelAgentStream is responsible for setting the agent stream that is
	// in use by the current model.
	SetModelAgentStream(context.Context, domainagentbinary.Stream) error

	// SetModelTargetAgentVersion is responsible for setting the current target
	// agent version of the model. This function expects a precondition version
	// to be supplied. The model's target version at the time the operation is
	// applied must match the preCondition version or else an error is returned.
	SetModelTargetAgentVersion(
		ctx context.Context,
		preCondition semversion.Number,
		toVersion semversion.Number,
	) error

	// SetModelTargetAgentVersionAndStream is responsible for setting the
	// current target agent version of the model and the agent stream that is
	// used. This function expects a precondition version to be supplied. The
	// model's target version at the time the operation is applied must match
	// the preCondition version or else an error is returned.
	SetModelTargetAgentVersionAndStream(
		ctx context.Context,
		preCondition semversion.Number,
		toVersion semversion.Number,
		stream domainagentbinary.Stream,
	) error

	// UpdateLatestAgentVersion persists the latest available agent version.
	UpdateLatestAgentVersion(context.Context, semversion.Number) error

	// SetUnitRunningAgentBinaryVersion sets the running agent version for the
	// unit.
	SetUnitRunningAgentBinaryVersion(context.Context, coreunit.UUID, agentbinary.Version) error

	// GetAllMachinesWithBase returns a map of
	// machine UUIDs to their resolved platform base.
	GetAllMachinesWithBase(ctx context.Context) (map[string]corebase.Base, error)

	// GetAllMachinesArchitectures returns a map of all machine architectures in
	// the model.
	GetAllMachinesArchitectures(ctx context.Context) ([]string, error)

	// GetAllMachineTargetAgentVersionByArches returns all the given machine
	// architectures for a given agent version that have an associated agent binary
	// in the agent binary store.
	GetAllMachineTargetAgentVersionByArches(
		ctx context.Context,
		version string,
	) ([]string, error)
}

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service is used to interact with the agent binary version of a model and its entities.

func NewService 

func NewService(
	agentBinaryFinder AgentBinaryFinder,
	modelSt ModelState,
	controllerSt ControllerState,
) *Service

NewService returns a new Service.

func (*Service) GetMachineAgentBinaryMetadata 

func (s *Service) GetMachineAgentBinaryMetadata(ctx context.Context, machineName machine.Name) (agentbinary.Metadata, error)

GetMachineAgentBinaryMetadata reports the agent binary metadata that is currently running a given machine.

The following errors can be expected: - machineerrors.MachineNotFound when the machine being asked for does not exist. - modelagenterrors.MissingAgentBinaries when the agent binaries don't exist for one or more machines in the model.

func (*Service) GetMachineReportedAgentVersion 

func (s *Service) GetMachineReportedAgentVersion(
	ctx context.Context,
	machineName machine.Name,
) (agentbinary.Version, error)

GetMachineReportedAgentVersion returns the agent binary version that was last reported to be running by the agent on the machine. The following errors are possible: - machineerrors.MachineNotFound when the machine being asked for does not exist. - github.com/juju/juju/domain/modelagent/errors.AgentVersionNotFound when no agent version has been reported for the given machine.

func (*Service) GetMachineTargetAgentVersion 

func (s *Service) GetMachineTargetAgentVersion(
	ctx context.Context,
	machineName machine.Name,
) (agentbinary.Version, error)

GetMachineTargetAgentVersion reports the target agent version that should be running on the provided machine identified by name. The following errors are possible: - machineerrors.MachineNotFound - github.com/juju/juju/domain/modelagent/errors.AgentVersionNotFound

func (*Service) GetMachinesAgentBinaryMetadata 

func (s *Service) GetMachinesAgentBinaryMetadata(
	ctx context.Context,
) (map[machine.Name]agentbinary.Metadata, error)

GetMachinesAgentBinaryMetadata returns the agent binary metadata that is running for each machine in the model. This call expects that every machine in the model has their agent binary version set and there exist agent binaries available for each machine and the version that it is running.

This is a bulk call to support operations such as model export where it will never provide enough granuality into what machine fails as part of the checks.

The following error types can be expected: - modelagenterrors.AgentVersionNotSet when one or more machines in the model do not have their agent binary version set. - modelagenterrors.MissingAgentBinaries when the agent binaries don't exist for one or more machines in the model.

func (*Service) GetMachinesNotAtTargetAgentVersion 

func (s *Service) GetMachinesNotAtTargetAgentVersion(
	ctx context.Context,
) ([]machine.Name, error)

GetMachinesNotAtTargetAgentVersion reports all of the machines in the model that are currently not at the desired target version. This also returns machines that have no reported agent version set. If all units are up to the target version or no uints exist in the model a zero length slice is returned.

func (*Service) GetMissingAgentTargetVersions 

func (s *Service) GetMissingAgentTargetVersions(ctx context.Context) (semversion.Number, []arch.Arch, error)

GetMissingAgentTargetVersions returns missing architectures for the target agent version.

func (*Service) GetModelTargetAgentVersion 

func (s *Service) GetModelTargetAgentVersion(ctx context.Context) (semversion.Number, error)

GetModelTargetAgentVersion returns the agent version for the specified model. The following errors can be returned: - github.com/juju/juju/domain/modelagent/errors.AgentVersionFound if no agent version record exists.

func (*Service) GetUnitReportedAgentVersion 

func (s *Service) GetUnitReportedAgentVersion(
	ctx context.Context,
	unitName coreunit.Name,
) (agentbinary.Version, error)

GetUnitReportedAgentVersion returns the agent binary version that was last reported to be running by the agent on the unit. The following errors are possible: - applicationerrors.UnitNotFound when the unit in question does not exist. - github.com/juju/juju/domain/model/errors.AgentVersionNotFound when no agent version has been reported for the given machine.

func (*Service) GetUnitTargetAgentVersion 

func (s *Service) GetUnitTargetAgentVersion(
	ctx context.Context,
	unitName coreunit.Name,
) (agentbinary.Version, error)

GetUnitTargetAgentVersion reports the target agent version that should be being run on the provided unit identified by name. The following errors are possible: - applicationerrors.UnitNotFound When the unit in question does not exist. - github.com/juju/juju/domain/modelagent/errors.AgentVersionFound if no agent version record exists.

func (*Service) GetUnitsAgentBinaryMetadata 

func (s *Service) GetUnitsAgentBinaryMetadata(
	ctx context.Context,
) (map[coreunit.Name]agentbinary.Metadata, error)

GetUnitsAgentBinaryMetadata returns the agent binary metadata that is running for each unit in the model. This call expects that every unit in the model has their agent binary version set and there exist agent binaries available for each unit and the version that it is running.

This is a bulk call to support operations such as model export where it will never provide enough granularity into what unit fails as part of the checks.

The following error types can be expected: - modelagenterrors.AgentVersionNotSet when one or more units in the model do not have their agent binary version set. - modelagenterrors.MissingAgentBinaries when the agent binaries don't exist for one or more units in the model.

func (*Service) GetUnitsNotAtTargetAgentVersion 

func (s *Service) GetUnitsNotAtTargetAgentVersion(
	ctx context.Context,
) ([]coreunit.Name, error)

GetUnitsNotAtTargetAgentVersion reports all of the units in the model that are currently not at the desired target agent version. This also returns units that have no reported agent version set. If all units are up to the target version or no units exist in the model a zero length slice is returned.

func (*Service) RunPreUpgradeChecks 

func (s *Service) RunPreUpgradeChecks(
	ctx context.Context,
) (semversion.Number, error)

RunPreUpgradeChecks performs a series of pre-upgrade validation checks to ensure that the model can be safely upgraded to the controller’s currently recommended version.

This method determines the recommended version from the controller, then calls Service.RunPreUpgradeChecksToVersion to validate that the model can be upgraded to that version.

The following errors may be returned:

Returns the controller’s recommended version if all checks pass.

func (*Service) RunPreUpgradeChecksToVersion 

func (s *Service) RunPreUpgradeChecksToVersion(
	ctx context.Context,
	desiredTargetVersion semversion.Number,
) (semversion.Number, error)

RunPreUpgradeChecksToVersion performs pre-upgrade validation checks to ensure that the model can be safely upgraded to a specific desired target agent version.

This function compares the current model’s target version with the desired target version, validates upgrade compatibility and supported ranges, ensures required binaries exist, and checks that the model itself is eligible for upgrade.

The following errors may be returned:

Returns the current model target version if validation passes.

func (*Service) RunPreUpgradeChecksToVersionWithStream 

func (s *Service) RunPreUpgradeChecksToVersionWithStream(
	ctx context.Context,
	desiredTargetVersion semversion.Number,
	stream domainagentbinary.Stream,
) (semversion.Number, error)

RunPreUpgradeChecksToVersionWithStream performs pre-upgrade validation checks for a specific desired target agent version within a given domainagentbinary.Stream.

This function validates the supplied agent stream, retrieves the model’s current target agent version, and checks that upgrading to the desired target version is supported, safe, and possible.

The following errors may be returned:

Returns the current model target version if validation succeeds.

func (*Service) RunPreUpgradeChecksWithStream 

func (s *Service) RunPreUpgradeChecksWithStream(
	ctx context.Context,
	stream domainagentbinary.Stream,
) (semversion.Number, error)

RunPreUpgradeChecksWithStream performs pre-upgrade validation checks similar to Service.RunPreUpgradeChecks, but additionally validates against a specific domainagentbinary.Stream.

It ensures that the provided agent stream is valid, retrieves the controller’s recommended version, and verifies that the model can be upgraded to that version using Service.RunPreUpgradeChecksToVersionWithStream.

The following errors may be returned:

Returns the controller’s recommended version if all checks pass.

func (*Service) SetMachineReportedAgentVersion 

func (s *Service) SetMachineReportedAgentVersion(
	ctx context.Context,
	machineName machine.Name,
	reportedVersion agentbinary.Version,
) error

SetMachineReportedAgentVersion sets the reported agent version for the supplied machine name. Reported agent version is the version that the agent binary on this machine has reported it is running.

The following errors are possible: - github.com/juju/juju/core/errors.NotValid if the reportedVersion is not valid or the machine name is not valid. - github.com/juju/juju/core/errors.NotSupported if the architecture is not supported. - machineerrors.MachineNotFound when the machine does not exist. - machineerrors.MachineDead when the machine is dead.

func (*Service) SetModelAgentStream 

func (s *Service) SetModelAgentStream(
	ctx context.Context,
	agentStream domainagentbinary.Stream,
) error

SetModelAgentStream is responsible for setting the agent stream that is in use for the current model. If the agent stream supplied is not a recognised value an error satisfying coreerrors.NotValid is returned.

func (*Service) SetUnitReportedAgentVersion 

func (s *Service) SetUnitReportedAgentVersion(
	ctx context.Context,
	unitName coreunit.Name,
	reportedVersion agentbinary.Version,
) error

SetUnitReportedAgentVersion sets the reported agent version for the supplied unit name. Reported agent version is the version that the agent binary on this unit has reported it is running.

The following errors are possible: - github.com/juju/juju/core/errors.NotValid if the reportedVersion is not valid or the machine name is not valid. - github.com/juju/juju/core/errors.NotSupported if the architecture is not supported. - applicationerrors.UnitNotFound - when the unit does not exist. - applicationerrors.UnitIsDead - when the unit is dead.

func (*Service) UpdateLatestAgentVersion 

func (s *Service) UpdateLatestAgentVersion(ctx context.Context, version semversion.Number) error

UpdateLatestAgentVersion persists the latest available agent version.

func (*Service) UpgradeModelAgentToTargetVersion 

func (s *Service) UpgradeModelAgentToTargetVersion(
	ctx context.Context,
	desiredTargetVersion semversion.Number,
) error

UpgradeModelAgentToTargetVersion upgrades a model to a new target agent version. All agents that run on behalf of entities within the model will be eventually upgraded to the new version after this call successfully returns.

The version supplied must not be a downgrade from the current target agent version of the model. It must also not be greater than the maximum supported version of the controller.

The following errors may be expected: - modelagenterrors.DowngradeNotSupported when the caller is attempting to change the model target agent version to one that is lower than the current version. - modelagenterrors.AgentVersionNotSupported when the caller is attempting to upgrade the version to one that is greater than the maximum supported version of the controller hosting the model. - modelagenterrors.MissingAgentBinaries when agent binaries do not exist for the desired version. The model cannot be upgraded to a version where no agent binaries exist. - modelagenterrors.CannotUpgradeControllerModel when the current model is the model running the Juju controller. - modelagenterrors.ModelUpgradeBlocker when their exists a blocker in the model that prevents the model from being upgraded.

func (*Service) UpgradeModelTargetAgentVersion 

func (s *Service) UpgradeModelTargetAgentVersion(
	ctx context.Context,
) (semversion.Number, error)

UpgradeModelTargetAgentVersion is responsible for upgrading the target agent version of the current model to latest version available. The version that is upgraded to is returned.

All agents that run on behalf of entities within the model will be entities within the model will be eventually upgraded to the new version after this call successfully returns.

The following errors may be expected: - modelagenterrors.CannotUpgradeControllerModel when the current model is the model running the Juju controller. - modelagenterrors.ModelUpgradeBlocker when there exists a blocker in the model that prevents the model from being upgraded.

func (*Service) UpgradeModelTargetAgentVersionStreamTo 

func (s *Service) UpgradeModelTargetAgentVersionStreamTo(
	ctx context.Context,
	desiredTargetVersion semversion.Number,
	agentStream domainagentbinary.Stream,
) error

UpgradeModelTargetAgentVersionStreamTo upgrades a model to a new target agent version and updates the agent stream that is in use. All agents that run on behalf of entities within the model will be eventually upgraded to the new version after this call successfully returns.

The version supplied must not be a downgrade from the current target agent version of the model. It must also not be greater than the maximum supported version of the controller.

The following errors may be expected: - coreerrors.NotValid when the agent stream is not valid. - modelagenterrors.DowngradeNotSupported when the caller is attempting to change the model target agent version to one that is lower than the current version. - modelagenterrors.AgentVersionNotSupported when the caller is attempting to upgrade the version to one that is greater than the maximum supported version of the controller hosting the model. - modelagenterrors.MissingAgentBinaries when agent binaries do not exist for the desired version. The model cannot be upgraded to a version where no agent binaries exist. - modelagenterrors.CannotUpgradeControllerModel when the current model is the model running the Juju controller. - modelagenterrors.ModelUpgradeBlocker when their exists a blocker in the model that prevents the model from being upgraded.

func (*Service) UpgradeModelTargetAgentVersionWithStream 

func (s *Service) UpgradeModelTargetAgentVersionWithStream(
	ctx context.Context,
	agentStream domainagentbinary.Stream,
) (semversion.Number, error)

UpgradeModelTargetAgentVersionWithStream is responsible for upgrading the target agent version of the current model to the latest version available. While performing the upgrade the agent stream for the model will also be changed. The version that is upgraded to is returned.

All agents that run on behalf of entities within the model will be entities within the model will be eventually upgraded to the new version after this call successfully returns.

The following errors may be expected: - coreerrors.NotValid when the agent stream is not valid. - modelagenterrors.CannotUpgradeControllerModel when the current model is the model running the Juju controller. - modelagenterrors.ModelUpgradeBlocker when their exists a blocker in the model that prevents the model from being upgraded.

type WatchableService 

type WatchableService struct {
	// Service is the composed Service that is being extended with watching
	// capabilities.
	Service
	// contains filtered or unexported fields
}

WatchableService extends Service to provide further interactions with state to watch for agent version changes within the model.

func NewWatchableService 

func NewWatchableService(
	agentBinaryFinder AgentBinaryFinder,
	modelSt ModelState,
	controllerSt ControllerState,
	watcherFactory WatcherFactory,
) *WatchableService

NewWatchableService returns a new WatchableService.

func (*WatchableService) WatchMachineTargetAgentVersion 

func (s *WatchableService) WatchMachineTargetAgentVersion(
	ctx context.Context,
	machineName machine.Name,
) (watcher.NotifyWatcher, error)

WatchMachineTargetAgentVersion is responsible for watching the target agent version for machine and reporting when there has been a change via a watcher.NotifyWatcher. The following errors can be expected: - machineerrors.NotFound when no machine exists for the provided name.

func (*WatchableService) WatchModelTargetAgentVersion 

func (s *WatchableService) WatchModelTargetAgentVersion(ctx context.Context) (watcher.NotifyWatcher, error)

WatchModelTargetAgentVersion is responsible for watching the target agent version of this model and reporting when a change has happened in the version.

func (*WatchableService) WatchUnitTargetAgentVersion 

func (s *WatchableService) WatchUnitTargetAgentVersion(
	ctx context.Context,
	unitName coreunit.Name,
) (watcher.NotifyWatcher, error)

WatchUnitTargetAgentVersion is responsible for watching the target agent version for unit and reporting when there has been a change via a watcher.NotifyWatcher. The following errors can be expected: - applicationerrors.UnitNotFound when no unit exists for the provided name.

type WatcherFactory 

type WatcherFactory interface {
	// NewNotifyWatcher returns a new watcher that filters changes from the
	// input base watcher's db/queue. A single filter option is required, though
	// additional filter options can be provided.
	NewNotifyWatcher(
		ctx context.Context,
		summary string,
		filter eventsource.FilterOption,
		filterOpts ...eventsource.FilterOption,
	) (watcher.NotifyWatcher, error)
}

WatcherFactory provides a factory for constructing new watchers.

Source Files

View all Source files

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.