From 2e4fd026298912656c145fc1942cd047818e972c Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Wed, 3 Dec 2025 13:06:08 +0000 Subject: [PATCH] restructured working with package revision guides --- .../working_with_package_revisions/_index.md | 185 +++++++++++++++++- .../cloning-packages.md | 0 .../copying-packages.md | 0 .../creating-packages.md} | 53 ----- .../inspecting-packages.md | 42 ---- .../upgrading-packages.md | 3 - 6 files changed, 184 insertions(+), 99 deletions(-) rename content/en/docs/neo-porch/4_tutorials_and_how-tos/{ => working_with_package_revisions}/cloning-packages.md (100%) rename content/en/docs/neo-porch/4_tutorials_and_how-tos/{ => working_with_package_revisions}/copying-packages.md (100%) rename content/en/docs/neo-porch/4_tutorials_and_how-tos/{initializing-first-package.md => working_with_package_revisions/creating-packages.md} (77%) rename content/en/docs/neo-porch/4_tutorials_and_how-tos/{ => working_with_package_revisions}/inspecting-packages.md (83%) rename content/en/docs/neo-porch/4_tutorials_and_how-tos/{ => working_with_package_revisions}/upgrading-packages.md (97%) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md index 22ac3717..03138433 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/_index.md @@ -2,6 +2,189 @@ title: "Working with Package Revisions" type: docs weight: 3 -description: +description: A group of guides outlining how to interact with Package Revisions 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-porchctl.md" %}}). +- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}). +- **Kubectl** configured to access your cluster. + +--- + +## Understanding Package Revisions + +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". + +PackageRevisions are Kubernetes resources that represent versioned collections of configuration files stored in Git repositories. Each PackageRevision contains: + +- **KRM Resources**: Kubernetes Resource Model files (YAML configurations) +- **Kptfile**: Package metadata and pipeline configuration +- **Pipeline Functions**: KRM functions that transform package resources +- **Lifecycle State**: Current state in the package workflow + +**PackageRevision Operations:** + +- **Creation**: `init`, `clone`, `copy` - Create new PackageRevisions from scratch, existing packages, or new revisions +- **Inspection**: `get` - List and view PackageRevision information and metadata +- **Content Management**: `pull`, `push` - Move PackageRevision content between Git repositories and local filesystem +- **Lifecycle Management**: `propose`, `approve`, `reject` - Control PackageRevision workflow states +- **Upgrading**: `upgrade` - Create new revision upgrading downstream to more recent upstream package +- **Deletion**: `propose-delete`, `del` - Propose deletion of published PackageRevisions, then delete them + +--- + +## PackageRevision Lifecycle + +PackageRevisions follow a structured lifecycle with three main states: + +- **Draft**: Work in progress, fully editable. Revision number is 0. +- **Proposed**: Ready for review, still editable. Revision number remains 0. +- **Published**: Approved and immutable. Revision number increments to 1+. + +**Lifecycle Transitions:** + +1. **Draft → Proposed**: `porchctl rpkg propose` - Signal readiness for review +2. **Proposed → Published**: `porchctl rpkg approve` - Approve and make immutable +3. **Proposed → Draft**: `porchctl rpkg reject` - Return for more work + +**Additional States:** + +- **DeletionProposed**: PackageRevision marked for deletion, pending approval + +--- + +## PackageRevision Naming + +Porch generates PackageRevision names automatically using a consistent format: + +- **Format**: `{repositoryName}.{packageName}.{workspaceName}` +- **Example**: `porch-test.my-first-package.v1` + +**Name Components:** + +- **Repository Name**: Name of the registered Git repository +- **Package Name**: Logical name for the package (can have multiple revisions) +- **Workspace Name**: Unique identifier within the package (maps to Git branch/tag) + +**Important Notes:** + +- Workspace names must be unique within a package +- Multiple PackageRevisions can share the same package name with different workspaces +- Published PackageRevisions get tagged in Git using the workspace name + +--- + +## Working with PackageRevision Content + +PackageRevisions contain structured configuration files that can be modified through various operations: + +**Local Operations:** + +1. **Pull**: Download PackageRevision contents to local filesystem +2. **Modify**: Edit files locally using standard tools +3. **Push**: Upload changes back to Porch (triggers pipeline rendering) + +**Pipeline Processing:** + +- KRM functions defined in the Kptfile automatically transform resources +- Functions run when PackageRevisions are pushed to Porch +- Common functions: set-namespace, apply-replacements, search-replace + +**Content Structure:** + +```bash +package-revision/ +├── Kptfile # Package metadata and pipeline +├── .KptRevisionMetadata # Porch-managed metadata +├── package-context.yaml # Package context information +├── README.md # Package documentation +└── *.yaml # KRM resources +``` + +--- + +## Repository Integration + +PackageRevisions are stored in Git repositories registered with Porch: + +**Git Branch Mapping:** + +- **Draft**: Stored in `draft/{workspace}` branch +- **Proposed**: Stored in `proposed/{workspace}` branch +- **Published**: Tagged as `{workspace}` and stored in main branch + +**Repository Types:** + +- **Blueprint Repositories**: Contain upstream package templates for cloning +- **Deployment Repositories**: Store deployment-ready packages (marked with `--deployment` flag) + +**Synchronization:** + +- Porch automatically syncs with Git repositories +- Manual sync: `porchctl repo sync ` +- Periodic sync can be configured with cron expressions + +--- + +## Troubleshooting + +Common issues when working with PackageRevisions and their solutions: + +**PackageRevision stuck in Draft?** + +- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` +- Verify all required fields are populated in the Kptfile +- Check for pipeline function errors in Porch server logs + +**Push fails with conflict?** + +- Pull the latest version first: `porchctl rpkg pull ./dir` +- The PackageRevision may have been modified by someone else +- Resolve conflicts locally and push again + +**Cannot modify Published PackageRevision?** + +- Published PackageRevisions are immutable by design +- Create a new revision using `porchctl rpkg copy` +- Use the copying workflow to create editable versions + +**PackageRevision not found?** + +- Verify the exact PackageRevision name: `porchctl rpkg get --namespace default` +- Check you're using the correct namespace +- Ensure the repository is registered and synchronized + +**Permission denied errors?** + +- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default` +- Verify service account has proper roles for PackageRevision operations +- Ensure repository authentication is configured correctly + +**Pipeline functions failing?** + +- Check function image availability and version +- Verify function configuration in Kptfile +- Review function logs in Porch server output during push operations + +--- + +## Key Concepts + +Important terms and concepts for working with PackageRevisions: + +- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource) +- **Workspace**: Unique identifier for a PackageRevision within a package (maps to Git branch/tag) +- **Lifecycle**: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed) +- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication) +- **Latest**: Flag indicating the most recent published PackageRevision of a package +- **Pipeline**: KRM functions defined in Kptfile that transform PackageRevision resources +- **Upstream/Downstream**: Relationship between source PackageRevisions (upstream) and their clones (downstream) +- **Repository**: Git repository where PackageRevisions are stored and managed +- **Namespace Scope**: PackageRevisions exist within a Kubernetes namespace and inherit repository namespace +- **Rendering**: Process of executing pipeline functions to transform PackageRevision resources +- **Kptfile**: YAML file containing PackageRevision metadata, pipeline configuration, and dependency information + +--- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md similarity index 100% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md rename to content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md similarity index 100% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/copying-packages.md rename to content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md 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/working_with_package_revisions/creating-packages.md similarity index 77% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/initializing-first-package.md rename to content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md index 76e0efb5..3bac9d1d 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/working_with_package_revisions/creating-packages.md @@ -5,13 +5,6 @@ weight: 3 description: "A step by step guide to creating a package revision 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: @@ -23,10 +16,6 @@ You will learn how to: 5. Propose the package revision for review 6. Approve or reject the package revision -{{% 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 %}} - --- {{% alert title="Note" color="primary" %}} @@ -313,45 +302,3 @@ If the package revision is rejected, the process begins again from Step 2 until ![Diagram](/static/images/porch/guides/lifecycle-workflow.drawio.svg) --- - -## Troubleshooting - -**PackageRevision 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 PackageRevision may have been modified by someone else - -**Cannot modify Published PackageRevision?** - -- 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 PackageRevision Names - -Porch generates PackageRevision names automatically: - -- Format: `{repoName}.{packageName}.{workspaceName}` -- Example: `porch-test.my-first-package.v1` -- 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 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) - ---- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md similarity index 83% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md rename to content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md index fb638816..81243573 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md @@ -5,16 +5,7 @@ weight: 3 description: "A guide to getting/listing, reading, querying, and inspecting package revisions 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. - -{{% 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 %}} --- @@ -368,36 +359,3 @@ For a complete reference of all available command options and flags, see the [Po {{% /alert %}} --- - -## Troubleshooting - -**No PackageRevisions shown?** - -- Verify repositories are registered and healthy (see [Repository Management Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}})) -- Ensure PackageRevisions exist in the Git repository - -**Permission denied errors?** - -- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default` -- Verify service account has proper roles - -**PackageRevision not found?** - -- Confirm the exact PackageRevision name: `porchctl rpkg get --namespace default` -- Check you're using the correct namespace -- Verify the PackageRevision hasn't been deleted - ---- - -## Key Concepts - -- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource) -- **Namespace**: Kubernetes namespace where PackageRevisions are managed -- **Repository**: Git repository containing PackageRevision sources -- **Lifecycle**: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed) -- **Workspace**: Unique identifier for a PackageRevision within a package (maps to Git branch/tag) -- **Latest**: Flag indicating the most recent published PackageRevision of a package -- **Path nodes**: Directory structure within repository where PackageRevision is located -- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication) - ---- diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md similarity index 97% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md rename to content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md index ce421164..34480421 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/upgrading-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md @@ -9,10 +9,7 @@ The package upgrade feature in Porch is a powerful mechanism for keeping deploye For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide/#package-upgrade" %}}). -## Prerequisites -* Porch installed in your Kubernetes cluster, along with its CLI `porchctl`. [Setup Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}) -* A Git Repository registered with Porch, in this example it's assumed that the Porch-Repository's name is "porch-test". [Repository Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}) ## Key Concepts