shell_operator

package
v1.18.0 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2026 License: Apache-2.0 Imports: 45 Imported by: 6

Documentation

Index

Constants

View Source 
const DefaultShutdownTimeout = 30 * time.Second

DefaultShutdownTimeout bounds how long Shutdown waits for queues, informers and HTTP servers to drain when the caller's context has no deadline.

Variables

This section is empty.

Functions

func RunDefaultDebugServer added in v1.4.0 

func RunDefaultDebugServer(unixSocket, httpServerAddress string, logger *log.Logger) (*debug.Server, error)

RunDefaultDebugServer initialized and run default debug server on unix and http sockets This method is also used in addon-operator

Types

type AdmissionEventHandler added in v1.16.2 

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

AdmissionEventHandler handles admission webhook events by creating a hook task, running it synchronously, and returning the hook's admission response.

func NewAdmissionEventHandler added in v1.16.2 

func NewAdmissionEventHandler(hm hook.HookManager, runner TaskRunner, factory HookTaskFactory, logger *log.Logger) *AdmissionEventHandler

NewAdmissionEventHandler creates a new AdmissionEventHandler. The factory argument is used to build HookRun tasks; pass HookTaskFactory{} to use the default zero-value implementation.

func (*AdmissionEventHandler) Handle added in v1.16.2 

func (h *AdmissionEventHandler) Handle(ctx context.Context, event admission.Event) (*admission.Response, error)

Handle implements the admission event handler func signature expected by admission.WebhookManager.WithAdmissionEventHandler.

type CombineResult 

type CombineResult struct {
	BindingContexts []bctx.BindingContext
	MonitorIDs      []string
}

type ConversionEventHandler added in v1.16.2 

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

ConversionEventHandler handles conversion webhook events by finding the conversion path, running the appropriate hook tasks, and returning the converted objects.

func NewConversionEventHandler added in v1.16.2 

func NewConversionEventHandler(hm hook.HookManager, runner TaskRunner, factory HookTaskFactory, logger *log.Logger) *ConversionEventHandler

NewConversionEventHandler creates a new ConversionEventHandler. The factory argument is used to build HookRun tasks; pass HookTaskFactory{} to use the default zero-value implementation.

func (*ConversionEventHandler) Handle added in v1.16.2 

func (h *ConversionEventHandler) Handle(ctx context.Context, crdName string, request *v1.ConversionRequest) (*conversion.Response, error)

Handle implements the conversion event handler func signature expected by conversion.WebhookManager.EventHandlerFn.

type DebugShutdowner added in v1.18.0 

type DebugShutdowner interface {
	Shutdown(ctx context.Context) error
}

DebugShutdowner is the subset of *debug.Server that ShellOperator needs at shutdown time. Using an interface avoids importing pkg/debug into operator.go and keeps the debug server optional.

type HookTaskFactory added in v1.16.1 

type HookTaskFactory struct{}

HookTaskFactory builds HookRun tasks, deduplicating the repeated boilerplate across kube event, schedule, admission, and conversion event handlers.

The factory does not set WithQueuedAt; callers should stamp the task with task.WithQueuedAt(time.Now()) when the task is ready to be enqueued.

func (HookTaskFactory) NewHookRunTask added in v1.16.1 

func (HookTaskFactory) NewHookRunTask(hookName string, bindingType types.BindingType, info controller.BindingExecutionInfo, logLabels map[string]string) task.Task

NewHookRunTask creates a HookRun task populated from a hook and a BindingExecutionInfo. It sets the CompactionID to hook.Name and copies QueueName from info.QueueName.

func (HookTaskFactory) NewSyncHookRunTask added in v1.16.1 

func (HookTaskFactory) NewSyncHookRunTask(h *hook.Hook, info controller.BindingExecutionInfo, logLabels map[string]string) task.Task

NewSyncHookRunTask creates a HookRun task for the Kubernetes synchronization flow. It sets extra MonitorIDs and ExecuteOnSynchronization fields, and always uses the "main" queue regardless of info.QueueName.

type KubeClientConfig added in v1.16.0 

type KubeClientConfig struct {
	Context      string
	Config       string
	QPS          float32
	Burst        int
	Timeout      time.Duration // zero means no timeout
	MetricPrefix string
}

KubeClientConfig holds explicit connection settings for a Kubernetes client, decoupling business logic from the global app.* configuration variables.

type ManagerEventsHandler 

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

func (*ManagerEventsHandler) Start 

func (m *ManagerEventsHandler) Start()

Start runs the events handler. Calling Start a second time is a no-op; the original loop keeps running until Stop is called.

func (*ManagerEventsHandler) Stop 

func (m *ManagerEventsHandler) Stop()

Stop signals the events handler loop to exit. Stop is non-blocking; pair it with Wait when you need a synchronous teardown.

func (*ManagerEventsHandler) Wait added in v1.18.0 

func (m *ManagerEventsHandler) Wait(ctx context.Context) error

Wait blocks until the events handler loop has exited or ctx is canceled. When Start was never called, Wait returns immediately.

func (*ManagerEventsHandler) WithKubeEventHandler 

func (m *ManagerEventsHandler) WithKubeEventHandler(fn func(ctx context.Context, kubeEvent kemtypes.KubeEvent) []task.Task)

WithKubeEventHandler sets custom function for event handling. This function is used inside addon-operator.

func (*ManagerEventsHandler) WithScheduleEventHandler 

func (m *ManagerEventsHandler) WithScheduleEventHandler(fn func(ctx context.Context, crontab string) []task.Task)

WithScheduleEventHandler sets custom scheduler function. This function is used inside addon-operator.

type Option added in v1.5.0 

type Option func(operator *ShellOperator)

func WithHookMetricStorage added in v1.18.0 

func WithHookMetricStorage(ms metricsstorage.Storage) Option

WithHookMetricStorage overrides the default per-instance HookMetricStorage.

func WithLogger added in v1.5.0 

func WithLogger(logger *log.Logger) Option

func WithMetricStorage added in v1.18.0 

func WithMetricStorage(ms metricsstorage.Storage) Option

WithMetricStorage overrides the default per-instance MetricStorage. Most callers should not need this; pass it only when sharing the registry with an outer program.

type ShellOperator 

type ShellOperator struct {

	// APIServer common http server for liveness and metrics endpoints
	APIServer *baseHTTPServer

	// MetricStorage collects and store metrics for built-in operator primitives, hook execution
	MetricStorage metricsstorage.Storage
	// HookMetricStorage separate metric storage for metrics, which are returned by user hooks
	HookMetricStorage metricsstorage.Storage

	KubeClient    *klient.Client
	ObjectPatcher *objectpatch.ObjectPatcher

	ScheduleManager   schedulemanager.ScheduleManager
	KubeEventsManager kubeeventsmanager.KubeEventsManager

	TaskQueues *queue.TaskQueueSet

	ManagerEventsHandler *ManagerEventsHandler

	HookManager hook.HookManager

	AdmissionWebhookManager  *admission.WebhookManager
	ConversionWebhookManager *conversion.WebhookManager

	// DebugServer is optional. When non-nil, Shutdown stops it. The assembly
	// path in Init() populates it with the default debug server.
	DebugServer DebugShutdowner

	// MetricNames is a per-instance snapshot of resolved metric names.
	// Library callers may consult it to avoid relying on the package-level
	// metrics globals. NewShellOperator populates it from cfg's prefix; the
	// bare constructor leaves it nil — callers can fill it later via
	// metrics.NewNames(prefix) if needed.
	MetricNames *metrics.Names
	// contains filtered or unexported fields
}

func Init deprecated added in v1.0.11 

func Init(ctx context.Context, cfg *app.Config, logger *log.Logger) (*ShellOperator, error)

Init is a thin wrapper kept for compatibility with code that still calls the previous bootstrap entry point. New code should call NewShellOperator directly.

Deprecated: use NewShellOperator(ctx, cfg, WithLogger(logger)) instead.

func NewBareShellOperator added in v1.18.0 

func NewBareShellOperator(ctx context.Context, opts ...Option) *ShellOperator

NewBareShellOperator constructs an empty *ShellOperator without wiring any of the heavy components (HookManager, webhook managers, debug server, etc.). It is intended for tests and downstream tooling that need to assemble a subset of the operator manually; production code should call NewShellOperator(ctx, cfg, ...) instead.

The returned operator has only context, logger, MetricStorage and HookMetricStorage initialized. All other fields are nil and the caller is responsible for populating them before Start.

func NewShellOperator 

func NewShellOperator(ctx context.Context, cfg *app.Config, opts ...Option) (*ShellOperator, error)

NewShellOperator builds a fully assembled, ready-to-Start operator from cfg. It supersedes the previous Init + NewShellOperator pair: it owns directory validation, metric storage construction, logging setup, debug server, kube clients, hook discovery and webhook initialization.

The returned operator is in the "ready" state — call Start to begin processing and Shutdown to tear everything down. After Shutdown returns, build a fresh instance via NewShellOperator to start over; *ShellOperator values are not meant to be reused across Stop/Start cycles.

func (*ShellOperator) AssembleCommonOperator added in v1.4.0 

func (op *ShellOperator) AssembleCommonOperator(listenAddress, listenPort string, kubeEventsManagerLabels []string, mainKubeCfg, patcherKubeCfg KubeClientConfig) error

AssembleCommonOperator instantiates common dependencies used by both shell-operator and its derivatives (e.g. addon-operator). Requires listenAddress and listenPort to run the HTTP server for operator APIs. kubeCfg provides Kubernetes connection settings for the main client and object patcher; pass KubeClientConfig{} to fall back to in-cluster defaults.

For library consumers that already hold an *app.Config, prefer AssembleCommonOperatorFromConfig instead of unpacking fields by hand.

func (*ShellOperator) AssembleCommonOperatorFromConfig added in v1.17.2 

func (op *ShellOperator) AssembleCommonOperatorFromConfig(cfg *app.Config, kubeEventsManagerLabels []string) error

AssembleCommonOperatorFromConfig is the recommended assembly entry point for library consumers that already hold a fully populated *app.Config (for example, addon-operator builds its own and embeds shell-operator).

It derives the HTTP server address, the main and object-patcher KubeClientConfigs from cfg and delegates to AssembleCommonOperator. The derivation reads only the supplied *app.Config — no environment variables are consulted on this path, so the values you put into cfg are the values shell-operator uses. See kubeClientConfigsFromAppConfig for the exact field mapping.

kubeEventsManagerLabels are the metric labels for the kube-events manager; each embedder typically passes its own (e.g. addon-operator adds "module" and "kind", shell-operator passes "hook"/"binding"/"queue").

Pass a nil cfg to fall back to zero-valued KubeClientConfig (in-cluster defaults) — useful for tests.

func (*ShellOperator) CombineBindingContextForHook 

func (op *ShellOperator) CombineBindingContextForHook(q *queue.TaskQueue, t task.Task, stopCombineFn func(tsk task.Task) bool) *CombineResult

CombineBindingContextForHook combines binding contexts from a sequence of task with similar hook name and task type into array of binding context and delete excess tasks from queue.

Also, sequences of binding contexts with similar group are compacted in one binding context.

If input task has no metadata, result will be nil. Metadata should implement HookNameAccessor, BindingContextAccessor and MonitorIDAccessor interfaces. DEV WARNING! Do not use HookMetadataAccessor here. Use only *Accessor interfaces because this method is used from addon-operator.

func (*ShellOperator) RegisterBuiltinTaskHandlers added in v1.16.2 

func (op *ShellOperator) RegisterBuiltinTaskHandlers()

RegisterBuiltinTaskHandlers populates the registry with the three core task types. It must be called after HookManager is set. Extenders may call Register() afterwards to add extra task types without touching this method.

func (*ShellOperator) RegisterDebugConfigRoutes added in v1.4.0 

func (op *ShellOperator) RegisterDebugConfigRoutes(dbgSrv *debug.Server, runtimeConfig *config.Config)

RegisterDebugConfigRoutes registers routes to manage runtime configuration. This method is also used in addon-operator

func (*ShellOperator) RegisterDebugHookRoutes added in v1.4.0 

func (op *ShellOperator) RegisterDebugHookRoutes(dbgSrv *debug.Server)

RegisterDebugHookRoutes register routes for dumping queues

func (*ShellOperator) RegisterDebugQueueRoutes added in v1.4.0 

func (op *ShellOperator) RegisterDebugQueueRoutes(dbgSrv *debug.Server)

RegisterDebugQueueRoutes register routes for dumping main queue this method is also used in addon-operator

func (*ShellOperator) Run added in v1.18.0 

func (op *ShellOperator) Run(ctx context.Context) error

Run is a convenience that Start()s the operator, blocks until ctx is canceled, then performs a synchronous Shutdown with a derived timeout. Use it from main() and tests; library consumers that want fine-grained control should call Start and Shutdown directly.

func (*ShellOperator) SetupEventManagers added in v1.4.0 

func (op *ShellOperator) SetupEventManagers()

SetupEventManagers instantiate queues and managers for schedule and Kubernetes events. This function is also used in the addon-operator

func (*ShellOperator) Shutdown 

func (op *ShellOperator) Shutdown(ctx context.Context) error

Shutdown gracefully tears down everything started by Start. It is synchronous: when Shutdown returns, no goroutine spawned by the operator is still running and every TCP port / unix socket / file descriptor opened during Start has been released. Subsequent calls return the original shutdown error.

The supplied ctx bounds how long Shutdown waits for in-flight queues, informers and HTTP servers; if it has no deadline DefaultShutdownTimeout is applied automatically.

func (*ShellOperator) Start 

func (op *ShellOperator) Start(_ context.Context) error

Start runs the operator: opens listeners, primes queues, spawns the metric and event goroutines. It is non-blocking. Calling Start twice is a no-op; the first call's error is returned to subsequent callers.

type TaskHandlerFunc added in v1.16.2 

type TaskHandlerFunc func(ctx context.Context, t task.Task) queue.TaskResult

TaskHandlerFunc is the function type for handling a single task.

type TaskHandlerRegistry added in v1.16.2 

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

TaskHandlerRegistry maps task types to their handlers. New task types can be registered without modifying the dispatcher.

func NewTaskHandlerRegistry added in v1.16.2 

func NewTaskHandlerRegistry() *TaskHandlerRegistry

NewTaskHandlerRegistry creates an empty registry.

func (*TaskHandlerRegistry) Handle added in v1.16.2 

func (r *TaskHandlerRegistry) Handle(ctx context.Context, t task.Task) (queue.TaskResult, bool)

Handle dispatches the task to the registered handler. Returns a Fail result when no handler is found.

func (*TaskHandlerRegistry) Register added in v1.16.2 

func (r *TaskHandlerRegistry) Register(taskType task.TaskType, handler TaskHandlerFunc)

Register associates a handler with a task type. Registering the same type twice overwrites the previous handler.

type TaskRunner added in v1.16.2 

type TaskRunner func(ctx context.Context, t task.Task) queue.TaskResult

TaskRunner executes a task synchronously and returns its result. ShellOperator.taskHandler satisfies this type.

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.