diff --git a/content/en/docs/neo-porch/2_concepts/package-lifecycle.md b/content/en/docs/neo-porch/2_concepts/package-lifecycle.md new file mode 100644 index 000000000..7c0ff2716 --- /dev/null +++ b/content/en/docs/neo-porch/2_concepts/package-lifecycle.md @@ -0,0 +1,21 @@ +--- +title: "Package Lifecycle" +type: docs +weight: 3 +description: +--- + +## Package Lifecycle Workflow + +Packages managed by Porch progress through several states, from creation to final publication. This workflow ensures that packages are reviewed and approved before they are published and consumed. + +The typical lifecycle of a package is as follows: + +1. **Draft:** A user initializes a new package or clones an existing one. The package is in a `Draft` state, allowing the user to make changes freely in their local workspace. +2. **Proposed:** Once the changes are ready for review, the user pushes the package, which transitions it to the `Proposed` state. In this stage, the package is available for review by other team members. +3. **Review and Approval:** + * **Approved:** If the package is approved, it is ready to be published. + * **Rejected:** If changes are required, the package is rejected. The user must pull the package, make the necessary modifications, and re-propose it for another review. +4. **Published:** After approval, the package is published. Published packages are considered stable and are available for deployment and consumption by other systems or clusters. They typically become the "latest" version of a package. + + diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md index dd82911da..e370aff4d 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md @@ -5,6 +5,8 @@ weight: 4 description: Tutorials in Porch --- -## Lorem Ipsum +## Overview -Lorem Ipsum +{{% alert title="Note" color="primary" %}} +The tutorials in this section assume you have a local development environment running (Porch + Gitea in kind). If you plan to follow the walkthroughs locally, please set up the Local Dev Environment first. For more information, see [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md" %}}). +{{% /alert %}} diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md deleted file mode 100644 index 829952d23..000000000 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Package Lifecycle" -type: docs -weight: 3 -description: ---- - -## Lorem Ipsum - -tutorial similar to getting started with first package in getting started section but this time in more detail and with package lifecycle diagram to clearly refference the different stages a package can be in and how it can change 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/upgrading-packages.md index 548f1661f..47194a7df 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/upgrading-packages.md @@ -1,16 +1,351 @@ --- -title: "Upgrading Packages" +title: "Upgrading Package Revisions" type: docs weight: 6 -description: +description: "A guide to upgrade package revisions using Porch and porchctl" --- -## Lorem Ipsum +The package upgrade feature in Porch is a powerful mechanism for keeping deployed packages (downstream) up-to-date with their source blueprints (upstream). This guide walks through the entire workflow, from creating packages to performing an upgrade, with a special focus on the different upgrade scenarios and merge strategies. -[UPGRADE EXAMPLES] [ALL THE DIFF SCENARIOS] [THIS IS THE MOST COMPLEX PART] [IT NEEDS TO BE VERY SPECIFIC ON WHAT DO/DONT WE SUPPORT] [] +For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide/#package-upgrade" %}}). -- [CREATE A GENERIC PACKAGE AND RUN IT THROUGH THE DIFFERENT UPGRADES TO SHOW HOW THEY WORK AND CHANGE] -- in upgrade scenario we expect that we have NEW BLUEPRINT IS PUBLISHED → DEPLOYMENT PACKAGE CAN BE UPGRADED IF IT WAS BASED ON THAT BLUEPRINT (AKA THE UPSTREAM OF THIS PACKAGE POINTS AT THAT BLUEPRINT). assuming 2 repositories -- [RESOURCE MERGE] IS A STRUCTURAL 3 WAY MERGE → HAS CONTEXT OF THE STRUCTURE OF THE FILES -> -- [COPY MERGE] IS A FILE REPLACEMENT STRATEGY → USEFUL WHEN YOU DONT NEED PORCH TO BE AWARE OF THE CONTENT OF THE FILES ESPECIALLY IF THERE IS CONTENT INSIDE THE FILES THAT DO NOT COMPLY WITH KUSTOMIZE. - - [OTHER STRATEGIES] … +## 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/setting-up-repositories" %}}) + +## Key Concepts + +To understand the upgrade process, it's essential to be familiar with the three states of a package during a merge operation: + +* **Original:** The state of the package when it was first cloned from the blueprint (e.g., `Blueprint v1`). This serves as the common ancestor for the merge. +* **Upstream:** The new, updated version of the source blueprint (e.g., `Blueprint v2`). This contains the changes you want to incorporate. +* **Local:** The current state of your deployment package, including any customizations you have applied since it was cloned. + +The upgrade process combines changes from the **Upstream** blueprint with your **Local** customizations, using the **Original** version as a base to resolve differences. + +## End-to-End Upgrade Example + +This example demonstrates the complete process of creating, customizing, and upgrading a package. + +### Step 1: Create a Base Blueprint Package (revision 1) + +Create the initial revision of our blueprint. This will be the "upstream" source for our deployment package. + +```bash +# Initialize a new package draft named 'blueprint' in the 'porch-test' repository +porchctl rpkg init blueprint --namespace=porch-demo --repository=porch-test --workspace=1 + +# Propose the draft for review +porchctl rpkg propose porch-test.blueprint.1 --namespace=porch-demo + +# Approve and publish the package, making it available as revision 1 +porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo +``` + + + +**PackageRevisions State After Step 1:** +```bash +$ porchctl rpkg get --namespace=porch-demo +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.blueprint.main blueprint main -1 false Published porch-test +porch-test.blueprint.1 blueprint 1 1 true Published porch-test +``` + +### Step 2: Create a New Blueprint Package Revision (revision 2) + +Create a new revision of the blueprint to simulate an update. In this case, we add a new ConfigMap. + +```bash +# Create a new draft (v2) by copying v1 +porchctl rpkg copy porch-test.blueprint.1 --namespace=porch-demo --workspace=2 + +# Pull the contents of the new draft locally to make changes +porchctl rpkg pull porch-test.blueprint.2 --namespace=porch-demo ./tmp/blueprint-v2 + +# Add a new resource file to the package +kubectl create configmap test-cm --dry-run=client -o yaml > ./tmp/blueprint-v2/new-configmap.yaml + +# Push the local changes back to the Porch draft +porchctl rpkg push porch-test.blueprint.2 --namespace=porch-demo ./tmp/blueprint-v2 + +# Propose and approve the new version +porchctl rpkg propose porch-test.blueprint.2 --namespace=porch-demo +porchctl rpkg approve porch-test.blueprint.2 --namespace=porch-demo +``` +At this point, we have two published blueprint versions: `v1` (the original) and `v2` (with the new ConfigMap). + + + +**PackageRevisions State After Step 2:** +```bash +$ porchctl rpkg get --namespace=porch-demo +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.blueprint.main blueprint main -1 false Published porch-test +porch-test.blueprint.1 blueprint 1 1 false Published porch-test +porch-test.blueprint.2 blueprint 2 2 true Published porch-test +``` + +### Step 3: Clone Blueprint revision 1 into a Deployment Package + +Clone the blueprint to create a "downstream" deployment package. + +```bash +# Clone blueprint v1 to create a new deployment package +porchctl rpkg clone porch-test.blueprint.1 --namespace=porch-demo --repository=porch-test --workspace=1 deployment + +# Pull the new deployment package locally to apply customizations +porchctl rpkg pull porch-test.deployment.1 --namespace=porch-demo ./tmp/deployment-v1 + +# Apply a local customization (e.g., add an annotation to the Kptfile) +kpt fn eval --image gcr.io/kpt-fn/set-annotations:v0.1.4 ./tmp/deployment-v1/Kptfile -- kpt.dev/annotation=true + +# Push the local changes back to Porch +porchctl rpkg push porch-test.deployment.1 --namespace=porch-demo ./tmp/deployment-v1 + +# Propose and approve the deployment package +porchctl rpkg propose porch-test.deployment.1 --namespace=porch-demo +porchctl rpkg approve porch-test.deployment.1 --namespace=porch-demo +``` + + + +**PackageRevisions State After Step 3:** +```bash +$ porchctl rpkg get --namespace=porch-demo +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.blueprint.main blueprint main -1 false Published porch-test +porch-test.blueprint.1 blueprint 1 1 false Published porch-test +porch-test.blueprint.2 blueprint 2 2 true Published porch-test +porch-test.deployment.main deployment main -1 false Published porch-test +porch-test.deployment.1 deployment 1 1 true Published porch-test +``` + +### Step 4: Discover and Perform the Upgrade + +Our deployment package is based on `blueprint.1`, but we know `blueprint.2` is available. We can discover and apply this upgrade. + +```bash +# Discover available upgrades for packages cloned from 'upstream' repositories +porchctl rpkg upgrade --discover=upstream +# This will list 'porch-test.deployment.1' as having an available upgrade to revision 2. + +# Upgrade the deployment package to revision 2 of its upstream blueprint +# This creates a new draft package: 'porch-test.deployment.2' +porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 + +# Propose and approve the upgraded package +porchctl rpkg propose porch-test.deployment.2 --namespace=porch-demo +porchctl rpkg approve porch-test.deployment.2 --namespace=porch-demo +``` + +After approval, `porch-test.deployment.2` is the new, published deployment package. It now contains: +1. The `new-configmap.yaml` from the upstream `blueprint.2`. +2. The local `kpt.dev/annotation=true` customization applied in Step 3. + + + +**PackageRevisions State After Step 4:** +```bash +$ porchctl rpkg get --namespace=porch-demo +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.blueprint.main blueprint main -1 false Published porch-test +porch-test.blueprint.1 blueprint 1 1 false Published porch-test +porch-test.blueprint.2 blueprint 2 2 true Published porch-test +porch-test.deployment.main deployment main -1 false Published porch-test +porch-test.deployment.1 deployment 1 1 false Published porch-test +porch-test.deployment.2 deployment 2 2 true Published porch-test +``` + +## Understanding Merge Strategies + + + +**Schema Explanation:** +The diagram above illustrates the package upgrade workflow in Porch: + +1. **CLONE**: A deployment package (Deployment.v1) is initially cloned from a blueprint (Blueprint.v1) in the blueprints repository +2. **COPY**: The blueprint evolves to a new version (Blueprint.v2) with additional features or fixes +3. **UPGRADE**: The deployment package is upgraded to incorporate changes from the new blueprint version, creating Deployment.v2 + +The dashed line shows the relationship between the new blueprint version and the upgrade process, indicating that the upgrade "uses the new blueprint" as its source for changes. + +The outcome of an upgrade depends on the changes made in the upstream blueprint and the local deployment package, combined with the chosen merge strategy. You can specify a strategy using the `--strategy` flag (e.g., `porchctl rpkg upgrade ... --strategy=copy-merge`). + +### Merge Strategy Comparison + +
| Scenario | +resource-merge (Default) | +copy-merge | +force-delete-replace | +fast-forward | +
|---|---|---|---|---|
| File added in Upstream | +File is added to Local. | +File is added to Local. | +File is added to Local. | +Fails (Local must be unchanged). | +
| File modified in Upstream only | +Changes are applied to Local. | +Upstream file overwrites Local file. | +Upstream file overwrites Local file. | +Fails (Local must be unchanged). | +
| File modified in Local only | +Local changes are kept. | +Local changes are kept. | +Local changes are discarded; Upstream version is used. | +Fails (Local must be unchanged). | +
| File modified in both (no conflict) | +Both changes are merged. | +Upstream file overwrites Local file. | +Upstream file overwrites Local file. | +Fails (Local must be unchanged). | +
| File modified in both (conflict) | +Merge autoconflic resolution: always choose the new upstream version. | +Upstream file overwrites Local file. | +Upstream file overwrites Local file. | +Fails (Local must be unchanged). | +
| File deleted in Upstream | +File is deleted from Local. | +File is deleted from Local. | +File is deleted from Local. | +Fails (Local must be unchanged). | +
| Local package is unmodified | +Upgrade succeeds. | +Upgrade succeeds. | +Upgrade succeeds. | +Upgrade succeeds. | +