PackageVariant Controllers on Porch Documentation

Design

Mon, 01 Jan 0001 00:00:00 +0000

Architecture

The Controllers follow a standard Kubernetes controller pattern using the controller-runtime framework:

┌─────────────────────────────────────────────────────┐
│ Controller Manager │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ PackageVariant │ │PackageVariantSet │ │
│ │ Reconciler │ │ Reconciler │ │
│ │ │ │ │ │
│ │ Watch/Reconcile │ │ Watch/Reconcile │ │
│ │ Loop │ │ Loop │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ ↓ │
│ ┌─────────────────┐ │
│ │ Shared Client │ │
│ │ (Porch API) │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────┘

Key architectural patterns:

PackageVariant Controller

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The PackageVariant Controller is a Kubernetes controller that manages individual package variants - maintaining a one-to-one relationship between an upstream package and a downstream package. It continuously synchronizes downstream PackageRevisions with upstream changes and applies configured mutations.

Key characteristics:

Reconciliation-based: Uses standard Kubernetes controller-runtime reconciliation loop
Upstream tracking: Monitors upstream PackageRevisions for changes via UpstreamLock comparison
Draft-driven workflow: All changes create draft PackageRevisions that require approval
Policy-based ownership: Configurable adoption and deletion policies for existing packages
Mutation application: Applies package context, pipeline functions, and config injection
Finalizer-based cleanup: Ensures proper cleanup of owned PackageRevisions on deletion

Implementation Details

Reconciliation State Machine

The PackageVariant controller implements a state machine that determines actions based on the current state of upstream and downstream packages:

PackageVariantSet Controller

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The PackageVariantSet Controller manages bulk creation of PackageVariant CRs based on target selectors. It implements a declarative fan-out pattern where a single upstream package is automatically instantiated across multiple downstream targets using template-based generation with CEL expressions.

Key characteristics:

Fan-out pattern: One upstream package → multiple PackageVariant CRs → multiple downstream packages
Target selection: Three mechanisms for identifying targets (repository list, repository selector, object selector)
Template-based generation: Single template generates multiple PackageVariants with per-target customization
CEL expression evaluation: Dynamic configuration using Common Expression Language
Set-based reconciliation: Desired state computed and reconciled against existing PackageVariants
Owner reference management: PackageVariantSet owns all generated PackageVariants

Reconciliation Overview

The PackageVariantSet controller implements a declarative fan-out pattern where a single upstream package is automatically instantiated across multiple downstream targets using template-based generation with CEL expressions.

Interactions with Porch APIs

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Controllers are clients of the Porch API, not part of the Porch server. They run as a separate microservice, interacting with Porch through standard Kubernetes client-go mechanisms. The controllers watch Porch API resources (PackageRevisions, Repositories) and create/update/upgrade PackageRevisions (PackageVariant controller) and PackageVariants (PackageVariantSet controller) through the Porch API to automate creation and management of package revisions on two levels of templating. PackageVariants allow multiple downstream package revisions, each with its own defined customisations, to be spun off a single upstream package revision; PackageVariantSets enable the same behaviour for PackageVariants themselves.