controller

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: Apache-2.0 Imports: 42 Imported by: 0

Documentation

Overview

Package controller reconciles Packages into package revisions.

Index

Constants

View Source
const (
	// AnnotationOwnedBy marks a CRD with the package that owns it.
	AnnotationOwnedBy = "kubepkg.dev/owned-by"
	// AnnotationRollbackTo asks the operator to re-apply an earlier revision.
	AnnotationRollbackTo = "kubepkg.dev/rollback-to"
	// AnnotationRollbackRequested marks a revision restored because someone
	// asked for it, not because an upgrade failed.
	AnnotationRollbackRequested = "kubepkg.dev/rollback-requested"
	// AnnotationAdopt on a Package takes over what its components would
	// create but was installed another way: Helm releases of the same
	// name, and objects applied without Helm. It is removed once a
	// revision has been applied, so later changes never take over
	// unrelated objects.
	AnnotationAdopt = "kubepkg.dev/adopt"
	// AnnotationRetry changes the desired state without changing the spec,
	// so a failed revision is attempted again.
	AnnotationRetry = "kubepkg.dev/retry"
	// AnnotationDesiredDigest on a revision records the desired state it was
	// made from; while it matches, the operator does not act again.
	AnnotationDesiredDigest = "kubepkg.dev/desired-digest"
	// AnnotationSkipPlatformValues on a PackageSource keeps the platform
	// values secret out of its components.
	AnnotationSkipPlatformValues = "kubepkg.dev/skip-platform-values"
	// AnnotationValuesFiles on a release lists the values files it was
	// rendered with.
	AnnotationValuesFiles = "kubepkg.dev/values-files"
	// AnnotationHooksDone on a revision records that its pre-upgrade hooks
	// succeeded, so later passes do not run them again.
	AnnotationHooksDone = "kubepkg.dev/hooks-done"
	// FinalizerCleanup removes releases before the Package goes away.
	FinalizerCleanup = "kubepkg.dev/cleanup"
)

Annotations kubepkg reads and writes.

View Source
const (

	// AnnotationSpecDigest on a PackageSource made from a repository is
	// the digest of the index entry it was made from.
	AnnotationSpecDigest = "kubepkg.dev/spec-digest"
	// ReasonVersionNotAvailable: no repository offers an acceptable version.
	ReasonVersionNotAvailable = "VersionNotAvailable"
)
View Source
const (
	// FinalizerPackageSet removes what a set wrote before it goes away.
	FinalizerPackageSet = "kubepkg.dev/package-set-cleanup"
)

Variables

View Source
var ErrNotManaged = fmt.Errorf("exists and is not managed by this set; left alone")

ErrNotManaged is returned for an object the set did not create.

Functions

func ClusterState

func ClusterState(ctx context.Context, c client.Reader, apis APIs) (resolve.State, error)

ClusterState gathers the installed packages and, when apis is set, the served APIs, in the form the resolver takes. The CLI plans with the same view the operator acts on.

func ComponentOrder

func ComponentOrder(comps []v1.Component) ([]string, error)

ComponentOrder lists component names so every component comes after the ones it depends on, keeping PackageSource order otherwise; a cycle is an error. Tools that render packages for other installers use the order the operator applies them in.

func DefaultImagePolicyExclude

func DefaultImagePolicyExclude() []string

DefaultImagePolicyExclude are the shared system namespaces.

func FluxHealthChecks

func FluxHealthChecks(in []v1.HealthCheck) []kustomize.CustomHealthCheck

FluxHealthChecks hands health checks to the flux backend in Flux's own type, which has the same shape.

func PackageNamespaces

func PackageNamespaces(ctx context.Context, c client.Reader) (map[string][]string, error)

PackageNamespaces maps each namespace installed packages put components in to those packages' names.

func ReleaseName

func ReleaseName(c v1.Component) string

ReleaseName is the release a component becomes.

Types

type APIs

type APIs interface {
	Served(ctx context.Context) (map[string]bool, error)
}

APIs lists group versions the API server serves, for "api:" capabilities.

type CRDOwner

type CRDOwner interface {
	// Conflict returns the owner and name of the first CRD in crds owned by
	// a package other than pkg.
	Conflict(ctx context.Context, pkg string, crds []string) (owner, crd string, err error)
	// Claim marks existing CRDs as owned by pkg.
	Claim(ctx context.Context, pkg string, crds []string) error
	// Transfer gives a CRD from one package to another, keeping it from
	// being deleted when the old owner's release lets go of it.
	Transfer(ctx context.Context, crd, from, to string) error
	// Retain lets go of the CRDs pkg owns and no longer lists in keep,
	// marking them so that removing them from a release does not delete
	// them and their objects.
	Retain(ctx context.Context, pkg string, keep []string) error
	// Release drops pkg's ownership of every CRD it owns, deleting them
	// when del is true.
	Release(ctx context.Context, pkg string, del bool) error
}

CRDOwner tracks which package owns which CRD.

type ChartPreparer

type ChartPreparer struct {
	// Mirror, when set, is the registry the tool fetches every chart from
	// (see source.MirrorPath).
	Mirror string
}

ChartPreparer hands published charts to backends that install through another tool (flux, argo). Such tools fetch charts themselves, so only components with chart can be installed this way; built packages are made of published charts.

func (ChartPreparer) Prepare

func (p ChartPreparer) Prepare(_ context.Context, src *v1.PackageSource, _ *v1.Variant, comp *v1.Component, c *backend.Component) (string, error)

Prepare implements Preparer.

type ClusterReconciler

type ClusterReconciler struct {
	client.Client
	Members MemberClients
}

ClusterReconciler checks that member clusters can be reached and run kubepkg.

func (*ClusterReconciler) Reconcile

func (r *ClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Reconcile checks one member.

func (*ClusterReconciler) SetupWithManager

func (r *ClusterReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager registers the controller.

type DiscoveryAPIs

type DiscoveryAPIs struct {
	Client discovery.DiscoveryInterface
	TTL    time.Duration
	// contains filtered or unexported fields
}

DiscoveryAPIs caches discovery for a short while: every reconcile asks, and the served API set changes only when CRDs come and go.

func (*DiscoveryAPIs) Served

func (d *DiscoveryAPIs) Served(context.Context) (map[string]bool, error)

Served implements APIs.

type KubeconfigClients

type KubeconfigClients struct {
	Hub   client.Reader
	Group string
	// contains filtered or unexported fields
}

KubeconfigClients reads members' kubeconfigs from Secrets in the hub and keeps one client per Secret version.

func (*KubeconfigClients) For

func (k *KubeconfigClients) For(ctx context.Context, c *v1.Cluster) (*Member, error)

For implements MemberClients.

type Member

type Member struct {
	Client client.Client
	Config *rest.Config
}

Member is an open connection to a member cluster.

type MemberClients

type MemberClients interface {
	For(ctx context.Context, c *v1.Cluster) (*Member, error)
}

MemberClients opens connections to member clusters.

type MetadataCRDs

type MetadataCRDs struct {
	Client client.Client
}

MetadataCRDs implements CRDOwner with metadata-only requests, so the operator never reads or rewrites a CRD schema it does not own.

func (*MetadataCRDs) Claim

func (m *MetadataCRDs) Claim(ctx context.Context, pkg string, crds []string) error

Claim implements CRDOwner.

func (*MetadataCRDs) Conflict

func (m *MetadataCRDs) Conflict(ctx context.Context, pkg string, crds []string) (string, string, error)

Conflict implements CRDOwner.

func (*MetadataCRDs) Release

func (m *MetadataCRDs) Release(ctx context.Context, pkg string, del bool) error

Release implements CRDOwner.

func (*MetadataCRDs) Retain

func (m *MetadataCRDs) Retain(ctx context.Context, pkg string, keep []string) error

Retain implements CRDOwner.

func (*MetadataCRDs) Transfer

func (m *MetadataCRDs) Transfer(ctx context.Context, crd, from, to string) error

Transfer implements CRDOwner.

type OCIPreparer

type OCIPreparer struct {
	Fetcher *source.Fetcher
	WorkDir string
}

OCIPreparer puts charts on disk for the helm backend: published charts are downloaded as they are, charts in a package tree are composed from the tree.

func (*OCIPreparer) Prepare

func (p *OCIPreparer) Prepare(ctx context.Context, src *v1.PackageSource, variant *v1.Variant, comp *v1.Component, c *backend.Component) (string, error)

Prepare implements Preparer.

type PackageReconciler

type PackageReconciler struct {
	client.Client
	Profile  Profile
	Backend  backend.Backend
	Preparer Preparer
	APIs     APIs
	// CRDs manages CRD ownership; nil disables it (tests without CRDs).
	CRDs CRDOwner
	// Repositories, when set, selects versions from repository indexes
	// for packages without a hand-written PackageSource.
	Repositories *Repositories
	// Workers is how many packages are reconciled at once; default 1. A
	// synchronous backend holds a worker until a component is ready, so
	// with one worker every other package, dependents of packages that
	// are already ready included, waits behind the slowest install.
	Workers int
}

PackageReconciler reconciles Package resources.

func (*PackageReconciler) Reconcile

func (r *PackageReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Reconcile is the main loop.

func (*PackageReconciler) SetupWithManager

func (r *PackageReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager wires the watches. Any Package change re-queues the packages that are not ready, because they may be waiting on it; at platform scale that is a few dozen objects and simpler than an index.

type PackageSetReconciler

type PackageSetReconciler struct {
	client.Client
	Members MemberClients
}

PackageSetReconciler writes a set's repositories and packages to the clusters it selects, paced by its rollout, and reports how far each got.

func (*PackageSetReconciler) Reconcile

func (r *PackageSetReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Reconcile brings one set's clusters in line.

func (*PackageSetReconciler) SetupWithManager

func (r *PackageSetReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager registers the controller; any Cluster change may change what a set selects.

type Preparer

type Preparer interface {
	// Prepare fills the chart location in c and returns a digest that
	// changes whenever the chart content changes.
	Prepare(ctx context.Context, src *v1.PackageSource, variant *v1.Variant, comp *v1.Component, c *backend.Component) (string, error)
}

Preparer puts a component's chart where the backend can read it.

type Profile

type Profile struct {
	// Group is the API group the resources are served under. A platform may
	// serve the kubepkg types under its own group.
	Group string
	// ValuesSecret, namespace/name, holds a values.yaml layered under every
	// component's values unless the PackageSource sets
	// AnnotationSkipPlatformValues. It lets a platform pass cluster-wide
	// settings to every package.
	ValuesSecret string
	// NamespaceLabels are put on every namespace the packages create.
	NamespaceLabels map[string]string
	// ImagePolicy is off, warn or enforce: whether package namespaces get
	// the label that turns the image admission webhook on there.
	ImagePolicy string
	// ImagePolicyExclude are namespaces the image policy never applies to,
	// however many packages install there: shared system namespaces, where
	// the cluster itself and tools other than packages start pods.
	ImagePolicyExclude []string
}

Profile holds the settings a platform changes to embed kubepkg. The zero value plus Group is a plain installation.

func DefaultProfile

func DefaultProfile() Profile

DefaultProfile is a plain kubepkg installation.

type Repositories

type Repositories struct {
	Store    *repo.Store
	Fetchers repo.Fetchers
	Policy   repo.Policy
}

Repositories lets the operator install packages from repository indexes. Fetchers and Policy are where a distribution plugs in its own transports and trust rules.

type RepositoryReconciler

type RepositoryReconciler struct {
	client.Client
	Repositories *Repositories
}

RepositoryReconciler keeps the index of every Repository loaded.

func (*RepositoryReconciler) Reconcile

func (r *RepositoryReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Reconcile fetches one repository index.

func (*RepositoryReconciler) SetupWithManager

func (r *RepositoryReconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager registers the controller.

Jump to

Keyboard shortcuts

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