Porch Concepts on Porch Documentation

Packages

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

Warning

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.

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).

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.):

Workspace

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

Warning

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.

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.

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.

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.

Subpackages

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

What are Subpackages?

A subpackage is a kpt package nested within a parent package at a specific subdirectory. Subpackages have a Kptfile that can be used to apply specific mutations or validations to the contents of the subpackage. See the kpt package documentation for a description of dependent and independent subpackages.

What is an Independent Subpackage?

An independent subpackage maintains its own upstream source and can be independently upgraded. Unlike regular package contents and dependent subpackages that are managed as a single unit, independent subpackages retain upstream tracking information in their Kptfile, enabling them to be upgraded separately from the parent package.

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: