Functionality on Porch Documentation

Source Execution

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

Overview

Source execution handles one-time package creation. When a user creates a PackageRevision with spec.source set, the controller executes the specified operation to produce initial content in the shared cache. This phase is idempotent: the guard is status.creationSource; if it is already set, source execution is skipped entirely.

After any source execution, the controller creates a draft in the cache, writes the resources, closes the draft (committing to Git), and requeues to trigger rendering.

Rendering

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

Overview

Rendering runs the KRM function pipeline defined in the package’s Kptfile. The controller reads resources from the shared cache, invokes kpt render through the function runner (gRPC), and writes the rendered output back to the cache.

Triggers

Two events can trigger rendering:

Content push via PRR: When a user edits PackageRevisionResources, the API Server patches the porch.kpt.dev/render-request annotation on the PackageRevision CRD. The controller’s predicate filter detects this and triggers a reconcile.
Source execution completion: After init, clone, copy, or upgrade produces initial content (including a generated or copied Kptfile), the controller immediately proceeds to render. For init with an empty Kptfile, rendering may produce no additional output.

The controller tracks the annotation value in status.observedPrrResourceVersion to avoid re-rendering the same content.

Lifecycle Management

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

Overview

The lifecycle phase compares the desired lifecycle in spec.lifecycle with the actual state in the cache. If they differ, the controller transitions the package accordingly. The spec.lifecycle field is client-owned: the controller reads it but never writes it.

Lifecycle States

State	Meaning
Draft	Package is being edited. Stored as a Git branch.
Proposed	Package is proposed for review (optional intermediate state).
Published	Package is immutable. Stored as a Git tag.
DeletionProposed	Package is marked for deletion. Required before deleting a published package.

State Transitions

 ┌─────────┐
 │ Draft │◄──────────┐
 └────┬────┘ │
 │ propose │ reject
 ▼ │
 ┌─────────────┐ │
 │ Proposed ├───────┘
 └────┬────────┘
 │ approve
 ▼
 ┌──────────────┐
 │ Published │
 └────┬─────────┘
 │ propose-delete
 ▼
 ┌──────────────────┐
 │ DeletionProposed │
 └────┬─────┬───────┘
 │ │
 approve reject
 deletion │
 │ ▼
 │ Published
 ▼
 [Deleted]

Valid transitions: