Porch Concepts on Porch Documentation

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:

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

Repository Types

Porch supports two storage backends:

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

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.

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
Automated propagation of upstream changes to downstream packages

How the Relationship Works

When you create a downstream package revision from an upstream package revision, Porch establishes and tracks this relationship. The downstream package revision maintains a record of its upstream source, including the exact version (Git commit) it was derived from.

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: