Functionality on Porch Documentation

PackageVariant Reconciliation

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

Overview

The PackageVariant controller implements a continuous synchronization pattern between upstream and downstream packages. It monitors upstream PackageRevisions for changes, detects when downstream packages need updating, and creates appropriate drafts (clone, upgrade, or edit) to maintain synchronization while applying configured mutations.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ PackageVariant Reconciliation System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ State Machine │ │ Upstream │ │
│ │ │ ──> │ Tracking │ │
│ │ • No Downstream │ │ │ │
│ │ • Upstream Chg │ │ • UpstreamLock │ │
│ │ • Mutation Chg │ │ • Comparison │ │
│ │ • Up-to-date │ │ • Detection │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └───────────┬─────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Draft │ │
│ │ Management │ │
│ │ │ │
│ │ • Clone │ │
│ │ • Upgrade │ │
│ │ • Edit │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Reconciliation State Machine

The controller implements a state machine that determines actions based on current state:

PackageVariantSet Reconciliation

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

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. It manages bulk creation of PackageVariant CRs based on target selectors and ensures the desired set of PackageVariants matches the actual set through set-based reconciliation.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ PackageVariantSet Reconciliation System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Target │ │ Template │ │
│ │ Unrolling │ ──> │ Evaluation │ │
│ │ │ │ │ │
│ │ • Repository │ │ • CEL Exprs │ │
│ │ List │ │ • Context │ │
│ │ • Repository │ │ • Dynamic │ │
│ │ Selector │ │ Config │ │
│ │ • Object │ │ │ │
│ │ Selector │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Set-Based │ │
│ │ Reconciliation │ │
│ │ │ │
│ │ • Desired Set │ │
│ │ • Existing Set │ │
│ │ • Create/Update │ │
│ │ • Delete │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Reconciliation Flow

The controller follows a structured reconciliation process:

Mutation Application

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

Overview

The PackageVariant controller applies mutations to downstream package revisions to customize them based on the PackageVariant specification. Mutations are systematic transformations applied to package resources after cloning or upgrading from upstream, enabling configuration injection, function pipeline modification, and dynamic resource generation.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Mutation Application System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Package │ │ KRM │ │
│ │ Context │ ───> │ Functions │ │
│ │ │ │ │ │
│ │ • ConfigMap │ │ • Prepend │ │
│ │ Data │ │ • Naming │ │
│ │ • Add/Remove │ │ • Pipeline │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Config │ │
│ │ Injection │ │
│ │ │ │
│ │ • Annotation │ │
│ │ • Selector │ │
│ │ • Field Copy │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Mutation Orchestration

Mutations are applied in a specific order during package revision processing: