Packages

Understanding packages in Porch: the relationship between kpt packages and Porch’s PackageRevision API.

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:

PackageRevision: A Kubernetes resource containing the kpt package metadata (name, repository, revision number, lifecycle stage, workspace, task list)
PackageRevisionResources: A companion resource containing the actual kpt package contents, represented as a key-value map of file names to YAML file contents

These resources expose kpt packages, stored in Git repositories, as Kubernetes-native objects.

The Relationship: kpt Packages and Porch

kpt packages are the underlying storage format:

A directory containing a Kptfile and one or more KRM (Kubernetes Resource Model) YAML files
May have subdirectories containing independent or dependent kpt subpackages
Are stored in Git repositories (branches, tags, commits) by Porch
Follow the kpt package specification

Porch packages are the API layer:

PackageRevision and PackageRevisionResources resources that expose kpt packages through the Kubernetes API
Enable declarative package revision lifecycle management (Draft → Proposed → Published)
Support operations like init, clone, edit, upgrade through Kubernetes-style interactions
Automatically sync changes between the API resources and the underlying Git storage

Warning

It is NOT recommended to directly edit downstream API resources on Git.

Example: Creating and Viewing a Package

When you create a “package” with porchctl:

porchctl rpkg init my-package --repository=blueprints --workspace=add-ai-feature

Porch creates:

A PackageRevision resource with metadata (name, repository, workspace, lifecycle=Draft)
A PackageRevisionResources resource with initial content (Kptfile + any starter resources)
A Git branch, containing the kpt package files, in the blueprints repository (if Porch is configured with the CR cache)

When you get “packages”/package revisions in Porch:

porchctl rpkg get

You see PackageRevision resources, not raw Git files. Each row represents a PackageRevision with its metadata.

When you pull a “package” contents in Porch:

porchctl rpkg pull blueprints.my-package.add-ai-feature ./local-dir

Porch fetches the PackageRevisionResources content and writes it as kpt package files in the local file system.

Key Distinctions

Storage layer: kpt packages in Git (Kptfile + YAML files)
API layer: PackageRevision and PackageRevisionResources in Kubernetes
User interaction: You work with PackageRevision and PackageRevisionResources resources using porchctl, kubectl, or Porch’s Kubernetes API
Compatibility: The underlying kpt packages remain standard and, when pulled, can be used locally with the kpt CLI

This separation allows Porch to add orchestration capabilities (lifecycle management, approval workflows, automation) on top of standard kpt packages, without vendor lock-in.