Porch on Porch Documentation

CLI Reference

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

Overview

porchctl is the command-line interface for interacting with Porch. It communicates with a Kubernetes API server that has Porch installed as an aggregated API server, allowing you to manage repository registrations and packages within those repositories.

Installation

See Installing porchctl for installation instructions.

Global Flags

These flags are available for all porchctl commands:

Flag	Description	Default
`--kubeconfig string`	Path to kubeconfig file. Only required if out-of-cluster. Can also be set via `KUBECONFIG` environment variable.
`--log-flush-frequency duration`	Maximum seconds between log flushes	`5s`
`--truncate-output`	Enable output truncation	`true`
`-v, --v Level`	Log level verbosity
`-h, --help`	Help for porchctl

Commands

repo - Manage package repositories
rpkg - Manage packages
completion - Generate shell autocompletion
version - Print version information

repo

Manage package repositories.

Development Environment

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

This guide walks you through setting up a local Porch development environment with a kind cluster, enabling you to debug the Porch server and controllers in VS Code with various configurations.

Prerequisites

Docker
kind
kubectl
Go (version specified in Porch’s go.mod)
VS Code with Go extension
make

MacOS Users

The deployment scripts require bash 4.x or later. MacOS ships with bash 3.x:

Install bash 4.x+ via Homebrew: brew install bash
Ensure /opt/homebrew/bin appears before /bin and /usr/bin in your PATH

Warning

This permanently changes your default bash version system-wide.

Automated Setup

The quickest way to set up your development environment - from the root directory of the Porch repository, run:

Function Evaluation

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

Overview

Function evaluation is the core responsibility of the Function Runner - executing KRM (Kubernetes Resource Model) functions through pluggable evaluator strategies. The system uses a strategy pattern where different evaluators handle function execution in different ways (pod-based, executable, or chained), all conforming to a common interface.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Function Evaluation System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Evaluator │ │ Execution │ │
│ │ Interface │ ───> │ Strategies │ │
│ │ │ │ │ │
│ │ • Common │ │ • Pod Evaluator │ │
│ │ Contract │ │ • Exec Evaluator│ │
│ │ • Pluggable │ │ • Multi Eval │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Wrapper │ │
│ │ Server │ │
│ │ │ │
│ │ • gRPC Frontend │ │
│ │ • Binary Exec │ │
│ │ • Result Parse │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Evaluator Interface

All evaluators implement a common interface that defines the contract for function execution.

Git Authentication

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

Authentication Methods

The Porch Server handles interaction with Git repositories through Repository Custom Resources (CRs) that act as a link between the Porch Server and the Git repositories.

Porch Server supports three authentication methods for Git repositories:

Basic Authentication - Username and password or Personal Access Token (post-deployment)
Bearer Token Authentication - Token-based authentication (post-deployment)
HTTPS/TLS Configuration - Custom TLS certificates for self-hosted Git (requires pre-deployment configuration)

1. Basic Authentication

Uses username and password or Personal Access Token (PAT). The secret must:

Installing Porchctl CLI

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

Download the latest porchctl binary

curl -LO "https://github.com/nephio-project/porch/releases/download/v1.5.9/porchctl_1.5.9_linux_amd64.tar.gz"

curl -LO "https://github.com/nephio-project/porch/releases/download/v1.5.9/porchctl_1.5.9_linux_arm64.tar.gz"

curl -LO "https://github.com/nephio-project/porch/releases/download/v1.5.9/porchctl_1.5.9_darwin_amd64.tar.gz"

curl -LO "https://github.com/nephio-project/porch/releases/download/v1.5.9/porchctl_1.5.9_darwin_arm64.tar.gz"

Note:

To download a specific version of porch and its porchctl binary you can do so by replacing the version number and machine type its for in the curl link above.

Packages

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

Important!

A “Porch package” is a collection of package revisions on the same kpt package. Porch does not have the concept of a “Package” internally - whenever an API request is received on a package, Porch composes the response from the package revisions associated with the kpt package. When users say they are creating, editing, or upgrading “a package” in Porch, they are manipulating a PackageRevision resource and its paired PackageRevisionResources resource. These are Porch’s Kubernetes API interpretations of kpt package metadata and contents stored in Git repositories.

What is a Package in Porch?

In Porch, a package is represented, not as files you directly manipulate, but through Kubernetes API resources presenting different views of the package’s file contents. When you work with a package in Porch, you interact with revisions of the package, and each such package revision has a pair of resources: a PackageRevision resource and a PackageRevisionResources resource:

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:

Repository Sync

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

Documentation Location

This documentation is currently located in the system configuration section but should be moved to a more logical location as it’s about configuring individual Repository resources, not system-wide settings. This may be relocated in future documentation updates.

Sync Configuration Fields

The spec.sync field in a Repository CR controls synchronization behavior with the external repository. Repositories without sync configuration use the system default for periodic synchronization (default 1 hour, configurable via --repositories.full-sync-frequency flag - see Repository Controller Configuration.

Repository Synchronization

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

Moved

Repository synchronization is now handled by the Repository Controller.

See:

Sync Behavior

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

Overview

The Repository controller uses two types of sync operations to keep repositories up-to-date:

Health checks: Lightweight connectivity validation that runs frequently to detect failures quickly
Full syncs: Complete repository synchronization that runs less often to fetch content and discover packages

The controller intelligently decides which operation to perform based on repository state and configured scheduling.

Sync Operations

Health Check

Health checks perform quick connectivity validation without fetching repository contents. They execute synchronously in the reconcile loop, validating only that the repository is reachable without the overhead of git operations.

API Reference

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

Packages

porch.kpt.dev/v1alpha1

porch.kpt.dev/v1alpha1

Condition

Appears in:

PackageRevisionStatus

Field	Description	Default	Validation
`type` string
`status` ConditionStatus
`reason` string
`message` string

ConditionStatus

Appears in:

Condition

Field	Description
`True`
`False`
`Unknown`

Field

Field references a field in a resource

Appears in:

ResultItem

Field	Description	Default	Validation
`path` string	Path is the field path. This field is required.
`currentValue` string	CurrentValue is the current field value
`proposedValue` string	ProposedValue is the proposed value of the field to fix an issue.

File

File references a file containing a resource

Cache Configuration

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

Porch supports two caching mechanisms for storing package metadata. Choose based on your deployment scale and infrastructure.

Cache Types

CR Cache (Default)

Uses Custom Resources for metadata tracking while package content is served through Porch’s aggregated API server. Suitable for development and smaller deployments.

Characteristics:

No external database required
Metadata stored in Kubernetes etcd via Custom Resources
Package content served through aggregated API server
Automatic backup with cluster backups
Simple operational model

Best For:

Cache Design

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

Cache Interface

The Package Cache provides a unified interface that abstracts the underlying storage mechanism. Both the CR Cache and DB Cache implementations conform to this common interface, allowing the CaDEngine to work with either implementation without knowing which is in use.

Repository Operations:

Open repository connections from Repository CR specifications
Close repositories and clean up resources
Retrieve list of all open repositories
Get specific repository by key
Update repository metadata
Check repository connectivity

Repository Interface Delegation:

Caching Behavior

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

Overview

The Package Cache optimizes performance by storing repository data in memory (CR Cache) or database (DB Cache) to avoid redundant Git operations. The caching system uses lazy loading, version-based refresh, and concurrency control to balance performance with data freshness.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Caching System │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────┐ │
│ │ Cache │ │ Version │ │ Git │ │
│ │ Population │ ───> │ Tracking │ ───> │ Repo │ │
│ │ │ │ │ │ │ │
│ │ • Lazy Load │ │ • Compare │ │ │ │
│ │ • Refresh │ │ • Refresh │ │ │ │
│ └──────────────┘ └──────────────┘ └──────┘ │
│ │ │ │
│ └──────────┬───────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Cache Structure │ │
│ │ │ │
│ │ • Maps │ │
│ │ • Mutex │ │
│ │ • Consistency │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Cache Population

The cache uses lazy loading and version-based refresh to minimize Git operations. While the cache provides the data storage and access interfaces, the Repository Controller orchestrates background sync operations that populate and refresh the cache on configurable schedules.

Catalog Deployment

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

This guide covers deploying Porch in production environments using the Nephio catalog.

Configuration Planning

Before deploying Porch, determine which features you need.

Cache Mode Selection

Choose your cache backend based on deployment scale and requirements:

CR Cache (default): Development and small deployments (<100 repositories)
DB Cache: Production deployments requiring scale and reliability

Important

If using DB Cache, you must configure database settings for both Porch Server and Repository Controller before deployment. See Cache Configuration for complete setup instructions including database initialization.

Optional Pre-deployment Configuration

These optional features must be configured before deployment if you need them:

Cert Manager Webhooks

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

Porch includes validating webhooks that require TLS certificates. By default, Porch generates self-signed certificates, but you can configure it to use cert-manager for automatic certificate management.

Porch Webhooks

Porch uses two validating webhooks:

PackageRevision Deletion Webhook - Validates PackageRevision deletion requests
Repository Validation Webhook - Validates Repository creation and updates

Using the Catalog Package

The Nephio catalog provides a ready-to-use package for Porch with cert-manager integration:

# Register the catalog repository (if not already done)
porchctl repo register \
 --namespace default \
 https://github.com/nephio-project/catalog.git \
 --name=catalog

# Clone the cert-manager webhook package
porchctl rpkg clone \
 catalog.nephio.optional.porch-cert-manager-webhook.main \
 porch-cert-manager \
 --repository=deployment-repo \
 --namespace=default

This package includes:

CRD Reference

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

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:

Design

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

REST Storage Interface

See Functionality for detailed CRUD operations and storage implementations.

The Porch API Server implements Kubernetes’ REST storage interface to provide custom storage backends for Porch resources. Unlike standard Kubernetes resources that store data in etcd, Porch resources delegate to the Engine which manages package data in Git repositories through the Cache.

Storage interface characteristics:

Implements standard Kubernetes storage.Interface
Provides CRUD operations (Create, Get, List, Update, Delete)
Supports Watch for real-time change notifications
Delegates all operations to CaD Engine
No direct etcd storage - packages stored in Git

Storage implementations:

Design Decisions

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

Overview

This page explains the key architectural decisions that shaped the Repository Controller, focusing on the “why” rather than the “what.” Each decision represents a deliberate trade-off made to balance competing concerns like performance, reliability, and operational simplicity.

These decisions address fundamental challenges in distributed systems: how to detect failures quickly without wasting resources, how to handle errors intelligently, and how to provide clear operational visibility. Understanding the rationale helps when troubleshooting issues or considering configuration changes.

Engine Design

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

CaD Engine Architecture

The Engine follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────┐
│ CaDEngine Interface │ ← Public API
├─────────────────────────────────────────┤
│ cadEngine Implementation │ ← Orchestration Logic
├─────────────────────────────────────────┤
│ ┌──────────┬──────────┬─────────────┐ │
│ │ Cache │ Task │ Watcher │ │ ← Dependencies
│ │ │ Handler │ Manager │ │
│ └──────────┴──────────┴─────────────┘ │
└─────────────────────────────────────────┘

Key architectural patterns:

Dependency Injection via Functional Options

The engine is constructed using a functional options pattern that allows flexible configuration of dependencies:

Error Handling

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

Overview

When repository operations fail, the controller uses intelligent retry logic based on error type. Different errors require different retry strategies - transient network issues retry quickly, while authentication problems that need manual intervention retry less frequently to avoid wasting resources.

For how errors affect sync scheduling behavior, see Sync Behavior During Errors.

Error-Specific Retry Intervals

The controller analyzes error messages to determine appropriate retry timing:

Error Type	Retry Interval	Error Patterns	Rationale
Network Issues	30 seconds	“no such host”, “connection refused”	Often transient, retry quickly
Authentication	10 minutes	“authentication required”, “permission denied”	Needs manual fix, avoid spam
Git Repo/Branch	2 minutes	“not found”, “invalid”, “branch”	May be transient (repo creation)
Timeouts	1 minute	“timeout”, “deadline exceeded”	Network congestion, moderate retry
TLS/SSL Issues	5 minutes	“certificate”, “tls”, “ssl”	Configuration issues, less frequent
Rate Limiting	5 minutes	“rate limit”, “too many requests”	Need to back off from API
Default	30 seconds	All other errors	Configurable fallback

Recovery Behavior

When a repository enters an error state, the controller adjusts its behavior to focus on recovery:

Function Runner Design

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

Architectural Context

The Function Runner is one of several function execution mechanisms in Porch. The Task Handler uses a Function Runtime interface that can be implemented by:

Task Handler (in Porch)
 ↓
 Function Runtime
 ↓
 ┌─────┴─────┬──────────┐
 ↓ ↓ ↓
Builtin gRPC Multi
Runtime Runtime Runtime
 ↓ ↓ ↓
In-Process Function Chains
Go Code Runner Runtimes
 (External)
 ↓
 ┌─────────┴─────────┬──────────┐
 ↓ ↓ ↓
 Pod Executable Multi
 Evaluator Evaluator Evaluator
 ↓ ↓ ↓
 Function Cached Fallback
 Pods Binaries Chain

Function Runtime implementations:

Installing Porch

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

Deploying Porch on a cluster

Create a new directory for the kpt package and navigate into it:

mkdir porch-1.5.9 && cd porch-1.5.9

Download the latest Porch kpt package blueprint:

curl -LO "https://github.com/nephio-project/porch/releases/download/v1.5.9/porch_blueprint.tar.gz"

Extract the Porch kpt package contents:

tar -xzf porch_blueprint.tar.gz

Initialize and apply the Porch kpt package:

kpt live init && kpt live apply

Verify Installation

Check that Porch components are running:

kubectl get all -n porch-system

A healthy Porch installation should show:

NAME READY STATUS RESTARTS AGE
pod/function-runner-567ddc76d-7k8sj 1/1 Running 0 4m3s
pod/function-runner-567ddc76d-x75lv 1/1 Running 0 4m3s
pod/porch-controllers-d8dfccb4-8lc6j 1/1 Running 0 4m3s
pod/porch-server-7dc5d7cd4f-smhf5 1/1 Running 0 4m3s

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/api ClusterIP 10.96.108.221 <none> 443/TCP,8443/TCP 4m3s
service/function-runner ClusterIP 10.96.237.108 <none> 9445/TCP 4m3s

NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/function-runner 2/2 2 2 4m3s
deployment.apps/porch-controllers 1/1 1 1 4m3s
deployment.apps/porch-server 1/1 1 1 4m3s

NAME DESIRED CURRENT READY AGE
replicaset.apps/function-runner-567ddc76d 2 2 2 4m3s
replicaset.apps/porch-controllers-d8dfccb4 1 1 1 4m3s
replicaset.apps/porch-server-7dc5d7cd4f 1 1 1 4m3s

Verify the Porch API is accessible:

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

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:

Pod Lifecycle Management

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

Overview

Pod lifecycle management orchestrates the complete lifecycle of function execution pods from creation through caching, reuse, and eventual garbage collection. The system maintains a pool of ready-to-use pods for frequently executed functions while automatically cleaning up unused pods based on time-to-live policies.

The architecture consists of two primary components:

Pod Cache Manager - Central coordinator running in a single goroutine that manages the pod cache, handles evaluation requests, processes pod readiness notifications, and performs periodic garbage collection. Uses channels for all communication to eliminate mutex synchronization.

Pod Templates

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

The Function Runner supports customizing the pod specifications used for KRM function evaluation through ConfigMap-based templates. This allows you to configure resource limits, security contexts, node selectors, tolerations, and other pod-level settings for function execution pods.

Overview

By default, the Function Runner uses an inline pod template with sensible defaults. For advanced use cases requiring customization, you can provide a ConfigMap containing custom pod and service templates. The Function Runner will use these templates when creating function evaluator pods.

Porch Controllers

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

The Porch controllers manage Repository synchronization, PackageVariants, and PackageVariantSets.

Enabling Controllers

Command Line Arguments

The controllers support these command line arguments:

args:
- --reconcilers=repositories,packagevariants,packagevariantsets # Comma-separated list
# OR use --reconcilers=* to enable all controllers

Repository Controller Configuration

The Repository Controller supports these additional flags:

args:
- --reconcilers=repositories
- --repositories.max-concurrent-reconciles=100
- --repositories.max-concurrent-syncs=50
- --repositories.health-check-frequency=5m
- --repositories.full-sync-frequency=1h
- --repositories.cache-type=CR # or DB

Configuration Parameters:

Parameter	Default	Description
`max-concurrent-reconciles`	100	Parallel reconcile loops
`max-concurrent-syncs`	50	Parallel sync operations
`health-check-frequency`	5m	Lightweight connectivity checks
`full-sync-frequency`	1h	Complete repository sync
`cache-type`	CR	Cache implementation (CR or DB) - see Cache Configuration

Cache Type:

Repositories

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

What is a Repository in Porch?

A Repository is a Kubernetes resource that connects Porch to a Git repository where kpt packages are stored. When you register a repository with Porch, you’re creating a Repository resource that tells Porch:

Where the storage backend is located (Git URL)
- including a particular branch within the repository - the deployment branch
How to authenticate (via references to a Kubernetes Secret containing the credentials)
Whether it’s a deployment repository (packages ready for deployment)
How often to sync/refresh the package revision cache

Repositories can be accessed using the short name repo for convenience (e.g., kubectl get repo).

Validation & Business Rules

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

Overview

The Engine enforces validation and business rules to ensure package revisions are created and modified correctly. These rules prevent invalid operations, enforce naming constraints, and maintain referential integrity across packages and revisions.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Validation & Business Rules │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Pre-Operation │ │ Constraint │ │
│ │ Validation │ ───> │ Enforcement │ │
│ │ │ │ │ │
│ │ • Lifecycle │ │ • Uniqueness │ │
│ │ • Tasks │ │ • Path Overlap │ │
│ │ • Resources │ │ • Clone Rules │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Optimistic │ │
│ │ Locking │ │
│ │ │ │
│ │ • Resource Ver │ │
│ │ • Conflict Det │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Lifecycle Validation

The Engine validates lifecycle values during package revision creation and updates:

Creating Package Revisions

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

Tutorial Overview

You will learn how to:

Initialize a new package revision
Pull the package revision locally
Modify the package revision contents
Push changes back to Porch
Propose the package revision for review
Approve or reject the package revision

Note

The tutorial assumes a porch repository is initialized with the “porch-test” name. We recommended to use this for simpler copy-pasting of commands otherwise replace any “porch-test” value with your repository’s name in the below commands.

Step 1: Initialize Your First Package Revision

Create a new package revision in Porch using the init command:

Custom Resource Cache

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

Overview

The Custom Resource (CR) Cache is the default cache implementation in Porch. It stores package metadata using a Kubernetes Custom Resources while keeping repository data in memory. This implementation is designed for standard Porch deployments where Kubernetes etcd provides sufficient storage and performance.

Key characteristics:

Default implementation: Used when no cache type is explicitly configured
Hybrid storage: In-memory repository cache + CR-based metadata storage
RDBMS-independent: No RDBMS (such as Posgres) required, leverages the Kubernetes API, etcd, and Git for persistence
Suitable for: Small to medium deployments with moderate package counts
No external dependencies: Only requires a Kubernetes cluster
Git interaction: Interacts with Git at every stage of package revision lifecycle for presistence

Implementation Details

Storage Architecture

The CR Cache uses a two-tier storage model:

Draft-Commit Workflow Orchestration

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

Overview

The Engine orchestrates a draft-commit workflow for all package revision modifications. This pattern ensures atomicity - either all changes succeed and are persisted, or none are. The workflow uses mutable drafts for changes and immutable package revisions for storage.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Draft-Commit Workflow Orchestration │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Draft Phase │ │ Commit Phase │ │
│ │ │ ───> │ │ │
│ │ • Open Draft │ │ • Close Draft │ │
│ │ • Apply Changes │ │ • Persist │ │
│ │ • Validate │ │ • Immutable │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Rollback │ │
│ │ Mechanism │ │
│ │ │ │
│ │• Trigger On Error│ │
│ │• Does Cleanup │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Draft-Commit Pattern

The Engine uses a two-phase workflow for all package revision modifications:

Functionality

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

Overview

The Porch API Server provides the Kubernetes API interface for Porch resources. It implements custom REST storage backends that delegate to the Engine, enforces validation and admission policies through strategies, and manages real-time watch streams for clients.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ API Server Functionality │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ REST Storage │ │ Strategies │ │
│ │ │ ───> │ │ │
│ │ • CRUD Ops │ │ • Validation │ │
│ │ • Watch Streams │ │ • Admission │ │
│ │ • Engine Deleg │ │ • Table Conv │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Background │ │
│ │ Operations │ │
│ │ │ │
│ │ • Cleanup │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

REST Storage Implementation

See Design for the design rationale behind custom REST storage.

Getting Package Revisions

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

Basic Operations

These operations cover the fundamental commands for viewing and inspecting package revisions in Porch.

Getting All Package Revisions

Get all package revisions across all repositories in a namespace:

porchctl rpkg get --namespace default

This command queries Porch for all PackageRevisions in the specified namespace and displays a summary table with key information. It shows PackageRevisions from all registered repositories in that namespace.

Note

porchctl rpkg list is an alias for porchctl rpkg get and can be used interchangeably:

Image and Registry Management

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

Overview

The Function Runner manages container image metadata and registry authentication to optimize pod creation and support private registries. The system caches image metadata (digest and entrypoint) to avoid repeated registry calls, handles authentication for private registries using Docker config format, and supports TLS configuration for secure registry connections.

High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│ Image and Registry Management │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Image │ │ Registry │ │
│ │ Metadata │ ───> │ Authentication │ │
│ │ Caching │ │ │ │
│ │ │ │ • Default │ │
│ │ • Digest │ │ • Custom Auth │ │
│ │ • Entrypoint │ │ • TLS Config │ │
│ │ • In-Memory │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌───────────────────┐ │
│ │ Secret │ │
│ │ Management │ │
│ │ │ │
│ │ • Creation │ │
│ │ • Synchronization│ │
│ │ • Pod Injection │ │
│ └───────────────────┘ │
└──────────────────────────────────────────────────────────┘

Image Metadata Caching

The pod manager caches image metadata to avoid repeated registry API calls during pod creation.

Jaeger Tracing

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

Jaeger tracing provides distributed tracing capabilities for the Porch Server, allowing you to monitor and debug package operations. This is particularly useful for development and troubleshooting.

Note

Jaeger tracing is currently only supported for the Porch Server component. Function Runner and Porch Controllers do not support tracing.

Overview

Porch Server supports OpenTelemetry tracing that can be exported to Jaeger for visualization. When enabled, Porch Server will generate traces for:

Package operations (create, update, delete)
Git repository interactions
Function execution requests
API requests and responses

Deployment Setup

Deploy Jaeger to Kubernetes

Porch includes a ready-to-use Jaeger deployment:

Lifecycle Management

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

Overview

The Engine enforces a strict lifecycle state machine for package revisions that governs their mutability, visibility, and progression from draft to published state. The lifecycle system ensures that package revisions follow a controlled workflow from creation through approval to deployment, with appropriate constraints at each stage.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Lifecycle Management System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ State Machine │ │ Validation │ │
│ │ │ ───> │ & Enforcement │ │
│ │ • Draft │ │ │ │
│ │ • Proposed │ │ • Creation │ │
│ │ • Published │ │ • Transition │ │
│ │ • Deletion │ │ • Mutation │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ State-Based │ │
│ │ Constraints │ │
│ │ │ │
│ │ • Mutability │ │
│ │ • Operations │ │
│ │ • Audit Trail │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Lifecycle State Machine

The lifecycle state machine defines four states that a package revision can be in:

Local Development Environment

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

This guide provides instructions for setting up a local development environment using Kind (Kubernetes in Docker) for developing, testing, and exploring Porch.

Prerequisites

Docker - For running containers and Kind cluster
kubectl - Kubernetes command-line tool
kind - Local Kubernetes clusters using Docker

Setup

1. Create Kind Cluster

From the Porch repository root directory:

./scripts/setup-dev-env.sh

This script:

Creates a Kind cluster named porch-test
Installs MetalLB load balancer
Deploys Gitea Git server
Generates PKI resources for testing
Builds the porchctl CLI binary

2. Deploy Porch

Choose your cache backend:

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:

Package Revisions

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

What is a Package Revision?

A package revision is the actual working unit in Porch. While users may often refer to “working with a package”, they are actually working with a specific revision of that package.

Think of it like Git commits:

A Git repository contains a project
Each commit is a specific version of that project
You work with commits, not the abstract “project”

Similarly in Porch:

A Repository contains kpt packages
Each package revision is a specific version of a kpt package
You work with package revisions, not the abstract “package”

Published Package Revision Numbering

Package revisions use simple integer sequence versioning (1, 2, 3, etc.):

Registering Repositories

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

Registering a repository connects Porch to your Git storage backend, allowing it to discover and manage packages. You can register repositories with various authentication methods and configuration options.

Register a Git Repository

porchctl repo register https://github.com/example/porch-test.git \
 --namespace default \
 --name=porch-test \
 --description="Blueprint packages" \
 --branch=main

This command registers the Git repository with Porch, creates a Repository resource in Kubernetes and begins synchronizing packages from the repository.

Status Management

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

Overview

The Repository controller maintains detailed status information to track sync operations, detect changes, and provide observability. The status includes both standard Kubernetes conditions and custom fields specific to repository synchronization.

Status Fields

Repository Information

The packageCount field shows how many package revisions were discovered during the last sync.

Git Commit Tracking

For git repositories, the gitCommitHash field contains the commit hash of the configured branch, enabling GitOps workflows to track which version is currently synced.

Uninstalling Porch

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

Uninstalling Porch Server

Navigate to the directory where you installed Porch:

cd porch-1.5.9

Remove Porch components using kpt:

kpt live destroy

This will delete all Porch resources from your cluster, including:

Porch server deployment
Function runner deployment
Porch controllers deployment
Services, ConfigMaps, and Secrets
Custom Resource Definitions (CRDs)

Warning

Destroying Porch will not delete your Git repositories or the packages stored in them. However, PackageRevision and Repository resources in your cluster will be removed.

Verify Uninstallation

Check that Porch components are removed:

Component Interactions

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

Overview

The Repository Controller operates within the Porch ecosystem by watching Repository custom resources and interacting with the cache layer to keep package metadata synchronized. This page describes how the controller integrates with other Porch components.

Architecture

┌────────────────────────────────────────────────────────┐
│ Repository Controller │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ Reconcile Loop │ │
│ │ │ │
│ │ • Watch Repository CRs │ │
│ │ • Sync Decision Logic │ │
│ │ • Async Workers │ │
│ │ • Status Updates │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Cache Interface │ │
│ │ │ │
│ │ • OpenRepository│ │
│ │ • Refresh │ │
│ │ • List Packages │ │
│ └──────────────────┘ │
└────────────────────────────────────────────────────────┘
 ↓
 Kubernetes API
 ↓
 Repository CRs
 ↓
 Cache Layer
 (CR/DB Cache)

Kubernetes API Interactions

The controller watches Repository custom resources using standard Kubernetes controller patterns. When repositories are created, updated, or deleted, the controller receives events and reconciles the desired state with actual state.

Copying Package Revisions

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

Tutorial Overview

You will learn how to:

Find a PackageRevision to copy
Copy a PackageRevision to create a new revision
Modify the copied PackageRevision
Propose and approve the new revision

Note

The tutorial assumes a porch repository is initialized with the “porch-test” name. We recommended to use this for simpler copy pasting of commands otherwise replace any “porch-test” value with your repository’s name in the below commands.

Key Concepts

Copy: Creates a new independent PackageRevision within the same repository
Source PackageRevision: The original PackageRevision being copied
Target PackageRevision: The new PackageRevision created by the copy operation
Workspace: Must be unique within the package for the target
Same-repository operation: Copy only works within a single repository
Immutability: Published PackageRevisions cannot be modified, only copied
Clone vs Copy: Use clone for cross-repository operations, copy for same-repository versions

Understanding Copy Operations

Copying creates a new PackageRevision based on an existing one within the same repository. The copied PackageRevision is completely independent with no upstream link to the source.

Database Cache

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

Overview

The Database (DB) Cache is an alternative cache implementation in Porch designed for larger deployments. It stores both package metadata and repository data in a PostgreSQL database rather than in memory or Kubernetes Custom Resources. This implementation provides better scalability and persistence characteristics for production environments with high package counts.

Key characteristics:

Alternative implementation: Used when explicitly configured with database connection details
Database-backed storage: All repository, package, and package revision data stored in PostgreSQL
External dependency: Requires PostgreSQL database instance
Suitable for: Large deployments with thousands of packages and package revisions
Better persistence: Survives Porch server restarts without re-fetching from Git
Git interaction: By default, interacts with Git only during approval/publish and sync operations. Configurable with --db-push-drafts-to-git flag to push drafts

Implementation Details

Storage Architecture

The DB Cache uses a database-centric storage model:

Engine Interactions

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

Overall Interaction Overview

Cache Integration

The Engine relies heavily on the Package Cache as its primary interface to repositories:

Opening Repositories

All repository access goes through the cache:

Engine
 ↓
OpenRepository(repositorySpec)
 ↓
Package Cache
 ↓
Repository Adapter (Git)

Process:

Engine receives a Repository CR specification
Calls cache.OpenRepository(ctx, repositorySpec)
Cache returns a Repository interface implementation
Engine uses the repository abstraction for all operations

Benefits of cache-mediated access:

Function Runner Interactions

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

Overview

The Function Runner is a separate gRPC service that interacts with multiple systems: the Task Handler (via gRPC), Kubernetes API (for pod management), container registries (for image metadata), and wrapper servers (for function execution). It operates independently from the Porch server, enabling isolated function execution.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Function Runner Service │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────┐ │
│ │ Task Handler │ ───> │ gRPC │ ───> │ Eval │ │
│ │ (in Porch) │ │ Server │ │uators│ │
│ └──────────────┘ └──────────────┘ └──────┘ │
│ ↑ │ │ │
│ │ ↓ ↓ │
│ │ ┌──────────────┐ ┌──────┐ │
│ └──────────────│ Kubernetes │ │Image │ │
│ │ API │ │Cache │ │
│ └──────────────┘ └──────┘ │
│ │ │ │
│ ↓ ↓ │
│ ┌──────────────┐ ┌─────────┐ │
│ │ Function Pods│ │Registry │ │
│ │ + Services │ │ APIs │ │
│ └──────────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────┘

Task Handler Integration

The Function Runner integrates with the Task Handler through the gRPC Runtime:

Interactions

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

Overview

The Porch API Server acts as the integration point between Kubernetes clients and Porch’s internal components. It translates Kubernetes API requests into Engine operations and manages watch streams for real-time event delivery.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Porch API Server │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────┐ │
│ │ Clients │ ───> │ REST │ ───> │Engine│ │
│ │ (kubectl, │ │ Storage │ │ │ │
│ │ kpt, etc) │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────┘ │
│ ↑ │ │ │
│ │ ↓ ↓ │
│ │ ┌──────────────┐ ┌──────┐ │
│ └──────────────│ Watcher │ │Cache │ │
│ │ Manager │ │ │ │
│ └──────────────┘ └──────┘ │
└─────────────────────────────────────────────────────────┘

Engine Integration

The API Server delegates all package operations to the CaD Engine:

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.

OpenTelemetry Configuration

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

Overview

Porch supports OpenTelemetry observability through the autoexport package, which provides automatic configuration of metrics and traces exporters via environment variables. This enables seamless integration with various observability backends including OTLP collectors, Prometheus, and Jaeger.

All Porch components (porch-server, porch-controllers, function-runner, and wrapper-server) support OpenTelemetry configuration through standardized environment variables as defined by the OpenTelemetry specification.

Note

Current Implementation Status: Porch currently implements metrics and traces export. Logs export is not supported.

Traces Configuration

OTLP Trace Export

Export traces to an OpenTelemetry Protocol (OTLP) collector using either HTTP or gRPC protocols.

Private Registries

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

Note

KPT functions and KRM functions are synonymous terms referring to the same containerized functions.

Configure the Function Runner to access private container registries for KRM functions.

Use Cases

Private registries are commonly used for:

Enterprise environments - Internal Harbor or JFrog registries
Cloud providers - GitHub Container Registry (GHCR), AWS ECR, Azure ACR
Custom functions - Organization-specific KRM functions

Default Public Registries

By default, Function Runner uses public registries:

ghcr.io/kptdev/krm-functions-catalog - GitHub Container Registry for KRM functions
Other public registries as configured

Private Registry Authentication

To use private container registries for KRM functions, configure authentication in the Function Runner.

Repositories Basic Usage

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

Basic Operations

These operations cover the fundamental commands for viewing and managing registered repositories.

List Registered Repositories

View all repositories registered with Porch:

porchctl repo get --namespace default

This command queries Porch for all registered repositories in the specified namespace, displays the repository type, content type, sync schedule, and status and shows the repository address.

Note

porchctl repo list is an alias for porchctl repo get and can be used interchangeably:

Task Coordination

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

Overview

The Engine coordinates task execution by delegating to the Task Handler. Tasks represent operations that transform package content (init, clone, edit, upgrade, render). The Engine orchestrates when and how tasks are executed, while the Task Handler implements the actual transformations.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Task Coordination System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Engine │ │ Task Handler │ │
│ │ Orchestration │ ───> │ Execution │ │
│ │ │ │ │ │
│ │ • When to Run │ │ • Init │ │
│ │ • Draft Mgmt │ │ • Clone │ │
│ │ • Error Handle │ │ • Edit │ │
│ └──────────────────┘ │ • Upgrade │ │
│ │ │ • Render │ │
│ │ └──────────────────┘ │
│ ↓ │ │
│ ┌──────────────────┐ ↓ │
│ │ Function │ ┌──────────────────┐ │
│ │ Runtime │ <─── │ Builtin Funcs │ │
│ │ │ │ │ │
│ │ • gRPC │ │ • set-namespace │ │
│ │ • Builtin │ │ • ensure-context│ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Task Handler Integration

The Engine integrates with the Task Handler through three main operations:

Workspace

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

Important

Workspace is merely a unique ID for a package revision!

The content of this page will shortly be updated to reflect this fact and moved into the PackageRevision page!

What is a Workspace?

A workspace is a named, isolated environment for working on a package revision in Porch. Each Draft or Proposed package revision has a unique workspace name that identifies the specific set of changes being made to a package.

Cloning Package Revisions

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

Tutorial Overview

You will learn how to:

Find a PackageRevision to clone
Clone a PackageRevision to a different repository
Modify the cloned PackageRevision
Propose and approve the new revision

Note

Please note the tutorial assumes repositories are initialized with the “blueprints” and “deployments” names. We recommended to use these for simpler copy pasting of commands otherwise replace these values with your repository names in the below commands.

Understanding Clone Operations

Cloning creates a new PackageRevision based on an existing one and works across different repositories. The cloned PackageRevision maintains an upstream reference to its source, allowing it to receive updates.

Package Revision Lifecycle

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

What is Package Revision Lifecycle?

The lifecycle of a package revision refers to its current stage in Porch’s orchestration process. A package revision moves through different stages from creation to publication, with approval gates between stages.

Lifecycle Stages

Draft

A package revision in Draft stage is work in progress. It is being actively edited and not ready for deployment. If it is being cached by the CR cache, its contents are stored in a temporary branch in the Git repository (e.g., drafts/package-name/workspace). If it is being cached by the DB cache, its contents are only stored in the database and do not appear in Git at all.

Synchronizing Repositories

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

Repository Synchronization

Porch periodically synchronizes with registered repositories to discover new packages and updates. You can also trigger manual synchronization when you need immediate updates.

Note

Sync Schedule Format: Cron expressions follow the format minute hour day month weekday. For example, */10 * * * * means “every 10 minutes”.

Trigger Manual Sync

Force an immediate synchronization of a repository:

porchctl repo sync porch-test --namespace default

This command schedules a one-time sync (minimum 1-minute delay), updates packages from the repository. This sync is independent of the periodic sync schedule.

API Reference Generation

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

Porch uses crd-ref-docs to generate API reference documentation from Go source code.

Note

Only regenerate documentation when API types in api/porch/v1alpha1 are modified.

Prerequisites

Go 1.25+ installed
Access to the Porch repository

Generate Documentation

From the docs/ directory:

make generate-api-docs-markdown

This runs scripts/generate-api-reference-md.sh which:

Installs crd-ref-docs (v2.0.0) if not present
Generates API reference from api/porch/v1alpha1
Outputs to docs/content/en/docs/7_cli_api/api-ref.md

Configuration

Config: docs/crd-ref-docs/config.yaml

Excludes OCI types (not supported)
Excludes standard Kubernetes metadata fields
Uses Kubernetes v1.34 for API links

Templates: docs/crd-ref-docs/markdown-templates/

Cache Interactions

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

Overview

The Package Cache acts as an intermediary layer that coordinates between the CaDEngine, Repository Adapters, and external Git repositories. It provides caching, synchronization, and change notification services while maintaining a clean separation of concerns.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Package Cache Layer │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────┐ │
│ │ CaDEngine │ ───> │ Cache │ ───> │ Repo │ │
│ │ Requests │ │ Operations │ │Adapt │ │
│ │ │ │ │ │ ers │ │
│ └──────────────┘ └──────────────┘ └──────┘ │
│ ↑ │ │ │
│ │ ↓ ↓ │
│ │ ┌──────────────┐ ┌──────┐ │
│ └──────────────│ Watcher │ │ Git │ │
│ │ Notifier │ │Repos │ │
│ └──────────────┘ └──────┘ │
└─────────────────────────────────────────────────────────┘

Repository Adapter Integration

The cache wraps repository adapters to provide caching and synchronization services:

Unregistering Repositories

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

Unregistering Repositories

When you no longer need Porch to manage packages from a repository, you can unregister it. This removes Porch’s connection to the repository without affecting the underlying Git storage.

Unregister a Repository

Remove a repository from Porch:

porchctl repo unregister porch-test --namespace default

This command removes the Repository resource from Kubernetes, it stops synchronizing packages from the repository, removes Porch’s cached metadata for the repository but does not delete the underlying Git repository or its contents.

Upgrading Package Revisions

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

The package upgrade feature in Porch is a powerful mechanism for keeping deployed packages (downstream) up-to-date with their source blueprints (upstream). This guide walks through the entire workflow, from creating packages to performing an upgrade, with a special focus on the different upgrade scenarios and merge strategies.

For detailed command reference, see the porchctl CLI guide.

Key Concepts

To understand the upgrade process, it’s essential to be familiar with the three states of a package during a merge operation:

Upstream & Downstream

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

What are Upstream and Downstream Packages?

Upstream and downstream describe source-to-derivation relationship between packages and package revisions in Porch. This relationship is fundamental to package reuse, customization, upgrade control, and lifecycle management.

Upstream package: The source or template package that provides the base content
Downstream package: A derived package created by cloning or copying from an upstream package

This relationship enables package reuse across teams and environments, centralized maintenance of template packages, tracking of package lineage and updates, and automated propagation of upstream changes to downstream packages.

Deleting Package Revisions

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

Tutorial Overview

You will learn how to:

Delete Draft and Proposed PackageRevisions directly
Propose Published PackageRevisions for deletion
Approve or reject deletion proposals
Understand the deletion workflow and safety mechanisms

Note

This tutorial assumes a porch repository is initialized with the “porch-test” name. Replace any “porch-test” value with your repository’s name in the commands below.

Understanding PackageRevision Deletion

PackageRevision deletion in Porch follows different workflows depending on the lifecycle state:

Direct Deletion:

KRM Functions

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

What are Functions in Porch?

Functions in Porch are KRM (Kubernetes Resource Model) functions - containerized programs that transform or validate Kubernetes resource manifests within a package’s files. Functions are declared in a package’s Kptfile and executed by Porch when rendering the package.

Functions enable:

Automated resource generation and modification
Policy enforcement and validation
Configuration customization without manual editing
Repeatable, auditable transformations

For details on how to declare and configure functions in the Kptfile pipeline, see the kpt functions documentation.

Package Variants and Package Variant Sets

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

What are PackageVariants?

A PackageVariant is a Kubernetes custom resource that automates the creation and maintenance of downstream package revisions based on an upstream package. It establishes a relationship between an upstream (source) package and one or more downstream (target) packages, automatically keeping them synchronized.

PackageVariants enable:

Automatic cloning of package revisions from upstream to downstream repositories
Continuous tracking of package revisions of the upstream package
Automated creation of new downstream revisions when a new revision of the upstream is published
Customization of downstream package revisions through injectors, functions, and package context

How PackageVariants Work

Porch’s PackageVariant controller watches for changes to: