Documentation
¶
Index ¶
- type App
- type Module
- type PreservePackage
- type Runtime
- func (r *Runtime) BuildKubeTasks(ctx context.Context, kubeEvent shkubetypes.KubeEvent) map[string][]queue.Task
- func (r *Runtime) BuildScheduleTasks(ctx context.Context, crontab string) map[string][]queue.Task
- func (r *Runtime) CheckConstraints(name string, constraints schedule.Constraints) error
- func (r *Runtime) Cleanup(ctx context.Context, preserves []PreservePackage)
- func (r *Runtime) Dump() []byte
- func (r *Runtime) DumpByName(name string) []byte
- func (r *Runtime) DumpGlobal() []byte
- func (r *Runtime) GetStatus(name string) status.Status
- func (r *Runtime) GetStatusQueue() workqueue.TypedRateLimitingInterface[string]
- func (r *Runtime) PauseScheduler()
- func (r *Runtime) RemoveApp(namespace, instance string)
- func (r *Runtime) RemoveModule(name string)
- func (r *Runtime) ResumeScheduler()
- func (r *Runtime) Run()
- func (r *Runtime) Stop()
- func (r *Runtime) UpdateApp(repo registry.Remote, app App)
- func (r *Runtime) UpdateModule(repo registry.Remote, module Module)
- func (r *Runtime) UpdateModulesSettings(name string, settingsVersion int, settings addonutils.Values, enabled *bool)
- func (r *Runtime) ValidatePackageSettings(ctx context.Context, name string, settingsVersion int, ...) (settingscheck.Result, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
Name string
Namespace string
Definition apps.Definition
Settings addonutils.Values
SettingsVersion int // schema version from Application.Spec.Version (reserved for future use)
Maintenance string
}
App represents an application instance as received from the Application controller. It carries the user-specified package identity, version constraints, settings, and maintenance mode.
type Module ¶
type Module struct {
Name string
Definition modules.Definition
Settings addonutils.Values
SettingsVersion int // schema version from ModuleConfig.Spec.Version
}
Module represents a module instance as received from the module controller. Unlike App, modules always run in the d8-system namespace.
type PreservePackage ¶ added in v1.76.1
type PreservePackage struct {
PackageName string
Repository string
Version string
ReleaseName string
ReleaseNamespace string
}
PreservePackage identifies one installed Package instance to preserve during Cleanup.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime orchestrates the full lifecycle of application packages: discovery, installation, hook execution, Helm release management, and removal.
State is split across three structures, all protected by r.mu:
- packages (lifecycle.Store): contexts and pending settings — the cancellation and change-detection layer, type-agnostic
- apps: loaded Application instances, keyed by name
- modules: loaded Module instances, keyed by name
Task execution is delegated to queue.Service (one queue per package), and cluster coordination to the scheduler, NELM, and hook event systems.
func New ¶
func New(cli kclient.Client, edition *edition.Edition, moduleManager moduleManagerI, dc dependency.Container, metricStorage metricsstorage.Storage, logger *log.Logger) (*Runtime, error)
New creates and initializes a Runtime with all subsystems wired together. Blocks until the NELM cache completes its initial sync.
func (*Runtime) BuildKubeTasks ¶
func (r *Runtime) BuildKubeTasks(ctx context.Context, kubeEvent shkubetypes.KubeEvent) map[string][]queue.Task
BuildKubeTasks converts a Kubernetes event into executable tasks for all matching hooks.
For each package (applications and the global module):
- Find hooks that are bound to Kubernetes events
- Check if the hook can handle this specific event (filtering)
- Generate tasks for matching hooks using the provided builder
Returns a map of queue names to tasks, allowing different hooks to be routed to different queues (e.g., priority queues, sequential queues).
func (*Runtime) BuildScheduleTasks ¶
BuildScheduleTasks converts a schedule (cron) event into executable tasks for all matching hooks.
For each package (applications and the global module):
- Find hooks that are bound to schedule events
- Check if the hook's schedule matches the triggered crontab
- Generate tasks for matching hooks using the provided builder
Returns a map of queue names to tasks, allowing hooks to specify their execution queue.
func (*Runtime) CheckConstraints ¶ added in v1.76.0
func (r *Runtime) CheckConstraints(name string, constraints schedule.Constraints) error
CheckConstraints validates the proposed package constraints against the current cluster state and dependency graph. The `name` is the scheduler-side identifier (apps.BuildName for applications, module name for modules) and is used by the cycle simulation step to identify the proposed graph vertex.
func (*Runtime) Cleanup ¶ added in v1.76.1
func (r *Runtime) Cleanup(ctx context.Context, preserves []PreservePackage)
Cleanup removes downloaded application packages on disk and orphan nelm releases in the cluster that are not in preserves. Runs once during preflight.
func (*Runtime) Dump ¶
Dump returns a YAML snapshot of all packages and their current state.
Includes for each package:
- Status: Current phase (Pending/Loaded/Running)
- State: Scheduler state (enabled/disabled with reason)
- Info: Instance name and namespace, current package configuration values and hooks
Used for debugging and introspection of operator internal state. Skips packages that have been removed from the manager.
func (*Runtime) DumpByName ¶ added in v1.76.0
DumpByName returns a YAML snapshot of a single package by name. Checks apps first, then modules. Returns an empty dump if not found.
func (*Runtime) DumpGlobal ¶ added in v1.77.0
DumpGlobal returns a YAML snapshot of the global module's package info.
The snapshot mirrors global.Info: instance name, running state, filesystem path, current values, and the names of registered hooks. Returns nil when the global module has not been initialized (r.global is nil), which the debug handler surfaces as an empty body.
func (*Runtime) GetStatusQueue ¶ added in v1.77.0
func (r *Runtime) GetStatusQueue() workqueue.TypedRateLimitingInterface[string]
GetStatusQueue returns the status queue for external access
func (*Runtime) PauseScheduler ¶ added in v1.76.1
func (r *Runtime) PauseScheduler()
PauseScheduler suspends the scheduler so it stops firing enable/disable callbacks.
func (*Runtime) RemoveApp ¶
RemoveApp removes an application and cancels all its running operations.
After the undeploy task succeeds, a cleanup goroutine removes the Store entry and stops the queue. The goroutine is necessary because queueService.Remove stops the queue — calling it synchronously from within the queue's own processing loop would deadlock on WaitGroup.
Store.Delete has a state guard: if UpdateApp re-created the package between undeploy and cleanup, Delete is a no-op (version != "").
func (*Runtime) RemoveModule ¶
RemoveModule removes a module and cancels all its running operations. After undeploy, a cleanup goroutine removes the Store entry and stops the queue. See RemoveApp for detailed rationale on the async cleanup pattern.
func (*Runtime) ResumeScheduler ¶ added in v1.76.1
func (r *Runtime) ResumeScheduler()
ResumeScheduler resumes the scheduler after a previous pause.
func (*Runtime) Run ¶ added in v1.76.0
func (r *Runtime) Run()
Run starts the scheduler event loop in a background goroutine. It listens for schedule and disable events from the scheduler and dispatches them to the appropriate handler, driving the enable/disable lifecycle for all packages.
func (*Runtime) Stop ¶
func (r *Runtime) Stop()
Stop performs graceful shutdown of all operator subsystems.
Shutdown order ensures safe termination:
- Stop NELM monitors (cleanup resource monitoring)
- Pause Kubernetes event handling (no new resource events)
- Stop schedule manager (no new cron triggers)
- Stop event handler (no new task generation)
- Stop queue service (no new task processing)
This order prevents new work from entering the system while allowing in-flight operations to complete gracefully where possible.
func (*Runtime) UpdateApp ¶
UpdateApp handles application creation and version changes from the Application controller.
Flow:
- NeedUpdate fast-path: skip if version and settings checksum are unchanged
- Store.Update: if version changed → new root context, enqueue full pipeline (Disable → Deploy → Load); if only settings changed → nil context, trigger Reschedule so the scheduler re-runs Configure → Startup → Run
- CheckConstraints: validate Kubernetes/Deckhouse version requirements before enqueuing
Settings are applied lazily: the scheduler's schedulePackage reads pending settings from the Store via GetPendingSettings when the package is scheduled for startup.
func (*Runtime) UpdateModule ¶
UpdateModule handles module creation and version changes from the module controller.
Flow mirrors UpdateApp: version changes enqueue the full pipeline (Disable → Deploy → Load), settings-only changes trigger Reschedule to re-apply settings through the scheduler's schedule pipeline. See UpdateApp for detailed flow documentation.
func (*Runtime) UpdateModulesSettings ¶ added in v1.77.0
func (r *Runtime) UpdateModulesSettings(name string, settingsVersion int, settings addonutils.Values, enabled *bool)
UpdateModulesSettings applies a settings-and-enabled change to an already-tracked package without redeploying or reloading it. It is meant to be wired into the packages-config-controller, which owns package settings and the ModuleConfig enabled intent independently of the package version handled by UpdateModule. enabled is the tri-state user intent (*true/*false set by a ModuleConfig, nil when unset) consumed by the scheduler's config rule.
Unlike UpdateModule, this never enqueues Deploy/Load tasks and never cancels the package's context tree: it only stashes the new pending settings and enabled intent and, if either actually changed, triggers Reschedule so the scheduler re-resolves the rule chain (re-evaluating the config rule) and, when the package stays enabled, re-runs the Configure → Startup → Run pipeline (see schedulePackage) with the new values. Any in-flight deploy or load for the package keeps running untouched.
Settings and the enabled intent diverge when the package is not tracked yet. The enabled intent is always recorded: it lives in the global module, which has no notion of tracking, so the scheduler's config rule sees the user intent the moment the package is registered. Pending settings, by contrast, are dropped — there is no per-package store to stash them in yet; the eventual UpdateModule registers the package and supplies its settings. Either way, an untracked package has no node to reschedule, so no Reschedule happens here.
func (*Runtime) ValidatePackageSettings ¶ added in v1.77.0
func (r *Runtime) ValidatePackageSettings(ctx context.Context, name string, settingsVersion int, settings addonutils.Values) (settingscheck.Result, error)
ValidatePackageSettings converts (if needed) and validates settings against the package's OpenAPI schema. Returns valid if the package is not loaded yet.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package debug provides a Unix socket-based HTTP server and client for runtime debugging and inspection.
|
Package debug provides a Unix socket-based HTTP server and client for runtime debugging and inspection. |
|
Package hookevent provides event handling for Kubernetes and schedule events.
|
Package hookevent provides event handling for Kubernetes and schedule events. |
|
tasks
|
|
|
globalrun
Package globalrun provides the global node's unit of work: run the global BeforeAll hooks, ensure the CRDs of every enabled module, then publish the enabled set and the discovered CRD capabilities into global values, before any module converges behind the global barrier.
|
Package globalrun provides the global node's unit of work: run the global BeforeAll hooks, ensure the CRDs of every enabled module, then publish the enabled set and the discovered CRD capabilities into global values, before any module converges behind the global barrier. |