manager

package
v1.16.1 Latest Latest
Warning

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

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

README

pkg/manager

Intention

pkg/manager is the controller-runtime integration layer for the platform's reconciler/provisioner model. It is the package that turns the lower-level provisioner contract into an operational controller process with shared startup, reconcile, teardown, status, and deletion-ordering behavior.

This package is where several lower-level ideas become enforceable runtime policy:

  • the reconciler-oriented provisioner contract from pkg/provisioners
  • the "yield instead of block" progress model driven by provisioners.ErrYield
  • the context-scoping and client-access model described in pkg/client
  • the shared runtime/bootstrap options from pkg/options
  • the controller-specific option layer in options

In practice pkg/manager does three jobs:

  • bootstraps controller processes through Run(f ControllerFactory)
  • implements the generic reconcile loop through Reconciler
  • manages cross-resource deletion ordering through resource-reference helper functions

Invariants And Guard Rails

  • ControllerFactory is the top-level integration contract for controller binaries built on this package.
  • Run(f ControllerFactory) is framework bootstrap code, not a generic library helper. It owns flag wiring, logging, OpenTelemetry setup, optional upgrade/initialize hooks, manager creation, controller creation, watch registration, and process startup.
  • Reconciler is the shared reconcile-policy implementation for manager-style resources. It injects the shared execution context that descendant provisioners depend on before invoking them.
  • That injected context includes:
    • manager access via pkg/manager
    • namespace and static Kubernetes client via pkg/client
    • active cluster scope via client.ClusterContext
    • CD driver context
    • managed-resource context for pkg/provisioners/application
  • provisioners.ErrYield is a first-class control signal here. It means "stop now and requeue on the fixed yield timeout" rather than "return a hard reconcile error."
  • During normal reconcile, even unexpected provisioner errors are intentionally translated into status updates plus fixed requeue, rather than returned as raw reconcile errors, to avoid controller-runtime exponential backoff harming throughput.
  • During delete reconcile, synthetic resource references and owned-resource finalizers are checked before child deprovisioning is allowed to proceed.
  • The resource-reference helpers implement the platform's deletion-ordering contract by encoding references as extra finalizers on referenced resources.
  • ResourceReady() is the shared readiness gate for dependent resources and returns provisioners.ErrYield when a dependency is not yet provisioned.

Lower Layers

  • options: controller-specific options built on pkg/options, including max concurrency and CD driver selection.
  • provisioners: the child lifecycle contract that this package drives.
  • client: namespace/client/cluster context propagation used by the reconciler.
  • provisioners/application: receives the managed-resource and CD contexts injected here.

Caveats

  • The package boundary is broad. It mixes process bootstrap, reconcile policy, context propagation, readiness helpers, and deletion/reference semantics.
  • pkg/manager is tightly coupled to the in-tree CD model. getDriver() currently hardcodes ArgoCD driver selection and treats anything else as unsupported.
  • The shared reconcile loop relies on substantial hidden context setup before provisioners run. That is efficient for repository consistency, but it means many downstream components depend on implicit prerequisites rather than explicit method arguments.
  • The deletion-ordering model is powerful but also compromised: resource references are encoded as finalizers, and GenerateResourceReference() still carries legacy naming baggage including the unikorn-cloud.org to kubernetes.unikorn-cloud.org group rewrite.
  • Run() exits the process directly on setup failures. That is appropriate for controller binaries, but it reinforces that this package is an operational framework layer rather than a clean reusable library.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrResourceError is raised when this is used with an unsupported resource
	// kind.
	ErrResourceError = errors.New("unable to assert resource type")
)

Functions

func AddResourceReference added in v1.8.0 

func AddResourceReference(ctx context.Context, cli client.Client, resource client.Object, key client.ObjectKey, reference string) error

AddResourceReference adds the given resource reference to the specified resource. This is typically run by a controller before the resource is consumed.

func AddResourceReferences added in v1.8.0 

func AddResourceReferences(ctx context.Context, cli client.Client, resources client.ObjectList, options *client.ListOptions, reference string, ids []string) error

AddResourceReferences adds the given resource reference to all resources that match the selector and that are in the given set of IDs. An error is raised if an ID is not present. This is typically run by a controller before the resource is consumed.

func ClearResourceReferences added in v1.8.0 

func ClearResourceReferences(ctx context.Context, cli client.Client, resources client.ObjectList, options *client.ListOptions, reference string) error

ClearResourceReferences is used by controllers whose object may reference one of many other resources e.g. a server can reference multiple security groups. This is used to clean them out during the finalizing phase of deletion.

func FromContext 

func FromContext(ctx context.Context) manager.Manager

func GenerateResourceReference added in v1.8.0 

func GenerateResourceReference(client client.Client, resource client.Object) (string, error)

GenerateResourceReference takes a resource and generates a unique reference for use with blocking deletion.

func GetResourceReferences added in v1.8.0 

func GetResourceReferences(object client.Object) []string

GetResourceReferences returns all resource references attached to a resource. This is used primarily to poll a resource to see if it's in use, and thus its deletion will have consequences. It may also be used to inhibit deletion in certain cercumstances.

func NewContext 

func NewContext(ctx context.Context, manager manager.Manager) context.Context

func RemoveResourceReference added in v1.8.0 

func RemoveResourceReference(ctx context.Context, cli client.Client, resource client.Object, key client.ObjectKey, reference string) error

RemoveResourceReference removes the given resource reference from the selected resource. This is typically run by a controller after a resource has stopped being used.

func RemoveResourceReferences added in v1.8.0 

func RemoveResourceReferences(ctx context.Context, cli client.Client, resources client.ObjectList, options *client.ListOptions, reference string, ids []string) error

RemoveResourceReferences removes the given resource reference from all resources that match the selector and that are not in the given set of IDs. This is typically run by a controller after a resource has stopped being used.

func ResourceReady added in v1.8.0 

func ResourceReady(ctx context.Context, resource corev1.ManagableResourceInterface) error

ResourceReady reads a resource, and checks its readiness status. If available, then it can be used by a child, and it returns nil, otherwise returns ErrYield.

func Run 

func Run(f ControllerFactory)

Run provides common manager initialization and execution.

Types

type ControllerFactory 

type ControllerFactory interface {
	// Metadata returns the application, version and revision.
	Metadata() util.ServiceDescriptor

	// Options may be nil, otherwise it's a controller specific set of
	// options that are added to the flagset on start up and passed to the
	// reonciler.
	Options() ControllerOptions

	// Reconciler returns a new reconciler instance.
	Reconciler(options *options.Options, controllerOptions ControllerOptions, manager manager.Manager) reconcile.Reconciler

	// RegisterWatches adds any watches that would trigger a reconcile.
	RegisterWatches(manager manager.Manager, controller controller.Controller) error

	// Schemes allows controllers to add types to the client beyond
	// the defaults defined in this repository.
	Schemes() []coreclient.SchemeAdder
}

ControllerFactory allows creation of a Unikorn controller with minimal code.

type ControllerInitializer added in v1.15.0 

type ControllerInitializer interface {
	Initialize(ctx context.Context, mgr manager.Manager, opts *options.Options) error
}

ControllerInitializer when implemented on a factory lets it prepare any dependencies, after the manager has been constructed and before the factory is called on to create a controller.

type ControllerOptions added in v0.1.65 

type ControllerOptions interface {
	// AddFlags adds a set of flags to the flagset.
	AddFlags(f *pflag.FlagSet)
}

ControllerOptions abstracts controller specific flags.

type ControllerUpgrader added in v1.7.0 

type ControllerUpgrader interface {
	// Upgrade allows version based upgrades of managed resources.
	Upgrade(ctx context.Context, cli client.Client, options *options.Options) error
}

ControllerUpgrader optionally allows the factory to define an upgrade procedure. DO NOT MODIFY THE SPEC EVER, you have CRD defaulting to fill in any blanks. Only things like metadata can be touched, or the resources can be moved around. Typically you would want to attach a controller version annotation to define what API the resource is using, then drive upgrades based on that.

type ProvisionerCreateFunc 

type ProvisionerCreateFunc func(ControllerOptions) provisioners.ManagerProvisioner

ProvisionerCreateFunc provides a type agnosic method to create a root provisioner.

type Reconciler 

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

Reconciler is a generic reconciler for all manager types.

func NewReconciler 

func NewReconciler(options *options.Options, controllerOptions ControllerOptions, manager manager.Manager, createProvisioner ProvisionerCreateFunc) *Reconciler

NewReconciler creates a new reconciler.

func (*Reconciler) Reconcile 

func (r *Reconciler) Reconcile(ctx context.Context, request reconcile.Request) (reconcile.Result, error)

Reconcile is the top-level reconcile interface that controller-runtime will dispatch to. It initialises the provisioner, extracts the request object and based on whether it exists or not, reconciles or deletes the object respectively.

Source Files

View all Source files

Directories

Path Synopsis
Code generated by MockGen.
 Code generated by MockGen.

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.