From c4c845719dd5784985356b30a4146cbb4bd53ac4 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 4 Dec 2025 11:21:11 +0000 Subject: [PATCH 1/2] Adding PackageRevision Deletion Guide --- .../creating-packages.md | 9 +- .../deleting-packages.md | 371 ++++++++++++++++++ 2 files changed, 378 insertions(+), 2 deletions(-) create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md index 3bac9d1d..f9f9eaf3 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md @@ -275,10 +275,15 @@ 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 +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 ``` +{{% alert title="Note" color="primary" %}} +Porch automatically creates a main branch-tracking PackageRevision (with workspace `main` and revision `-1`) to track the latest published version of this package. +{{% /alert %}} + --- ## Step 6b: Reject the Package Revision (Alternative) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md new file mode 100644 index 00000000..d05774ea --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md @@ -0,0 +1,371 @@ +--- +title: "Deleting Package Revisions" +type: docs +weight: 7 +description: "A step by step guide to deleting package revisions in Porch" +--- + +## Tutorial Overview + +You will learn how to: + +1. Delete Draft and Proposed PackageRevisions directly +2. Propose Published PackageRevisions for deletion +3. Approve or reject deletion proposals +4. Understand the deletion workflow and safety mechanisms + +{{% alert title="Note" color="primary" %}} +This tutorial assumes a porch repository is initialized with the "porch-test" name. +Replace any "porch-test" value with your repository's name in the commands below. +{{% /alert %}} + +--- + +## Understanding PackageRevision Deletion + +PackageRevision deletion in Porch follows different workflows depending on the lifecycle state: + +**Direct Deletion:** +- **Draft** and **Proposed** PackageRevisions can be deleted immediately +- No approval process required +- Permanently removes the PackageRevision and its Git branch + +**Deletion Proposal Workflow:** +- **Published** PackageRevisions require a two-step deletion process +- First propose deletion, then approve the proposal +- Provides safety mechanism to prevent accidental deletion of production packages + +**Branch-Tracking PackageRevisions:** + +- When you publish a PackageRevision, Porch automatically creates a "main" branch-tracking PackageRevision +- These have revision `-1` and workspace name `main` +- They track the current state of the package on the main Git branch +- **Important**: These are managed automatically by Porch and should not be directly modified +- The only user interaction should be deletion after all regular PackageRevisions of **that specific package** are deleted + +--- + +## Step 1: Create Test PackageRevisions + +Let's create some test PackageRevisions to demonstrate the deletion workflows: + +```bash +# Create a Draft PackageRevision +porchctl rpkg init test-draft-package \ + --namespace=default \ + --repository=porch-test \ + --workspace=draft-v1 \ + --description="Test package for deletion" + +# Create a Proposed PackageRevision +porchctl rpkg init test-proposed-package \ + --namespace=default \ + --repository=porch-test \ + --workspace=proposed-v1 \ + --description="Test package for deletion" + +porchctl rpkg propose porch-test.test-proposed-package.proposed-v1 --namespace=default + +# Create a Published PackageRevision +porchctl rpkg init test-published-package \ + --namespace=default \ + --repository=porch-test \ + --workspace=published-v1 \ + --description="Test package for deletion" + +porchctl rpkg propose porch-test.test-published-package.published-v1 --namespace=default +porchctl rpkg approve porch-test.test-published-package.published-v1 --namespace=default +``` + +**Verify the PackageRevisions were created:** + +```bash +porchctl rpkg get --namespace=default +``` + +You should see output similar to: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-draft-package.draft-v1 test-draft-package draft-v1 0 false Draft porch-test +porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +``` + +--- + +## Step 2: Delete Draft PackageRevisions + +Draft PackageRevisions can be deleted immediately without any approval process: + +```bash +porchctl rpkg del porch-test.test-draft-package.draft-v1 --namespace=default +``` + +**What this does:** + +- Immediately removes the Draft PackageRevision +- Deletes the corresponding Git branch (`draft/draft-v1`) +- No approval or confirmation required + +**Verify deletion:** + +```bash +porchctl rpkg get --namespace=default --name=test-draft-package +``` + +The Draft PackageRevision should no longer appear in the list. + +--- + +## Step 3: Delete Proposed PackageRevisions + +Proposed PackageRevisions can also be deleted directly: + +```bash +porchctl rpkg del porch-test.test-proposed-package.proposed-v1 --namespace=default +``` + +**What this does:** + +- Immediately removes the Proposed PackageRevision +- Deletes the corresponding Git branch (`proposed/proposed-v1`) +- No approval process required + +**Verify deletion:** + +```bash +porchctl rpkg get --namespace=default --name=test-proposed-package +``` + +The Proposed PackageRevision should no longer appear in the list. + +--- + +## Step 4: Propose Published PackageRevision for Deletion + +Published PackageRevisions cannot be deleted directly. You must first propose them for deletion: + +```bash +porchctl rpkg propose-delete porch-test.test-published-package.published-v1 --namespace=default +``` + +**What this does:** + +- Changes the PackageRevision lifecycle from `Published` to `DeletionProposed` +- Signals that the PackageRevision should be deleted +- Requires approval before actual deletion occurs + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.test-published-package.published-v1 --namespace=default +``` + +The lifecycle should now show `DeletionProposed`: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true DeletionProposed porch-test +``` + +--- + +## Step 5a: Approve Deletion Proposal + +If you want to proceed with deletion, approve the deletion proposal: + +```bash +porchctl rpkg del porch-test.test-published-package.published-v1 --namespace=default +``` + +**What this does:** + +- Permanently deletes the PackageRevision +- Removes the Git tag and any associated branches +- Cannot be undone once completed + +**Verify deletion:** + +```bash +porchctl rpkg get --namespace=default --name=test-published-package +``` + +The PackageRevision should no longer exist. + +--- + +## Step 5b: Reject Deletion Proposal (Alternative) + +If you decide not to delete the PackageRevision, you can reject the deletion proposal: + +```bash +# First, let's create another Published PackageRevision for this example +porchctl rpkg init test-reject-delete \ + --namespace=default \ + --repository=porch-test \ + --workspace=reject-v1 \ + --description="Test package for rejection" + +porchctl rpkg propose porch-test.test-reject-delete.reject-v1 --namespace=default +porchctl rpkg approve porch-test.test-reject-delete.reject-v1 --namespace=default + +# Propose it for deletion +porchctl rpkg propose-delete porch-test.test-reject-delete.reject-v1 --namespace=default + +# Now reject the deletion proposal +porchctl rpkg reject porch-test.test-reject-delete.reject-v1 --namespace=default +``` + +**What this does:** + +- Changes lifecycle from `DeletionProposed` back to `Published` +- PackageRevision returns to normal published state +- Can be used again normally + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.test-reject-delete.reject-v1 --namespace=default +``` + +The lifecycle should be back to `Published`. + +--- + +## Batch Deletion Operations + +You can delete multiple PackageRevisions in a single command: + +**Delete multiple Draft/Proposed PackageRevisions:** + +```bash +porchctl rpkg del package1 package2 package3 --namespace=default +``` + +**Propose multiple Published PackageRevisions for deletion:** + +```bash +porchctl rpkg propose-delete package1 package2 package3 --namespace=default +``` + +**Approve multiple deletion proposals:** + +```bash +porchctl rpkg del package1 package2 package3 --namespace=default +``` + +--- + +## Deletion Workflow Summary + +The complete deletion workflow depends on the PackageRevision lifecycle state: + +```mermaid +graph TD + A[PackageRevision] --> B{Lifecycle State?} + B -->|Draft| C[porchctl rpkg del] + B -->|Proposed| C + B -->|Published| D[porchctl rpkg propose-delete] + C --> E[Immediately Deleted] + D --> F[DeletionProposed State] + F --> G{Decision?} + G -->|Approve| H[porchctl rpkg del] + G -->|Reject| I[porchctl rpkg reject] + H --> E + I --> J[Back to Published] +``` + +--- + +## Safety Considerations + +**Published PackageRevision Protection:** +- Two-step deletion process prevents accidental removal +- Deletion proposals can be reviewed before approval +- Rejected proposals restore the PackageRevision to Published state + +**Git Repository Impact:** +- Draft/Proposed deletions remove Git branches +- Published deletions remove Git tags and references +- Deletion is permanent and cannot be undone + +**Dependency Considerations:** +- Check if other PackageRevisions depend on the one being deleted +- Deleting upstream packages may affect downstream clones +- Consider the impact on deployed workloads + +--- + +## Troubleshooting + +**Cannot delete Published PackageRevision directly:** + +```bash +Error: cannot delete published package revision directly, use propose-delete first +``` + +- Use `porchctl rpkg propose-delete` first, then `porchctl rpkg del` + +**PackageRevision not found:** + +- Verify the exact PackageRevision name: `porchctl rpkg get --namespace=default` +- Check you're using the correct namespace +- Ensure the PackageRevision hasn't already been deleted + +**Permission denied:** + +- Check RBAC permissions: `kubectl auth can-i delete packagerevisions -n default` +- Verify your service account has proper deletion roles + +**Deletion proposal stuck:** + +- Check the PackageRevision status: `porchctl rpkg get -o yaml` +- Look for conditions that might prevent deletion +- Ensure no other processes are modifying the PackageRevision + +--- + +## Complete Cleanup + +After deleting PackageRevisions, you may notice "main" branch-tracking PackageRevisions still exist. These are automatically created by Porch when packages are published and must be deleted separately. + +{{% alert title="Important" color="warning" %}} +Main branch-tracking PackageRevisions (with workspace name "main" and revision "-1") are managed automatically by Porch. Do not modify, propose, approve, or otherwise interact with them except for deletion after all regular PackageRevisions of that specific package have been removed. +{{% /alert %}} + +**Check for remaining PackageRevisions:** + +```bash +porchctl rpkg get --namespace=default +``` + +You might see output like: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-reject-delete.main test-reject-delete main -1 false Published porch-test +``` + +**Delete the main branch-tracking PackageRevisions:** + +```bash +# Propose deletion of main branch PackageRevisions +porchctl rpkg propose-delete porch-test.test-published-package.main --namespace=default +porchctl rpkg propose-delete porch-test.test-reject-delete.main --namespace=default + +# Approve the deletions +porchctl rpkg del porch-test.test-published-package.main --namespace=default +porchctl rpkg del porch-test.test-reject-delete.main --namespace=default +``` + +**Verify complete cleanup:** + +```bash +porchctl rpkg get --namespace=default +``` + +All test PackageRevisions should now be removed. + +--- \ No newline at end of file From 6d2259c01cc98e0c43f75773305c70f42b13a72e Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 4 Dec 2025 15:56:11 +0000 Subject: [PATCH 2/2] modified some example output sections --- .../deleting-packages.md | 46 +++++++++++++++---- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md index d05774ea..7b4b724a 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md @@ -26,11 +26,13 @@ Replace any "porch-test" value with your repository's name in the commands below PackageRevision deletion in Porch follows different workflows depending on the lifecycle state: **Direct Deletion:** + - **Draft** and **Proposed** PackageRevisions can be deleted immediately - No approval process required - Permanently removes the PackageRevision and its Git branch **Deletion Proposal Workflow:** + - **Published** PackageRevisions require a two-step deletion process - First propose deletion, then approve the proposal - Provides safety mechanism to prevent accidental deletion of production packages @@ -89,6 +91,7 @@ You should see output similar to: NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY porch-test.test-draft-package.draft-v1 test-draft-package draft-v1 0 false Draft porch-test porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test +porch-test.test-published-package.main test-published-package main -1 false Published porch-test porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test ``` @@ -111,10 +114,17 @@ porchctl rpkg del porch-test.test-draft-package.draft-v1 --namespace=default **Verify deletion:** ```bash -porchctl rpkg get --namespace=default --name=test-draft-package +porchctl rpkg get --namespace=default ``` -The Draft PackageRevision should no longer appear in the list. +The Draft PackageRevision should no longer appear in the list: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +``` --- @@ -135,10 +145,16 @@ porchctl rpkg del porch-test.test-proposed-package.proposed-v1 --namespace=defau **Verify deletion:** ```bash -porchctl rpkg get --namespace=default --name=test-proposed-package +porchctl rpkg get --namespace=default ``` -The Proposed PackageRevision should no longer appear in the list. +The Proposed PackageRevision should no longer appear in the list: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +``` --- @@ -166,6 +182,7 @@ The lifecycle should now show `DeletionProposed`: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test porch-test.test-published-package.published-v1 test-published-package published-v1 1 true DeletionProposed porch-test ``` @@ -188,10 +205,15 @@ porchctl rpkg del porch-test.test-published-package.published-v1 --namespace=def **Verify deletion:** ```bash -porchctl rpkg get --namespace=default --name=test-published-package +porchctl rpkg get --namespace=default ``` -The PackageRevision should no longer exist. +The published PackageRevision should no longer exist, but the main branch-tracking PackageRevision remains: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +``` --- @@ -229,7 +251,12 @@ porchctl rpkg reject porch-test.test-reject-delete.reject-v1 --namespace=default porchctl rpkg get porch-test.test-reject-delete.reject-v1 --namespace=default ``` -The lifecycle should be back to `Published`. +The lifecycle should be back to `Published`: + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-reject-delete.reject-v1 test-reject-delete reject-v1 1 true Published porch-test +``` --- @@ -281,16 +308,19 @@ graph TD ## Safety Considerations **Published PackageRevision Protection:** + - Two-step deletion process prevents accidental removal - Deletion proposals can be reviewed before approval - Rejected proposals restore the PackageRevision to Published state **Git Repository Impact:** + - Draft/Proposed deletions remove Git branches - Published deletions remove Git tags and references - Deletion is permanent and cannot be undone **Dependency Considerations:** + - Check if other PackageRevisions depend on the one being deleted - Deleting upstream packages may affect downstream clones - Consider the impact on deployed workloads @@ -368,4 +398,4 @@ porchctl rpkg get --namespace=default All test PackageRevisions should now be removed. ---- \ No newline at end of file +---