manager

package
v0.0.0-...-7283b26 Latest Latest
Warning

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

Go to latest
Published: Dec 18, 2025 License: Apache-2.0 Imports: 42 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 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
	// 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 Plugin

type Plugin struct {
	// PluginType identifies if the plugin type.
	PluginType PluginType
	// 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] includes 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) 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

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

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, localPlugin bool)

ConfigurePluginStates configures the plugin states as stated in the request. localPlugin identifies if the plugin is a core plugin. These core plugins are installed by package managers but not launched along with Guest Agent binary. Plugin Manager will launch and manage lifecycle of core plugins along with other dynamic plugins.

func (*PluginManager) Fetch

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

Fetch returns the plugin instance with the given name.

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) 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.

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

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

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 PluginType

type PluginType int

PluginType is the type of plugin.

const (
	// PluginTypeCore represents plugin is a core plugin. These are generally
	// packaged with the Guest Agent and installed by package mangers and offer
	// core Guest Agent functionality and are required to support various GCE
	// features.
	PluginTypeCore PluginType = iota
	// PluginTypeDynamic represents plugin is a dynamic plugin. These type of
	// plugins are optional plugins that are dynamically downloaded and installed
	// by the Guest Agent.
	PluginTypeDynamic
)

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 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_DaemonPluginState_StatusValue
	// ErrorStatus returns the plugin state if current step fails.
	ErrorStatus() acmpb.CurrentPluginStates_DaemonPluginState_StatusValue
	// Performs the step.
	Run(context.Context, *Plugin) error
}

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL