Creating Package Revisions

Tutorial Overview

You will learn how to:

1. Initialize a new package revision
2. Pull the package revision locally
3. Modify the package revision contents
4. Push changes back to Porch
5. Propose the package revision for review
6. Approve or reject the package revision

Step 1: Initialize Your First Package Revision

Create a new package revision in Porch using the init command:

porchctl rpkg init my-first-package \
  --namespace=default \
  --repository=porch-test \
  --workspace=v1 \
  --description="My first Porch package"

This command creates a new package named my-first-package in the porch-test repository, initializing a PackageRevision with the workspace name of v1 (this must be unique within this package). The PackageRevision starts in Draft lifecycle state.

Verify the package revision was created:

porchctl rpkg get --namespace default

You should see your package revision listed with lifecycle Draft:

NAME                             PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.my-first-package.v1   my-first-package   v1              0          false    Draft       porch-test

Step 2: Pull the Package Revision Locally

Download the package revision contents to your local filesystem:

porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace default

This command fetches all resources from the PackageRevision and saves them to the ./my-first-package directory. This includes the Kptfile and all other resources.

Explore the package revision contents:

ls -al ./my-first-package

You should see the Kptfile, which contains Package metadata and pipeline configuration, as well as the .KptRevisionMetadata file, which contains PackageRevision metadata. Additionally, you should see other YAML files, if any were created.

total 24
drwxr-x--- 2 user user 4096 Nov 24 13:27 .
drwxr-xr-x 4 user user 4096 Nov 24 13:27 ..
-rw-r--r-- 1 user user  259 Nov 24 13:27 .KptRevisionMetadata
-rw-r--r-- 1 user user  177 Nov 24 13:27 Kptfile
-rw-r--r-- 1 user user  488 Nov 24 13:27 README.md
-rw-r--r-- 1 user user  148 Nov 24 13:27 package-context.yaml

Alternatively, if you have the tree command installed on your system you can use it to view the hierarchy of the package

tree ./my-first-package/

Should return the following output:

my-first-package/
├── Kptfile
├── README.md
└── package-context.yaml

1 directory, 3 files

Step 3: Modify the Package Revision

Let’s add a simple KRM function to the pipeline. Open the Kptfile in your editor of choice:

vim ./my-first-package/Kptfile

Add a mutator function to the pipeline section so that your Kptfile looks like so:

apiVersion: kpt.dev/v1
kind: Kptfile
metadata:
  name: my-first-package
  annotations:
    config.kubernetes.io/local-config: "true"
info:
  description: My first Porch package
pipeline:
  mutators:
    - image: gcr.io/kpt-fn/set-namespace:v0.4.1
      configMap:
        namespace: production

This edit adds a set-namespace function to the pipeline. This function will set the namespace to production for all resources. The functions are not rendered until the package is “pushed” to Porch.

Add new resource. First, create a new configmap:

vim ./my-first-package/test-config.yaml

Then add the following content to this new configmap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-config
data:
  key: "value"

Save and close the file.

Step 4: Push Changes Back to Porch

Upload your modified package revision back to Porch:

porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace default

This command updates the PackageRevision in Porch and triggers rendering (executes pipeline functions). The PackageRevision remains in Draft state.

Successful output should look like a following. This describes how the KRM function was run by Porch and has updated the namespace in our new configmap.

[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1"
[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1"
  Results:
    [info]: namespace "" updated to "production", 1 value(s) changed
porch-test.my-first-package.v1 pushed

Step 5: Propose the Package Revision

Move the package revision to Proposed state for review:

porchctl rpkg propose porch-test.my-first-package.v1 --namespace default

This command changes lifecycle from Draft to Proposed and signals that the package revision is ready for review. After this, the package revision contents can no longer be modified directly. To make further changes, you must first reject the proposal back to Draft.

Verify the state change:

porchctl rpkg get porch-test.my-first-package.v1 --namespace default

The lifecycle should now show Proposed.

NAME                             PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.my-first-package.v1   my-first-package   v1              0          false    Proposed    porch-test

Step 6a: Approve the Package Revision

If the package revision looks good, approve it to publish:

porchctl rpkg approve porch-test.my-first-package.v1 --namespace default

This command changes the PackageRevision lifecycle from Proposed (revision 0) to Published (revision 1). With this, the PackageRevision becomes immutable, which means that the content cannot be changed. The command also records who approved and when. The PackageRevision is now available for cloning/deployment.

Verify the publication:

porchctl rpkg get porch-test.my-first-package.v1 --namespace default -o yaml | grep -E "lifecycle|publishedBy|publishTimestamp"

Verify the state change:

porchctl rpkg get porch-test.my-first-package.v1 --namespace default

The lifecycle should now show Published.

NAME                               PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.my-first-package.main   my-first-package   main            -1         true     Published   porch-test
porch-test.my-first-package.v1     my-first-package   v1              1          false    Published   porch-test

Step 6b: Reject the Package Revision (Alternative)

If the package revision needs more work, reject it to return to Draft:

porchctl rpkg reject porch-test.my-first-package.v1 --namespace default

This command changes the lifecycle from Proposed back to Draft, which allows further modifications. You can then make changes and re-propose.

If the package revision is rejected, the process begins again from Step 2 until the desired state is achieved.