From 8d9730c7a952c7ac8ee202d41eff41ba7cee7489 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 24 Nov 2025 17:50:12 +0000 Subject: [PATCH 1/5] adding creating first package tutorial --- .../initializing-first-package.md | 343 ++++++++++++++++++ .../porch/guides/approve-workflow.drawio.svg | 4 + .../porch/guides/init-workflow.drawio.svg | 4 + .../porch/guides/propose-workflow.drawio.svg | 4 + .../porch/guides/pull-workflow.drawio.svg | 4 + .../porch/guides/push-workflow.drawio.svg | 4 + .../porch/guides/reject-workflow.drawio.svg | 4 + 7 files changed, 367 insertions(+) create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md create mode 100644 static/images/porch/guides/approve-workflow.drawio.svg create mode 100644 static/images/porch/guides/init-workflow.drawio.svg create mode 100644 static/images/porch/guides/propose-workflow.drawio.svg create mode 100644 static/images/porch/guides/pull-workflow.drawio.svg create mode 100644 static/images/porch/guides/push-workflow.drawio.svg create mode 100644 static/images/porch/guides/reject-workflow.drawio.svg diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md new file mode 100644 index 00000000..41c00433 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -0,0 +1,343 @@ +--- +title: "Creating your first package" +type: docs +weight: 3 +description: "A tutorial designed to guide a first time user's to the package creation process in Porch" +--- + +## Prerequisites + +- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}). +- **Kubectl** configured to access your cluster. + +## Tutorial Overview + +You will learn how to: + +1. Initialize a new package +2. Pull the package locally +3. Modify the package (update Kptfile) +4. Push changes back to Porch +5. Propose the package for review +6. Approve or reject the package + +--- + +## Step 1: Initialize Your First Package + +Create a new package in Porch using the `init` command: + +```bash +porchctl rpkg init my-first-package \ + --namespace=default \ + --repository=porch-test \ + --workspace=v1 \ + --description="My first Porch package" +``` + +**What this does:** + +- Creates a new package named `my-first-package` +- Places it in the `porch-test` repository +- Uses `v1` as the workspace name (must be unique) +- Starts in `Draft` lifecycle state + +![Diagram](/static/images/porch/guides/init-workflow.drawio.svg) + +**Verify the package was created:** + +```bash +porchctl rpkg get --namespace default +``` + +You should see your package listed with lifecycle `Draft`: + +```bash +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 Locally + +Download the package contents to your local filesystem: + +```bash +porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace default +``` + +**What this does:** + +- Fetches all package resources from Porch +- Saves them to the `./my-first-package` directory +- Includes the Kptfile and any other resources + +![Diagram](/static/images/porch/guides/pull-workflow.drawio.svg) + +**Explore the package:** + +```bash +ls -al ./my-first-package +``` + +You'll see: + +- The `Kptfile` - Package metadata and pipeline configuration +- Other YAML files (if any were created) + +```bash +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 + +```bash +tree ./my-first-package/ +``` + +Should return the following output on your package: + +```bash +my-first-package/ +├── Kptfile +├── README.md +└── package-context.yaml + +1 directory, 3 files +``` + +--- + +## Step 3: Modify the Package + +Let's add a simple KRM function to the pipeline. + +Open the `Kptfile` in your editor of choice: + +```bash +vim ./my-first-package/Kptfile +``` + +Add a mutator function to the pipeline section so that your `Kptfile` looks like so: + +```yaml +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 +``` + +**What this does:** + +- Adds a `set-namespace` function to the pipeline +- This function will set the namespace to `production` for all resources in the package +- Functions run automatically when the package is rendered + +**Add new resource:** + +Create a new configmap inside the package: + +```bash +vim ./my-first-package/test-config.yaml +``` + +Now add the following content to this new configmap + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: test-config +data: + Key: "Value" +``` + +**Save and close the file.** + +{{% alert title="Note" color="primary" %}} +Changes are LOCAL ONLY (Porch doesn't know about them yet) at this stage +{{% /alert %}} + +--- + +## Step 4: Push Changes Back to Porch + +Upload your modified package back to Porch: + +```bash +porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace default +``` + +**What this does:** + +- Updates the package revision in Porch +- Triggers rendering (executes pipeline functions) +- Package remains in `Draft` state + +![Diagram](/static/images/porch/guides/push-workflow.drawio.svg) + +**Successful output:** + +This describes how the KRM function was run by porch and has updated the namespace in our new configmap. + +```bash +[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 + +Move the package to `Proposed` state for review: + +```bash +porchctl rpkg propose porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes lifecycle from `Draft` to `Proposed` +- Signals the package is ready for review +- Package can still be modified if needed + +![Diagram](/static/images/porch/guides/propose-workflow.drawio.svg) + +{{% alert title="Note" color="primary" %}} +Note a state change from `Draft` to `Proposed` means that in Git the package has moved from the `draft` branch to the `proposed` branch +{{% /alert %}} + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default +``` + +The lifecycle should now show `Proposed`. + +```bash +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 + +If the package looks good, approve it to publish: + +```bash +porchctl rpkg approve porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes lifecycle from `Proposed` to `Published` +- Package becomes **immutable** (content cannot be changed) +- Records who approved and when +- Package is now available for cloning/deployment + +![Diagram](/static/images/porch/guides/approve-workflow.drawio.svg) + +**Verify publication:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default -o yaml | grep -E "lifecycle|publishedBy|publishTimestamp" +``` + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.my-first-package.v1 --namespace default +``` + +The lifecycle should now show `Published`. + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-first-package.v1 my-first-package v1 1 true Published porch-test +``` + +--- + +## Step 6b: Reject the Package (Alternative) + +If the package needs more work, reject it to return to `Draft`: + +```bash +porchctl rpkg reject porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Changes lifecycle from `Proposed` back to `Draft` +- Allows further modifications +- You can then make changes and re-propose + +![Diagram](/static/images/porch/guides/reject-workflow.drawio.svg) + +Once rejected the process repeats from Stage 2 to [Pull -> Modify -> Propose and Approve] users are satisfied with its state. + +--- + +## Troubleshooting + +**Package stuck in Draft?** + +- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` + +**Push fails with conflict?** + +- Pull the latest version first: `porchctl rpkg pull ./dir` +- The package may have been modified by someone else + +**Cannot modify Published package?** + +- Published packages are immutable +- Create a new revision using `porchctl rpkg copy` + +--- + +## Understanding Package Names + +Porch generates package names automatically: + +- Format: `{repoName}-{packageName}-{workspaceName}` +- Example: `porch-test.my-first-package.v1` +- The workspace name must be unique per package + +--- + +## Key Concepts + +- **Draft**: Work in progress, fully editable +- **Proposed**: Ready for review, still editable +- **Published**: Approved and immutable +- **Workspace**: Unique identifier for a package revision +- **Repository**: Git repo where packages are stored +- **Pipeline**: KRM functions that transform package resources + +--- diff --git a/static/images/porch/guides/approve-workflow.drawio.svg b/static/images/porch/guides/approve-workflow.drawio.svg new file mode 100644 index 00000000..c254a597 --- /dev/null +++ b/static/images/porch/guides/approve-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Approve Workflow
USER
porchctl rpkg approve porch-test.my-first-package.v1
PORCH

PORCH publishes your package
  • Proposed > Published
  • Creates Git tag & merges branch to main.
  • Records who approved & when
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Published < FINAL!
📝 Contains: Kptfile + pipeline + configmap.
✅ Approved by: You
🔓 Can edit: NO (immutable)

 \ No newline at end of file diff --git a/static/images/porch/guides/init-workflow.drawio.svg b/static/images/porch/guides/init-workflow.drawio.svg new file mode 100644 index 00000000..6ea27230 --- /dev/null +++ b/static/images/porch/guides/init-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Initialization Workflow
USER
porchctl rpkg init my-first-package
PORCH

GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft                    
📝 Contains: Kptfile                              
🔓 Can edit: YES                               

PORCH creates your package
  • Creates Kptfile & Pkg from template
  • Sets Lifecycle to: Draft
  • Stores in Git branch: drafts/...
 \ No newline at end of file diff --git a/static/images/porch/guides/propose-workflow.drawio.svg b/static/images/porch/guides/propose-workflow.drawio.svg new file mode 100644 index 00000000..85ad9f1e --- /dev/null +++ b/static/images/porch/guides/propose-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Propose Workflow
USER
porchctl rpkg propose porch-test.my-first-package.v1
PORCH

PORCH changes package state
  • Draft > Proposed
  • Signals: "Ready for review"
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Proposed < CHANGED!
📝 Contains: Kptfile + pipeline + configmap.
👀 Ready for review  
🔓 Can edit: YES (still editable) 

 \ No newline at end of file diff --git a/static/images/porch/guides/pull-workflow.drawio.svg b/static/images/porch/guides/pull-workflow.drawio.svg new file mode 100644 index 00000000..303dd01b --- /dev/null +++ b/static/images/porch/guides/pull-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Pulling Workflow
USER
porchctl rpkg pull my-first-package-v1 ./my-package
PORCH

GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft                    
📝 Contains: Kptfile                              
🔓 Can edit: YES                               

PORCH retrieves the package contents from GIT to the user
USER File System

User System: ./my-first-package/
|
|-->📁 Kptfile
|-->📁 Other YAML files   
|-->📁 Readme.md

 \ No newline at end of file diff --git a/static/images/porch/guides/push-workflow.drawio.svg b/static/images/porch/guides/push-workflow.drawio.svg new file mode 100644 index 00000000..9c3f3cd6 --- /dev/null +++ b/static/images/porch/guides/push-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Push Workflow
USER
porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package 
PORCH

PORCH receives your changes
  • Updates package files
  • Runs pipeline functions
  • Commits to Git
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft (still)
📝 Contains: Kptfile + pipeline + configmap.
✅ Pipeline ran: PASS
🔓 Can edit: YES                               

 \ No newline at end of file diff --git a/static/images/porch/guides/reject-workflow.drawio.svg b/static/images/porch/guides/reject-workflow.drawio.svg new file mode 100644 index 00000000..123f9f14 --- /dev/null +++ b/static/images/porch/guides/reject-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Package Reject Workflow
USER
porchctl rpkg reject porch-test.my-first-package.v1
PORCH

PORCH changes package state
  • Proposed > Draft
  • Package modification continues
GIT REPO


YOUR PACKAGE: my-first-package-v1

📦 Status: Draft < Back to Draft!
📝 Contains: Kptfile + pipeline + configmap.
🔓 Can edit: YES (still editable)
🔄 Can pull → modify → push → propose again 

 \ No newline at end of file From 5e3c7084a2853556c02d2d54751dc438cc519ccd Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 09:54:29 +0000 Subject: [PATCH 2/5] amended comments --- .../initializing-first-package.md | 21 ++++++++++++------- .../guides/lifecycle-workflow.drawio.svg | 4 ++++ 2 files changed, 18 insertions(+), 7 deletions(-) create mode 100644 static/images/porch/guides/lifecycle-workflow.drawio.svg diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md index 41c00433..57d74a8f 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -1,8 +1,8 @@ --- -title: "Creating your first package" +title: "Creating Packages" type: docs weight: 3 -description: "A tutorial designed to guide a first time user's to the package creation process in Porch" +description: "A step by step guide to creating a package revision in Porch" --- ## Prerequisites @@ -25,6 +25,11 @@ You will learn how to: --- +{{% alert title="Note" color="primary" %}} +Please note the tutorial assumes a porch repository is initialized with the "porch-test" name. +We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. +{{% /alert %}} + ## Step 1: Initialize Your First Package Create a new package in Porch using the `init` command: @@ -169,7 +174,7 @@ kind: ConfigMap metadata: name: test-config data: - Key: "Value" + key: "value" ``` **Save and close the file.** @@ -227,7 +232,7 @@ porchctl rpkg propose porch-test.my-first-package.v1 --namespace default ![Diagram](/static/images/porch/guides/propose-workflow.drawio.svg) {{% alert title="Note" color="primary" %}} -Note a state change from `Draft` to `Proposed` means that in Git the package has moved from the `draft` branch to the `proposed` branch +A lifecycle state change from `Draft` to `Proposed` means that in Git the package has moved from the `draft` branch to the `proposed` branch {{% /alert %}} **Verify the state change:** @@ -255,7 +260,7 @@ porchctl rpkg approve porch-test.my-first-package.v1 --namespace default **What this does:** -- Changes lifecycle from `Proposed` to `Published` +- Changes packageRevision lifecycle from `Proposed` (0) to `Published` (1) - Package becomes **immutable** (content cannot be changed) - Records who approved and when - Package is now available for cloning/deployment @@ -299,7 +304,9 @@ porchctl rpkg reject porch-test.my-first-package.v1 --namespace default ![Diagram](/static/images/porch/guides/reject-workflow.drawio.svg) -Once rejected the process repeats from Stage 2 to [Pull -> Modify -> Propose and Approve] users are satisfied with its state. +If the package is rejected, the process begins again from Step 2 until the desired state is achieved. + +![Diagram](/static/images/porch/guides/lifecycle-workflow.drawio.svg) --- @@ -317,7 +324,7 @@ Once rejected the process repeats from Stage 2 to [Pull -> Modify -> Propose and **Cannot modify Published package?** - Published packages are immutable -- Create a new revision using `porchctl rpkg copy` +- Create a new revision using `porchctl rpkg copy` [Copying Packages Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md" %}}). --- diff --git a/static/images/porch/guides/lifecycle-workflow.drawio.svg b/static/images/porch/guides/lifecycle-workflow.drawio.svg new file mode 100644 index 00000000..2d24fdca --- /dev/null +++ b/static/images/porch/guides/lifecycle-workflow.drawio.svg @@ -0,0 +1,4 @@ + + + +
Draft
🔓 Editable
Proposed
👀 Review
Published
🔒 Immutable
propose
approve
reject
 \ No newline at end of file From 815aaef60edd1538af9adc5a4a1638aae328213f Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 09:58:19 +0000 Subject: [PATCH 3/5] reformating to PackageRevision --- .../initializing-first-package.md | 111 ++++++++++-------- 1 file changed, 59 insertions(+), 52 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md index 57d74a8f..9b1ec0cc 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -1,5 +1,5 @@ --- -title: "Creating Packages" +title: "Creating Package Revisions" type: docs weight: 3 description: "A step by step guide to creating a package revision in Porch" @@ -16,12 +16,16 @@ description: "A step by step guide to creating a package revision in Porch" You will learn how to: -1. Initialize a new package -2. Pull the package locally -3. Modify the package (update Kptfile) +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 for review -6. Approve or reject the package +5. Propose the package revision for review +6. Approve or reject the package revision + +{{% alert title="Understanding Terminology" color="info" %}} +In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package". +{{% /alert %}} --- @@ -30,9 +34,9 @@ Please note the tutorial assumes a porch repository is initialized with the "por We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. {{% /alert %}} -## Step 1: Initialize Your First Package +## Step 1: Initialize Your First Package Revision -Create a new package in Porch using the `init` command: +Create a new package revision in Porch using the `init` command: ```bash porchctl rpkg init my-first-package \ @@ -44,20 +48,20 @@ porchctl rpkg init my-first-package \ **What this does:** -- Creates a new package named `my-first-package` +- Creates a new PackageRevision named `my-first-package` - Places it in the `porch-test` repository -- Uses `v1` as the workspace name (must be unique) +- Uses `v1` as the workspace name (must be unique within this package) - Starts in `Draft` lifecycle state ![Diagram](/static/images/porch/guides/init-workflow.drawio.svg) -**Verify the package was created:** +**Verify the package revision was created:** ```bash porchctl rpkg get --namespace default ``` -You should see your package listed with lifecycle `Draft`: +You should see your package revision listed with lifecycle `Draft`: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -66,9 +70,9 @@ porch-test.my-first-package.v1 my-first-package v1 0 f --- -## Step 2: Pull the Package Locally +## Step 2: Pull the Package Revision Locally -Download the package contents to your local filesystem: +Download the package revision contents to your local filesystem: ```bash porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace default @@ -76,13 +80,13 @@ porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace **What this does:** -- Fetches all package resources from Porch +- Fetches all resources from the PackageRevision - Saves them to the `./my-first-package` directory - Includes the Kptfile and any other resources ![Diagram](/static/images/porch/guides/pull-workflow.drawio.svg) -**Explore the package:** +**Explore the package revision contents:** ```bash ls -al ./my-first-package @@ -90,7 +94,7 @@ ls -al ./my-first-package You'll see: -- The `Kptfile` - Package metadata and pipeline configuration +- The `Kptfile` - PackageRevision metadata and pipeline configuration - Other YAML files (if any were created) ```bash @@ -111,7 +115,7 @@ If you have the tree command installed on your system you can use it to view the tree ./my-first-package/ ``` -Should return the following output on your package: +Should return the following output: ```bash my-first-package/ @@ -124,7 +128,7 @@ my-first-package/ --- -## Step 3: Modify the Package +## Step 3: Modify the Package Revision Let's add a simple KRM function to the pipeline. @@ -155,12 +159,12 @@ pipeline: **What this does:** - Adds a `set-namespace` function to the pipeline -- This function will set the namespace to `production` for all resources in the package -- Functions run automatically when the package is rendered +- This function will set the namespace to `production` for all resources +- Functions run automatically when the package revision is rendered **Add new resource:** -Create a new configmap inside the package: +Create a new configmap: ```bash vim ./my-first-package/test-config.yaml @@ -187,7 +191,7 @@ Changes are LOCAL ONLY (Porch doesn't know about them yet) at this stage ## Step 4: Push Changes Back to Porch -Upload your modified package back to Porch: +Upload your modified package revision back to Porch: ```bash porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace default @@ -195,9 +199,9 @@ porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace **What this does:** -- Updates the package revision in Porch +- Updates the PackageRevision in Porch - Triggers rendering (executes pipeline functions) -- Package remains in `Draft` state +- PackageRevision remains in `Draft` state ![Diagram](/static/images/porch/guides/push-workflow.drawio.svg) @@ -215,9 +219,9 @@ porch-test.my-first-package.v1 pushed --- -## Step 5: Propose the Package +## Step 5: Propose the Package Revision -Move the package to `Proposed` state for review: +Move the package revision to `Proposed` state for review: ```bash porchctl rpkg propose porch-test.my-first-package.v1 --namespace default @@ -226,13 +230,13 @@ porchctl rpkg propose porch-test.my-first-package.v1 --namespace default **What this does:** - Changes lifecycle from `Draft` to `Proposed` -- Signals the package is ready for review -- Package can still be modified if needed +- Signals the package revision is ready for review +- PackageRevision can still be modified if needed ![Diagram](/static/images/porch/guides/propose-workflow.drawio.svg) {{% alert title="Note" color="primary" %}} -A lifecycle state change from `Draft` to `Proposed` means that in Git the package has moved from the `draft` branch to the `proposed` branch +A lifecycle state change from `Draft` to `Proposed` means that in Git the package revision has moved from the `draft` branch to the `proposed` branch {{% /alert %}} **Verify the state change:** @@ -250,9 +254,9 @@ porch-test.my-first-package.v1 my-first-package v1 0 f --- -## Step 6a: Approve the Package +## Step 6a: Approve the Package Revision -If the package looks good, approve it to publish: +If the package revision looks good, approve it to publish: ```bash porchctl rpkg approve porch-test.my-first-package.v1 --namespace default @@ -260,10 +264,10 @@ porchctl rpkg approve porch-test.my-first-package.v1 --namespace default **What this does:** -- Changes packageRevision lifecycle from `Proposed` (0) to `Published` (1) -- Package becomes **immutable** (content cannot be changed) +- Changes PackageRevision lifecycle from `Proposed` (revision 0) to `Published` (revision 1) +- PackageRevision becomes **immutable** (content cannot be changed) - Records who approved and when -- Package is now available for cloning/deployment +- PackageRevision is now available for cloning/deployment ![Diagram](/static/images/porch/guides/approve-workflow.drawio.svg) @@ -288,9 +292,9 @@ porch-test.my-first-package.v1 my-first-package v1 1 t --- -## Step 6b: Reject the Package (Alternative) +## Step 6b: Reject the Package Revision (Alternative) -If the package needs more work, reject it to return to `Draft`: +If the package revision needs more work, reject it to return to `Draft`: ```bash porchctl rpkg reject porch-test.my-first-package.v1 --namespace default @@ -304,7 +308,7 @@ porchctl rpkg reject porch-test.my-first-package.v1 --namespace default ![Diagram](/static/images/porch/guides/reject-workflow.drawio.svg) -If the package is rejected, the process begins again from Step 2 until the desired state is achieved. +If the package revision is rejected, the process begins again from Step 2 until the desired state is achieved. ![Diagram](/static/images/porch/guides/lifecycle-workflow.drawio.svg) @@ -312,39 +316,42 @@ If the package is rejected, the process begins again from Step 2 until the desir ## Troubleshooting -**Package stuck in Draft?** +**PackageRevision stuck in Draft?** -- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` +- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` **Push fails with conflict?** -- Pull the latest version first: `porchctl rpkg pull ./dir` -- The package may have been modified by someone else +- Pull the latest version first: `porchctl rpkg pull ./dir` +- The PackageRevision may have been modified by someone else -**Cannot modify Published package?** +**Cannot modify Published PackageRevision?** -- Published packages are immutable -- Create a new revision using `porchctl rpkg copy` [Copying Packages Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md" %}}). +- Published PackageRevisions are immutable +- Create a new revision using `porchctl rpkg copy` [Copying Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md" %}}). --- -## Understanding Package Names +## Understanding PackageRevision Names -Porch generates package names automatically: +Porch generates PackageRevision names automatically: -- Format: `{repoName}-{packageName}-{workspaceName}` +- Format: `{repoName}.{packageName}.{workspaceName}` - Example: `porch-test.my-first-package.v1` -- The workspace name must be unique per package +- The workspace name must be unique within the package +- Multiple PackageRevisions can share the same package name but have different workspaces --- ## Key Concepts +- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource) - **Draft**: Work in progress, fully editable - **Proposed**: Ready for review, still editable - **Published**: Approved and immutable -- **Workspace**: Unique identifier for a package revision -- **Repository**: Git repo where packages are stored -- **Pipeline**: KRM functions that transform package resources +- **Workspace**: Unique identifier for a PackageRevision within a package +- **Repository**: Git repo where PackageRevisions are stored +- **Pipeline**: KRM functions that transform PackageRevision resources +- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication) --- From aca8880a5764d78cf574cea082b946879c713e4b Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 10:01:14 +0000 Subject: [PATCH 4/5] changed alert color --- .../4_tutorials_and_how-tos/initializing-first-package.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md index 9b1ec0cc..cbf6f978 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -23,7 +23,7 @@ You will learn how to: 5. Propose the package revision for review 6. Approve or reject the package revision -{{% alert title="Understanding Terminology" color="info" %}} +{{% alert title="Understanding Terminology" color="primary" %}} In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package". {{% /alert %}} From 94021978758d3f48648b99d8513ca8d5196780d4 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 10:47:47 +0000 Subject: [PATCH 5/5] adding clarity to function rendering --- .../4_tutorials_and_how-tos/initializing-first-package.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md index cbf6f978..76e0efb5 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md @@ -160,7 +160,7 @@ pipeline: - Adds a `set-namespace` function to the pipeline - This function will set the namespace to `production` for all resources -- Functions run automatically when the package revision is rendered +- These Functions are not rendered until the package is "pushed" to porch **Add new resource:**