manager

package
v0.0.0-...-fa08905 Latest Latest
Warning

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

 Go to latest Published: May 11, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Overview

Package manager contains the plugin manager engine that handles the workflow.

Index

Constants

View Source 
const (
	// WatcherID is the core plugin watcher's ID.
	WatcherID = "plugin-status-watcher"
	// EventID is the core plugin event type ID.
	EventID = "plugin-watcher,status"
)
View Source 
const (

	// CorePluginName is the name of the guest agent core plugin.
	CorePluginName = "GuestAgentCorePlugin"
)
View Source 
const (
	// VMEventCmd is the command name that handler supports.
	VMEventCmd = "VmEvent"
)

Variables

View Source 
var (
	// SupportedEvents is the list of supported VM events. Specialize represents
	// windows sysprep specialize phase.
	SupportedEvents = []string{"startup", "shutdown", "specialize"}
)

Functions

func RegisterCmdHandler 

func RegisterCmdHandler(ctx context.Context) error

RegisterCmdHandler registers the command handler for VM events. [vmEventHandler]notifies all the plugins about the event over [Apply()] RPC. Plugins may choose to react to the event or ignore.

Types

type CleanupJob 

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

CleanupJob is a job that cleans up old plugin states.

func (*CleanupJob) ID 

func (s *CleanupJob) ID() string

ID returns the ID of the cleanup job.

func (*CleanupJob) Interval 

func (s *CleanupJob) Interval() (time.Duration, bool)

Interval returns the interval of the cleanup job. This is set to 24 hours to run once a day.

func (*CleanupJob) MetricName 

func (s *CleanupJob) MetricName() acpb.GuestAgentModuleMetric_Metric

MetricName returns the metric name of the cleanup job.

func (*CleanupJob) Run 

func (s *CleanupJob) Run(ctx context.Context) (bool, error)

Run runs the cleanup job.

func (*CleanupJob) ShouldEnable 

func (s *CleanupJob) ShouldEnable(context.Context) bool

ShouldEnable returns true if the cleanup job should be enabled.

This should always be enabled to ensure that old plugin states are cleaned up.

type DaemonExecutionModel 

type DaemonExecutionModel struct{}

DaemonExecutionModel is the execution model for daemon plugins.

type ExecutionModel 

type ExecutionModel struct {
	// DefaultState is the base state of the plugin before any rule evaluation.
	DefaultState acmpb.ExecutionModel_State
	// MatchState is the state of the plugin if the rule matches.
	MatchState acmpb.ExecutionModel_State
	// MatchPolicy is the policy to use when evaluating the rules.
	MatchPolicy acmpb.ExecutionModel_MatchPolicy
	// Rules is the list of rules to evaluate against the host.
	Rules []*Rule
	// BootCritical is true if the plugin must run immediately at boot after agent
	// is initialized.
	BootCritical bool
	// OneShot is the execution model for one-shot plugins.
	OneShot *OneShotExecutionModel
	// Daemon is the execution model for daemon plugins.
	Daemon *DaemonExecutionModel
}

ExecutionModel is the execution model of the plugin.

type LocalPluginInstallation 

type LocalPluginInstallation struct {
	// Enable indicates if the local plugin should be enabled.
	Enable bool
	// OnReady is the callback when the local plugin is running.
	OnReady func(context.Context)
}

LocalPluginInstallation contains the configuration for a local plugin installation.

type Manifest 

type Manifest struct {
	// StartAttempts is the number of times to try launching the plugin.
	StartAttempts int
	// MaxMemoryUsage is the maximum allowed memory usage of the plugin, in bytes.
	MaxMemoryUsage int64
	// MaxCPUUsage is the maximum allowed percent CPU usage of the plugin.
	MaxCPUUsage int32
	// MaxMetricDatapoints is the maximum number of datapoints to report/collect.
	// Metrics are collected every [MetricsInterval] but are flushed from memory
	// only when reported back to the service. This count limits datapoints from
	// growing indefinitely.
	MaxMetricDatapoints uint
	// MetricsInterval is the interval at which metrics are collected.
	MetricsInterval time.Duration
	// StopTimeout is the timeout set on plugin stop request before process is
	// killed.
	StopTimeout time.Duration
	// StartTimeout is the timeout set on plugin start request.
	StartTimeout time.Duration
	// StartConfig is the config service has sent down for passing down to the
	// plugin on each start RPC request.
	StartConfig *ServiceConfig

	// LaunchArguments are extra arguments specified by plugin owners to pass down
	// during process launch.
	LaunchArguments []string
	// PluginType identifies if the plugin is a daemon or one-shot plugin.
	PluginType acmpb.PluginType
	// PluginInstallationType identifies if the plugin is installed locally or dynamically.
	PluginInstallationType acmpb.PluginInstallationType
	// ExecutionModel contains the execution model of the plugin.
	ExecutionModel *ExecutionModel
	// contains filtered or unexported fields
}

Manifest is the plugin specific static config agent received from ACP.

type Metric 

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

Metric is a struct to store the plugin's current memory and CPU usage at a specific timestamp.

type OneShotExecutionModel 

type OneShotExecutionModel struct {
	// Triggers is the list of triggers to execute the plugin.
	Triggers *Triggers
	// ExecutionTimeout is the max duration plugin is allowed to run.
	ExecutionTimeout time.Duration
}

OneShotExecutionModel is the execution model for one-shot plugins.

type Plugin 

type Plugin struct {
	// Name is the current plugin name.
	Name string
	// Revision is the current plugin revision.
	Revision string
	// Address is the current address plugin is listening on.
	Address string
	// InstallPath is the path to the directory where plugin is
	// installed/unpacked.
	InstallPath string
	// EntryPath is the path to the plugin/binary entry point from which its spun
	// up.
	EntryPath string
	// Protocol is the protocol used for communication with the plugin.
	Protocol string

	// Manifest is plugin configuration defining various agent/plugin behavior.
	Manifest *Manifest
	// RuntimeInfo holds plugin runtime information.
	RuntimeInfo *RuntimeInfo
	// contains filtered or unexported fields
}

Plugin struct represents the plugin information.

func (*Plugin) Apply 

func (p *Plugin) Apply(ctx context.Context, serviceConfig *ServiceConfig) (*pb.ApplyResponse, *status.Status)

Apply makes plugin RPC apply request. Function accepts a service config which is passed down to the plugin with the apply request instead of using the one from the plugin manifest as it allows sending adhoc configs that can be used for one off operations without having to update the plugin. For example, this can be used to trigger VM event on plugins that support it.

func (*Plugin) Connect 

func (p *Plugin) Connect(ctx context.Context) error

Connect tries to establish grpc connection to the plugin server.

func (*Plugin) FullName 

func (p *Plugin) FullName() string

FullName returns the full name of the plugin including name and revision.

func (*Plugin) GetStatus 

func (p *Plugin) GetStatus(ctx context.Context, req string) (*pb.Status, *status.Status)

GetStatus makes the GetStatus RPC request, [req] provides the context on what the request is about. For e.g. if we want status for task A, context could be task ID. For regular health check leave it empty.

func (*Plugin) IsDaemon 

func (p *Plugin) IsDaemon() bool

IsDaemon returns true if the plugin is a daemon plugin.

func (*Plugin) IsDynamic 

func (p *Plugin) IsDynamic() bool

IsDynamic returns true if the plugin is a dynamic plugin.

func (*Plugin) IsLocal 

func (p *Plugin) IsLocal() bool

IsLocal returns true if the plugin is a local plugin.

func (*Plugin) IsOneShot 

func (p *Plugin) IsOneShot() bool

IsOneShot returns true if the plugin is a one-shot plugin.

func (*Plugin) IsRunning 

func (p *Plugin) IsRunning(ctx context.Context) bool

IsRunning checks if the plugin is running by reconnecting and executing a health check.

func (*Plugin) PluginService 

func (p *Plugin) PluginService() (pb.GuestAgentPluginClient, error)

PluginService returns the underlying plugin service client.

func (*Plugin) Start 

func (p *Plugin) Start(ctx context.Context) (*pb.StartResponse, *status.Status)

Start makes plugin RPC start request.

func (*Plugin) State 

func (p *Plugin) State() acmpb.CurrentPluginStates_StatusValue

State returns the plugin status.

func (*Plugin) Stop 

func (p *Plugin) Stop(ctx context.Context, cleanup bool) (*pb.StopResponse, *status.Status)

Stop makes plugin RPC stop request.

func (*Plugin) Store 

func (p *Plugin) Store() error

Store writes plugin information to the file.

type PluginManager 

type PluginManager struct {

	// IsInitialized indicates if plugin manager is initialized.
	IsInitialized atomic.Bool
	// contains filtered or unexported fields
}

PluginManager struct represents the plugins that plugin manager manages.

func InitAdHocPluginManager 

func InitAdHocPluginManager(ctx context.Context, instanceID string) (*PluginManager, error)

InitAdHocPluginManager initializes and returns a PluginManager instance for ad-hoc requests that does not go through ACS. This is generally used by other local processes to temporarily leverage plugin manager functionality. Use this instead of InitPluginManager if there's no active plugin management required. InitAdHocPluginManager skips some initialization steps like scheduling plugin monitors that are not required for ad-hoc requests.

func InitPluginManager 

func InitPluginManager(ctx context.Context, instanceID string) (*PluginManager, error)

InitPluginManager initializes and returns a PluginManager instance. Plugin Manager can be initialized and used to support core plugins even if ACS is disabled. Plugin Manager will be initialized during early Guest Agent startup to configure the core plugins.

func Instance 

func Instance() *PluginManager

Instance returns the previously initialized instance of plugin manager.

func (*PluginManager) ConfigurePluginStates 

func (m *PluginManager) ConfigurePluginStates(ctx context.Context, req *acpb.ConfigurePluginStates)

ConfigurePluginStates configures the plugin states as stated in the request.

func (*PluginManager) Fetch 

func (m *PluginManager) Fetch(name string) (*Plugin, error)

Fetch returns the plugin instance with the given name.

func (*PluginManager) GetLocalPlugin 

func (m *PluginManager) GetLocalPlugin(ctx context.Context, name string) (*acpb.ConfigurePluginStates_ConfigurePlugin, error)

GetLocalPlugin returns the local plugin configuration for the given plugin name. If the plugin does not have a local installation, this will return nil.

func (*PluginManager) ListPluginStates 

func (m *PluginManager) ListPluginStates(ctx context.Context, req *acpb.ListPluginStates) *acpb.CurrentPluginStates

ListPluginStates returns the plugin states and cached health check information.

func (*PluginManager) RemoveAllDynamicPlugins 

func (m *PluginManager) RemoveAllDynamicPlugins(ctx context.Context) error

RemoveAllDynamicPlugins filters out core plugins and triggers plugin manager to remove all dynamic plugins on the host. It also removes the base state directory to ensure that the entire state is cleaned up.

func (*PluginManager) StartLocalPlugins 

func (m *PluginManager) StartLocalPlugins(ctx context.Context, config map[string]LocalPluginInstallation) error

StartLocalPlugins starts all local plugins that are not running and for which there are no dynamically installed versions of the plugin.

The enable map is used to determine which plugins to start. By default, a local plugin will be run if no dynamically installed version exists. If the enable map is provided, and a local plugin has an entry disabling it, then the local plugin will not be started.

func (*PluginManager) StopPlugin 

func (m *PluginManager) StopPlugin(ctx context.Context, name string) error

StopPlugin stops the plugin. This is used for ad-hoc requests that does not go through ACS. In case the plugin is not found or is not running, it returns nil error and is a no-op.

func (*PluginManager) VerifyPluginRunning 

func (m *PluginManager) VerifyPluginRunning(ctx context.Context, plugin *acpb.ConfigurePluginStates_ConfigurePlugin) error

VerifyPluginRunning verifies that the configured plugins are running.

type PluginMetrics 

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

PluginMetrics is a struct to monitor and store a plugin's metrics.

func NewPluginMetrics 

func NewPluginMetrics(plugin *Plugin, interval time.Duration) *PluginMetrics

NewPluginMetrics creates a new PluginMetrics.

func (*PluginMetrics) ID 

func (p *PluginMetrics) ID() string

ID returns the ID of the plugin metric.

func (*PluginMetrics) Interval 

func (p *PluginMetrics) Interval() (time.Duration, bool)

Interval returns the interval of the getting plugin metrics.

func (*PluginMetrics) MetricName 

func (p *PluginMetrics) MetricName() acpb.GuestAgentModuleMetric_Metric

MetricName returns the metric name for the job.

func (*PluginMetrics) Run 

func (p *PluginMetrics) Run(ctx context.Context) (bool, error)

Run gets and caches the plugin's metrics.

func (*PluginMetrics) ShouldEnable 

func (*PluginMetrics) ShouldEnable(ctx context.Context) bool

ShouldEnable returns true if this job should be scheduled or not by the scheduler.

type PluginMonitor 

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

PluginMonitor is a monitor for a plugin which implements scheduler job interface. It runs a health check and restarts the plugin if found unhealthy.

func NewPluginMonitor 

func NewPluginMonitor(plugin *Plugin, interval time.Duration) *PluginMonitor

NewPluginMonitor creates a new plugin monitor.

func (*PluginMonitor) ID 

func (m *PluginMonitor) ID() string

ID returns the plugin monitor ID.

func (*PluginMonitor) Interval 

func (m *PluginMonitor) Interval() (time.Duration, bool)

Interval returns the interval for scheduler to run this job.

func (*PluginMonitor) MetricName 

func (m *PluginMonitor) MetricName() acpb.GuestAgentModuleMetric_Metric

MetricName returns the metric name for the job.

func (*PluginMonitor) Run 

func (m *PluginMonitor) Run(ctx context.Context) (bool, error)

Run runs the plugin health check. Always return true to continue monitoring.

func (*PluginMonitor) ShouldEnable 

func (m *PluginMonitor) ShouldEnable(ctx context.Context) bool

ShouldEnable informs scheduler if this job should be scheduled job or not. Always return true to have plugin monitoring.

type Request 

type Request struct {
	command.Request
	// Event that triggered current request and must be one of [supportedEvents].
	Event string `json:"Event"`
}

Request struct represents the request from command handler.

type Rule 

type Rule struct {
	// The namespace is the namespace of the rule.
	Scope acmpb.Rules_Scope
	// Attribute is the attribute to compare against.
	Attribute string
	// ComparisonOperator to compare the attribute against the value.
	ComparisonOperator acmpb.Rules_ComparisonOperator
	// Value is the value to compare against. It is marshaled to a byte array to
	// persist across agent restarts and reuse on every plugin start request.
	// Agent will unmarshal using [toProto] method.
	Value []byte
}

Rule is a rule for triggering a plugin.

type RuntimeInfo 

type RuntimeInfo struct {

	// Pid is the process id of the plugin.
	Pid int
	// contains filtered or unexported fields
}

RuntimeInfo represent plugin metrics and health check information captured at run time. Expect info here to change during plugin execution.

type ServiceConfig 

type ServiceConfig struct {
	// Simple is simple string form of the config.
	Simple string
	// Structured is structured [*structpb.Struct] config message. It is marshaled
	// to a byte array to persist across agent restarts and reuse on every plugin
	// start request. Agent will unmarshal using [toProto] method before sending
	// it to plugins on Start RPC.
	Structured []byte
}

ServiceConfig is agent agnostic data that is passed to the plugin on every start rpc request. At any given time only one of this can be set.

type Step 

type Step interface {
	// The name of the step.
	Name() string
	// Status returns the plugin state for current step.
	Status() acmpb.CurrentPluginStates_StatusValue
	// ErrorStatus returns the plugin state if current step fails.
	ErrorStatus() acmpb.CurrentPluginStates_StatusValue
	// Performs the step.
	Run(context.Context, *Plugin) error
}

Step represents an interface for each step run as part of a plugin configuration.

type Triggers 

type Triggers struct {
	// Startup is true if the plugin runs every time when the instance boots,
	// similar to startup script.
	Startup bool
	// Firstboot is true if the plugin runs only on the very first startup of an
	// instance, triggered by an agent detecting a new instance ID.
	Firstboot bool
	// Interval is a simple recurring schedule in minutes. Schedule begins at
	// instance startup.
	Interval time.Duration
}

Triggers is the list of triggers to execute the plugin.

type Watcher 

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

Watcher is the plugin event watcher implementation.

func InitWatcher 

func InitWatcher(ctx context.Context, name string, code int32, req string) (*Watcher, error)

InitWatcher initializes and registers the watcher to monitor plugin status for a specific request. Runner also removes the watcher as soon as the condition is met.

func (*Watcher) Events 

func (w *Watcher) Events() []string

Events returns an slice with all implemented events.

func (*Watcher) ID 

func (w *Watcher) ID() string

ID returns the plugin watcher ID.

func (*Watcher) Run 

func (w *Watcher) Run(ctx context.Context, event string) (bool, any, error)

Run implements the plugin event watcher that does status check on plugin and notifies when plugin returns the required status code. Watcher stops watching the plugin once the event is detected. Non-nil error is sent only when the required event is encountered.

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.