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 Engine runtime chain (builtin, optional Function Runner exec, porch-server pod evaluator over 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 (complete replace or ?partial=true merge), the API Server writes the resulting package and 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.

Subpackage Operations

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

Overview

Subpackage operations allow an independent subpackage to be cloned into, or upgraded within, an existing Draft package revision. Unlike source execution (which runs once at package creation time and is guarded by status.creationSource), subpackage operations can be applied repeatedly to the same package revision — one operation at a time — and are guarded by status.lastSubpackageOperationHash.

The operation is specified via spec.subpackageOperation on the PackageRevision CRD.

Idempotency

Each time the controller reconciles a PackageRevision that has spec.subpackageOperation set, it computes a SHA-256 hash of the operation spec and compares it to status.lastSubpackageOperationHash. If they match, the operation has already been executed and is skipped. The hash is only written to status after the operation completes successfully, so a failure leaves the hash unset and the operation will be retried on the next reconcile.

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: