From 143118bb26682a9cafcffda1178a79cdea4bdc84 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 17 Oct 2025 10:39:51 +0100 Subject: [PATCH 01/16] upgrade examples Signed-off-by: lapentafd --- .../4_tutorials_and_how-tos/test-setup.md | 110 +++++++++++ .../upgrading-packages.md | 185 +++++++++++++++++- .../neo-porch/static/flowchart.drawio.svg | 4 + 3 files changed, 291 insertions(+), 8 deletions(-) create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md create mode 100644 content/en/docs/neo-porch/static/flowchart.drawio.svg diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md new file mode 100644 index 00000000..4775b425 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md @@ -0,0 +1,110 @@ +--- +title: "Local Development Environment Setup" +type: docs +weight: 2 +description: "A guide to setting up a local environment for developing and testing with Porch." +--- + +# Local Development Environment Setup + +This guide provides instructions for setting up a local development environment using `kind` (Kubernetes in Docker). This setup is ideal for developing, testing, and exploring Porch functionalities. + + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Local Environment Setup](#local-environment-setup) +- [Verifying the Setup](#verifying-the-setup) +- [Package Lifecycle Workflow](#package-lifecycle-workflow) + + +## Prerequisites + +Before you begin, ensure you have the following tools installed on your system: + +* **[Docker](httpss://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster. +* **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/):** The Kubernetes command-line tool for interacting with your cluster. +* **[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation):** A tool for running local Kubernetes clusters using Docker container "nodes". + +The setup scripts provided in the Porch repository will handle the installation of Porch itself and its CLI, `porchctl`. + +## Local Environment Setup + +Follow these steps from the root directory of your cloned Porch repository to set up your local environment. + +1. **Bring up the `kind` cluster:** + + This script creates a local Kubernetes cluster with the necessary configuration for Porch. + + ```bash + ./scripts/setup-dev-env.sh + ``` + +2. **Build and load Porch images:** + + **Choose one of the following options** to build the Porch container images and load them into your `kind` cluster. + + * **CR-CACHE (Default):** Uses a cache backed by a Custom Resource (CR). + ```bash + make run-in-kind + ``` + + * **DB-CACHE:** Uses a PostgreSQL database as the cache backend. + ```bash + make run-in-kind-db-cache + ``` + +## Verifying the Setup + +After the setup scripts complete, verify that all components are running correctly. + +1. **Check Pod Status:** + + Ensure all pods in the `porch-system` namespace are in the `READY` state. + + ```bash + kubectl get pods -n porch-system + ``` + +2. **Verify CRD Availability:** + + Confirm that the `PackageRevision` Custom Resource Definition (CRD) has been successfully registered. + + ```bash + kubectl api-resources | grep packagerevisions + ``` + +3. **Configure `porchctl` (Optional):** + + The `porchctl` binary is built into the `.build/` directory. For convenient access, add it to your system's `PATH`. + + ```bash + # You can copy the binary to a directory in your PATH, for example: + sudo cp ./.build/porchctl /usr/local/bin/porchctl + + # Alternatively, you can add the build directory to your PATH: + export PATH="$(pwd)/.build:$PATH" + ``` + +4. **Access Gitea UI (Optional):** + + The local environment includes a Gitea instance for Git repository hosting. You can access it at [http://localhost:3000](http://localhost:3000). + + * **Username:** `nephio` + * **Password:** `secret` + +## 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. + +![Flowchart](../static/flowchart.drawio.svg) + 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 548f1661..68929eb4 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 @@ -2,15 +2,184 @@ title: "Upgrading Packages" type: docs weight: 6 -description: +description: "A guide to upgrade package revisions using Porch and porchctl" --- -## Lorem Ipsum +# Upgrading Porch Packages -[UPGRADE EXAMPLES] [ALL THE DIFF SCENARIOS] [THIS IS THE MOST COMPLEX PART] [IT NEEDS TO BE VERY SPECIFIC ON WHAT DO/DONT WE SUPPORT] [] +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. -- [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] … + +## Table of Contents + +- [Key Concepts](#key-concepts) +- [End-to-End Upgrade Example](#end-to-end-upgrade-example) +- [Understanding Merge Strategies](#understanding-merge-strategies) +- [Reference](#reference) + + +## 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 (v1) + +First, we create the initial version 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 v1 +porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo +``` + +### Step 2: Create a New Blueprint Version (v2) + +Next, we'll create a new version 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). + +### Step 3: Clone Blueprint v1 into a Deployment Package + +Now, a user clones 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 +``` + +### 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. + +## Understanding Merge Strategies + +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. | + +### Detailed Strategy Explanations + +#### `resource-merge` (Default) +This is a structural 3-way merge designed for Kubernetes resources. It understands the structure of YAML files and attempts to intelligently merge changes from the upstream and local packages. + +* **When to use:** This is the **recommended default strategy** for managing Kubernetes configuration. Use it when you want to preserve local customizations while incorporating upstream updates. + +#### `copy-merge` +A file-level replacement strategy. For any file present in both local and upstream, the upstream version is used, overwriting local changes. Files that only exist locally are kept. + +* **When to use:** When you trust the upstream source more than local changes or when Porch cannot parse the file contents (e.g., non-KRM files). + +#### `force-delete-replace` +The most aggressive strategy. It completely discards the local package's contents and replaces them with the contents of the new upstream package. + +* **When to use:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations. + +#### `fast-forward` +A fail-fast safety check. The upgrade only succeeds if the local package has **zero modifications** compared to the original blueprint version it was cloned from. + +* **When to use:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. + +## Reference + +### Command Flags + +The `porchctl rpkg upgrade` command has several key flags: + +* `--workspace=`: (Mandatory) The name for the new workspace where the upgraded package draft will be created. +* `--revision=`: (Optional) The specific revision number of the upstream package to upgrade to. If not specified, Porch will automatically use the latest published revision. +* `--strategy=`: (Optional) The merge strategy to use. Defaults to `resource-merge`. Options are `resource-merge`, `copy-merge`, `force-delete-replace`, `fast-forward`. + +For more details, run `porchctl rpkg upgrade --help`. + +### Best Practices + +* **Separate Repositories:** For better organization and access control, keep blueprint packages and deployment packages in separate Git repositories. +* **Understand Your Strategy:** Before upgrading, be certain which merge strategy fits your use case to avoid accidentally losing important local customizations. When in doubt, the default `resource-merge` is the safest and most intelligent option. + +### Cleanup + +To remove the packages created in this guide, you must first propose them for deletion and then perform the final deletion. + +```bash +# Clean up local temporary directory used in these examples +rm -rf ./tmp + +# Propose all packages for deletion +porchctl rpkg propose-delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo + +# Delete the packages +porchctl rpkg delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo +``` diff --git a/content/en/docs/neo-porch/static/flowchart.drawio.svg b/content/en/docs/neo-porch/static/flowchart.drawio.svg new file mode 100644 index 00000000..8ef79e65 --- /dev/null +++ b/content/en/docs/neo-porch/static/flowchart.drawio.svg @@ -0,0 +1,4 @@ + + + +
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file From 7fba00e376bc56b8a4cf94c66b0a02565e6dc85a Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 17 Oct 2025 11:11:26 +0100 Subject: [PATCH 02/16] Fix typo in link Signed-off-by: lapentafd --- content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md index 4775b425..c9724c5e 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md @@ -22,7 +22,7 @@ This guide provides instructions for setting up a local development environment Before you begin, ensure you have the following tools installed on your system: -* **[Docker](httpss://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster. +* **[Docker](https://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster. * **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/):** The Kubernetes command-line tool for interacting with your cluster. * **[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation):** A tool for running local Kubernetes clusters using Docker container "nodes". From 85b2a8212d85c6dfd5d8d8378d1182a286fd6bd8 Mon Sep 17 00:00:00 2001 From: Lapenta Francesco Davide <37077655+lapentad@users.noreply.github.com> Date: Tue, 21 Oct 2025 10:44:32 +0100 Subject: [PATCH 03/16] Update content for upgrading packages documentation --- .../neo-porch/4_tutorials_and_how-tos/upgrading-packages.md | 2 -- 1 file changed, 2 deletions(-) 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 68929eb4..23cce63c 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 @@ -9,14 +9,12 @@ description: "A guide to upgrade package revisions using Porch and porchctl" 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. - ## Table of Contents - [Key Concepts](#key-concepts) - [End-to-End Upgrade Example](#end-to-end-upgrade-example) - [Understanding Merge Strategies](#understanding-merge-strategies) - [Reference](#reference) - ## Key Concepts From 03d78c5b6922dd528e70c66ffbb8fcd875c25995 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 31 Oct 2025 14:30:33 +0000 Subject: [PATCH 04/16] reordered and added examples Signed-off-by: lapentafd --- .../4_tutorials_and_how-tos/_index.md | 4 +- .../package-lifecycle.md | 17 ++- .../4_tutorials_and_how-tos/test-setup.md | 110 ------------------ .../upgrading-packages.md | 56 +++++++++ .../deployments/local-dev-env-deployment.md | 90 +++++++++++++- 5 files changed, 158 insertions(+), 119 deletions(-) delete mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md 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 dd82911d..f59dcdd0 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,6 @@ weight: 4 description: Tutorials in Porch --- -## Lorem Ipsum +## Overview -Lorem Ipsum +> Note: 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: [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment/test-setup.md" %}}). 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 index 829952d2..b58f0c5c 100644 --- 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 @@ -2,9 +2,20 @@ title: "Package Lifecycle" type: docs weight: 3 -description: +description: --- -## Lorem Ipsum +## Package Lifecycle Workflow -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 +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. + +![Flowchart](../static/flowchart.drawio.svg) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md deleted file mode 100644 index c9724c5e..00000000 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/test-setup.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Local Development Environment Setup" -type: docs -weight: 2 -description: "A guide to setting up a local environment for developing and testing with Porch." ---- - -# Local Development Environment Setup - -This guide provides instructions for setting up a local development environment using `kind` (Kubernetes in Docker). This setup is ideal for developing, testing, and exploring Porch functionalities. - - -## Table of Contents - -- [Prerequisites](#prerequisites) -- [Local Environment Setup](#local-environment-setup) -- [Verifying the Setup](#verifying-the-setup) -- [Package Lifecycle Workflow](#package-lifecycle-workflow) - - -## Prerequisites - -Before you begin, ensure you have the following tools installed on your system: - -* **[Docker](https://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster. -* **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/):** The Kubernetes command-line tool for interacting with your cluster. -* **[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation):** A tool for running local Kubernetes clusters using Docker container "nodes". - -The setup scripts provided in the Porch repository will handle the installation of Porch itself and its CLI, `porchctl`. - -## Local Environment Setup - -Follow these steps from the root directory of your cloned Porch repository to set up your local environment. - -1. **Bring up the `kind` cluster:** - - This script creates a local Kubernetes cluster with the necessary configuration for Porch. - - ```bash - ./scripts/setup-dev-env.sh - ``` - -2. **Build and load Porch images:** - - **Choose one of the following options** to build the Porch container images and load them into your `kind` cluster. - - * **CR-CACHE (Default):** Uses a cache backed by a Custom Resource (CR). - ```bash - make run-in-kind - ``` - - * **DB-CACHE:** Uses a PostgreSQL database as the cache backend. - ```bash - make run-in-kind-db-cache - ``` - -## Verifying the Setup - -After the setup scripts complete, verify that all components are running correctly. - -1. **Check Pod Status:** - - Ensure all pods in the `porch-system` namespace are in the `READY` state. - - ```bash - kubectl get pods -n porch-system - ``` - -2. **Verify CRD Availability:** - - Confirm that the `PackageRevision` Custom Resource Definition (CRD) has been successfully registered. - - ```bash - kubectl api-resources | grep packagerevisions - ``` - -3. **Configure `porchctl` (Optional):** - - The `porchctl` binary is built into the `.build/` directory. For convenient access, add it to your system's `PATH`. - - ```bash - # You can copy the binary to a directory in your PATH, for example: - sudo cp ./.build/porchctl /usr/local/bin/porchctl - - # Alternatively, you can add the build directory to your PATH: - export PATH="$(pwd)/.build:$PATH" - ``` - -4. **Access Gitea UI (Optional):** - - The local environment includes a Gitea instance for Git repository hosting. You can access it at [http://localhost:3000](http://localhost:3000). - - * **Username:** `nephio` - * **Password:** `secret` - -## 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. - -![Flowchart](../static/flowchart.drawio.svg) - 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 23cce63c..f462ee6d 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 @@ -150,6 +150,62 @@ A fail-fast safety check. The upgrade only succeeds if the local package has **z * **When to use:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. +## Practical examples: upgrade strategies in action + +This section contains short, focused examples showing how each merge strategy behaves in realistic scenarios. Each example assumes you have a deployment package `porch-test.deployment.1` cloned from `porch-test.blueprint.1` and that `porch-test.blueprint.2` is available upstream. + +### Example A — `resource-merge` (default) + +Scenario: Upstream adds a new ConfigMap and local changes added an annotation to Kptfile. `resource-merge` should apply the upstream addition while preserving the local annotation. + +Commands (happy path): + +```bash +# discover available upgrades +porchctl rpkg upgrade --discover=upstream + +# perform upgrade using the default strategy +porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 +``` + +Outcome: A new draft `porch-test.deployment.2` is created containing both the new `ConfigMap` and the local annotation. + +### Example B — `copy-merge` + +Scenario: Upstream changes a file that the local package also modified, but you want the upstream version to win (file-level overwrite). + +Commands: + +```bash +porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=copy-merge +``` + +Outcome: Files present in both upstream and local are replaced with the upstream copy. Files only present locally are preserved. + +### Example C — `force-delete-replace` + +Scenario: The blueprint has diverged substantially; you want to reset the deployment package to exactly match upstream v2. + +Commands: + +```bash +porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=force-delete-replace +``` + +Outcome: The new draft contains only the upstream contents; local customizations are discarded. + +### Example D — `fast-forward` + +Scenario: You want to ensure upgrades are only applied to unmodified, pristine clones. + +Commands: + +```bash +porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 --strategy=fast-forward +``` + +Outcome: The upgrade succeeds only if `porch-test.deployment.1` has no local modifications compared to the original clone. If local changes exist, the command fails and reports the modifications that prevented a fast-forward. + ## Reference ### Command Flags diff --git a/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md b/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md index d2e8e06c..b7869fe8 100644 --- a/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md +++ b/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md @@ -1,10 +1,92 @@ --- -title: "Local/Development Environment Deployment" +title: "Local Development Environment Setup" type: docs weight: 3 -description: +description: "A guide to setting up a local environment for developing and testing with Porch." --- -## Lorem Ipsum +# Local Development Environment Setup -this section should only explain setting up the dev environment (not how to use it) [example old guide]({{% relref "/docs/neo-porch/6_configuration_and_deployments/relevant_old_docs/environment-setup.md" %}}) +This guide provides instructions for setting up a local development environment using `kind` (Kubernetes in Docker). This setup is ideal for developing, testing, and exploring Porch functionalities. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Local Environment Setup](#local-environment-setup) +- [Verifying the Setup](#verifying-the-setup) +- [Package Lifecycle Workflow](#package-lifecycle-workflow) + +## Prerequisites + +Before you begin, ensure you have the following tools installed on your system: + +* **[Docker](https://docs.docker.com/get-docker/):** For running containers, including the `kind` cluster. +* **[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/):** The Kubernetes command-line tool for interacting with your cluster. +* **[kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation):** A tool for running local Kubernetes clusters using Docker container "nodes". + +The setup scripts provided in the Porch repository will handle the installation of Porch itself and its CLI, `porchctl`. + +## Local Environment Setup + +Follow these steps from the root directory of your cloned Porch repository to set up your local environment. + +1. **Bring up the `kind` cluster:** + + This script creates a local Kubernetes cluster with the necessary configuration for Porch. + + ```bash + ./scripts/setup-dev-env.sh + ``` + +2. **Build and load Porch images:** + + **Choose one of the following options** to build the Porch container images and load them into your `kind` cluster. + + * **CR-CACHE (Default):** Uses a cache backed by a Custom Resource (CR). + ```bash + make run-in-kind + ``` + + * **DB-CACHE:** Uses a PostgreSQL database as the cache backend. + ```bash + make run-in-kind-db-cache + ``` + +## Verifying the Setup + +After the setup scripts complete, verify that all components are running correctly. + +1. **Check Pod Status:** + + Ensure all pods in the `porch-system` namespace are in the `READY` state. + + ```bash + kubectl get pods -n porch-system + ``` + +2. **Verify CRD Availability:** + + Confirm that the `PackageRevision` Custom Resource Definition (CRD) has been successfully registered. + + ```bash + kubectl api-resources | grep packagerevisions + ``` + +3. **Configure `porchctl` (Optional):** + + The `porchctl` binary is built into the `.build/` directory. For convenient access, add it to your system's `PATH`. + + ```bash + # You can copy the binary to a directory in your PATH, for example: + sudo cp ./.build/porchctl /usr/local/bin/porchctl + + # Alternatively, you can add the build directory to your PATH: + export PATH="$(pwd)/.build:$PATH" + ``` + +4. **Access Gitea UI (Optional):** + + The local environment includes a Gitea instance for Git repository hosting. You can access it at [http://localhost:3000](http://localhost:3000). + + * **Username:** `nephio` + * **Password:** `secret` From d5395527680858399247505c834dd34e138e6e79 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 31 Oct 2025 14:33:29 +0000 Subject: [PATCH 05/16] fix path error Signed-off-by: lapentafd --- content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 f59dcdd0..365d7d28 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 @@ -7,4 +7,4 @@ description: Tutorials in Porch ## Overview -> Note: 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: [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment/test-setup.md" %}}). +> Note: 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: [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md" %}}). From 1a0ff99c643f59fc9c6317d3691b4cb167dc787c Mon Sep 17 00:00:00 2001 From: lapentafd Date: Thu, 6 Nov 2025 16:22:53 +0000 Subject: [PATCH 06/16] moving the svg and fix link Signed-off-by: lapentafd --- .../neo-porch/4_tutorials_and_how-tos/package-lifecycle.md | 2 +- .../deployments/local-dev-env-deployment.md | 1 - static/flowchart.drawio.svg | 4 ++++ 3 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 static/flowchart.drawio.svg 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 index b58f0c5c..7b20bc97 100644 --- 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 @@ -18,4 +18,4 @@ The typical lifecycle of a package is as follows: * **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. -![Flowchart](../static/flowchart.drawio.svg) +![Flowchart](/flowchart.drawio.svg) diff --git a/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md b/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md index b7869fe8..e1ede2bc 100644 --- a/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md +++ b/content/en/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md @@ -14,7 +14,6 @@ This guide provides instructions for setting up a local development environment - [Prerequisites](#prerequisites) - [Local Environment Setup](#local-environment-setup) - [Verifying the Setup](#verifying-the-setup) -- [Package Lifecycle Workflow](#package-lifecycle-workflow) ## Prerequisites diff --git a/static/flowchart.drawio.svg b/static/flowchart.drawio.svg new file mode 100644 index 00000000..e2033ab2 --- /dev/null +++ b/static/flowchart.drawio.svg @@ -0,0 +1,4 @@ + + + +
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file From bdda058ed8d341bb1ffbf665cafaedb8291fe6ce Mon Sep 17 00:00:00 2001 From: lapentafd Date: Tue, 11 Nov 2025 11:04:24 +0000 Subject: [PATCH 07/16] address comments and added upgrade svg Signed-off-by: lapentafd --- .../package-lifecycle.md | 2 +- .../upgrading-packages.md | 39 +++++++++++++------ static/flowchart.drawio.svg | 4 -- static/images/flowchart.drawio.svg | 4 ++ static/images/upgrade.drawio.svg | 4 ++ 5 files changed, 37 insertions(+), 16 deletions(-) delete mode 100644 static/flowchart.drawio.svg create mode 100644 static/images/flowchart.drawio.svg create mode 100644 static/images/upgrade.drawio.svg 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 index 7b20bc97..4f00d7f1 100644 --- 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 @@ -18,4 +18,4 @@ The typical lifecycle of a package is as follows: * **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. -![Flowchart](/flowchart.drawio.svg) +![Flowchart](/images/flowchart.drawio.svg) 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 f462ee6d..034986ae 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,14 +1,14 @@ --- -title: "Upgrading Packages" +title: "Upgrading Package Revisions" type: docs weight: 6 description: "A guide to upgrade package revisions using Porch and porchctl" --- -# Upgrading Porch Packages - 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. +For detailed command reference, see the [porchctl CLI guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide/#package-upgrade" %}}). + ## Table of Contents - [Key Concepts](#key-concepts) @@ -30,24 +30,28 @@ The upgrade process combines changes from the **Upstream** blueprint with your * This example demonstrates the complete process of creating, customizing, and upgrading a package. -### Step 1: Create a Base Blueprint Package (v1) +### Step 1: Create a Base Blueprint Package (revision 1) -First, we create the initial version of our blueprint. This will be the "upstream" source for our deployment package. +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 +``` +```bash # Propose the draft for review porchctl rpkg propose porch-test.blueprint.1 --namespace=porch-demo +``` -# Approve and publish the package, making it available as v1 +```bash +# Approve and publish the package, making it available as revision 1 porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo ``` -### Step 2: Create a New Blueprint Version (v2) +### Step 2: Create a New Blueprint Package Revision (revision 2) -Next, we'll create a new version of the blueprint to simulate an update. In this case, we add a new ConfigMap. +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 @@ -68,9 +72,9 @@ 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). -### Step 3: Clone Blueprint v1 into a Deployment Package +### Step 3: Clone Blueprint revision 1 into a Deployment Package -Now, a user clones the blueprint to create a "downstream" deployment package. +Clone the blueprint to create a "downstream" deployment package. ```bash # Clone blueprint v1 to create a new deployment package @@ -114,6 +118,17 @@ After approval, `porch-test.deployment.2` is the new, published deployment packa ## Understanding Merge Strategies +![Package Upgrade Flow](/images/upgrade.drawio.svg) + +**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 @@ -158,12 +173,14 @@ This section contains short, focused examples showing how each merge strategy be Scenario: Upstream adds a new ConfigMap and local changes added an annotation to Kptfile. `resource-merge` should apply the upstream addition while preserving the local annotation. -Commands (happy path): +Commands: ```bash # discover available upgrades porchctl rpkg upgrade --discover=upstream +``` +```bash # perform upgrade using the default strategy porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision=2 --workspace=2 ``` diff --git a/static/flowchart.drawio.svg b/static/flowchart.drawio.svg deleted file mode 100644 index e2033ab2..00000000 --- a/static/flowchart.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file diff --git a/static/images/flowchart.drawio.svg b/static/images/flowchart.drawio.svg new file mode 100644 index 00000000..8ef79e65 --- /dev/null +++ b/static/images/flowchart.drawio.svg @@ -0,0 +1,4 @@ + + + +
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file diff --git a/static/images/upgrade.drawio.svg b/static/images/upgrade.drawio.svg new file mode 100644 index 00000000..336c7937 --- /dev/null +++ b/static/images/upgrade.drawio.svg @@ -0,0 +1,4 @@ + + + +
Blueprint.v1
Blueprint.v2
Deployment.v1
Deployment.v2
1.CLONE
2.COPY
3.UPGRADE
Using the new blueprint
Blueprints repository
Deployments repository
 \ No newline at end of file From d4afb9a8b1d41948f2f862e724e7aee363ab8196 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Tue, 11 Nov 2025 11:46:14 +0000 Subject: [PATCH 08/16] removed unused images Signed-off-by: lapentafd --- content/en/docs/neo-porch/static/flowchart.drawio.svg | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 content/en/docs/neo-porch/static/flowchart.drawio.svg diff --git a/content/en/docs/neo-porch/static/flowchart.drawio.svg b/content/en/docs/neo-porch/static/flowchart.drawio.svg deleted file mode 100644 index 8ef79e65..00000000 --- a/content/en/docs/neo-porch/static/flowchart.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file From d3b5479dbfff33ba1c47f6d0a4f9420a1c78c7b9 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Fri, 14 Nov 2025 15:22:17 +0000 Subject: [PATCH 09/16] resolve link issue moving images Signed-off-by: lapentafd --- .../package-lifecycle.md | 2 +- .../neo-porch/4_tutorials_and_how-tos/upgrading-packages.md | 2 +- static/images/{ => porch}/flowchart.drawio.svg | 0 static/images/{ => porch}/upgrade.drawio.svg | 0 4 files changed, 2 insertions(+), 2 deletions(-) rename content/en/docs/neo-porch/{4_tutorials_and_how-tos => 2_concepts}/package-lifecycle.md (95%) rename static/images/{ => porch}/flowchart.drawio.svg (100%) rename static/images/{ => porch}/upgrade.drawio.svg (100%) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md b/content/en/docs/neo-porch/2_concepts/package-lifecycle.md similarity index 95% rename from content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md rename to content/en/docs/neo-porch/2_concepts/package-lifecycle.md index 4f00d7f1..7c0ff271 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/package-lifecycle.md +++ b/content/en/docs/neo-porch/2_concepts/package-lifecycle.md @@ -18,4 +18,4 @@ The typical lifecycle of a package is as follows: * **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. -![Flowchart](/images/flowchart.drawio.svg) +![Flowchart](/static/images/porch/flowchart.drawio.svg) 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 034986ae..4e2b8b06 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 @@ -118,7 +118,7 @@ After approval, `porch-test.deployment.2` is the new, published deployment packa ## Understanding Merge Strategies -![Package Upgrade Flow](/images/upgrade.drawio.svg) +![Package Upgrade Flow](/static/images/porch/upgrade.drawio.svg) **Schema Explanation:** The diagram above illustrates the package upgrade workflow in Porch: diff --git a/static/images/flowchart.drawio.svg b/static/images/porch/flowchart.drawio.svg similarity index 100% rename from static/images/flowchart.drawio.svg rename to static/images/porch/flowchart.drawio.svg diff --git a/static/images/upgrade.drawio.svg b/static/images/porch/upgrade.drawio.svg similarity index 100% rename from static/images/upgrade.drawio.svg rename to static/images/porch/upgrade.drawio.svg From dd0a1a99306f91fea4a1040970b99bca2c775d61 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Mon, 17 Nov 2025 15:34:16 +0000 Subject: [PATCH 10/16] better schemas and tables Signed-off-by: lapentafd --- .../upgrading-packages.md | 95 ++++++++++++++----- static/images/porch/flowchart.drawio.svg | 2 +- static/images/porch/upgrade.drawio.svg | 2 +- 3 files changed, 75 insertions(+), 24 deletions(-) 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 4e2b8b06..b017ecbb 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 @@ -9,12 +9,10 @@ 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" %}}). -## Table of Contents +## Prerequisetes -- [Key Concepts](#key-concepts) -- [End-to-End Upgrade Example](#end-to-end-upgrade-example) -- [Understanding Merge Strategies](#understanding-merge-strategies) -- [Reference](#reference) +* 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 @@ -133,34 +131,87 @@ The outcome of an upgrade depends on the changes made in the upstream blueprint ### 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. | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Scenarioresource-merge (Default)copy-mergeforce-delete-replacefast-forward
File added in UpstreamFile is added to Local.File is added to Local.File is added to Local.Fails (Local must be unchanged).
File modified in Upstream onlyChanges are applied to Local.Upstream file overwrites Local file.Upstream file overwrites Local file.Fails (Local must be unchanged).
File modified in Local onlyLocal 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 UpstreamFile is deleted from Local.File is deleted from Local.File is deleted from Local.Fails (Local must be unchanged).
Local package is unmodifiedUpgrade succeeds.Upgrade succeeds.Upgrade succeeds.Upgrade succeeds.
### Detailed Strategy Explanations -#### `resource-merge` (Default) +#### **resource-merge (Default)** This is a structural 3-way merge designed for Kubernetes resources. It understands the structure of YAML files and attempts to intelligently merge changes from the upstream and local packages. * **When to use:** This is the **recommended default strategy** for managing Kubernetes configuration. Use it when you want to preserve local customizations while incorporating upstream updates. -#### `copy-merge` +#### **copy-merge** A file-level replacement strategy. For any file present in both local and upstream, the upstream version is used, overwriting local changes. Files that only exist locally are kept. * **When to use:** When you trust the upstream source more than local changes or when Porch cannot parse the file contents (e.g., non-KRM files). -#### `force-delete-replace` +#### **force-delete-replace** The most aggressive strategy. It completely discards the local package's contents and replaces them with the contents of the new upstream package. * **When to use:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations. -#### `fast-forward` +#### **fast-forward** A fail-fast safety check. The upgrade only succeeds if the local package has **zero modifications** compared to the original blueprint version it was cloned from. * **When to use:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. @@ -169,7 +220,7 @@ A fail-fast safety check. The upgrade only succeeds if the local package has **z This section contains short, focused examples showing how each merge strategy behaves in realistic scenarios. Each example assumes you have a deployment package `porch-test.deployment.1` cloned from `porch-test.blueprint.1` and that `porch-test.blueprint.2` is available upstream. -### Example A — `resource-merge` (default) +### Example A — resource-merge (default) Scenario: Upstream adds a new ConfigMap and local changes added an annotation to Kptfile. `resource-merge` should apply the upstream addition while preserving the local annotation. @@ -187,7 +238,7 @@ porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision= Outcome: A new draft `porch-test.deployment.2` is created containing both the new `ConfigMap` and the local annotation. -### Example B — `copy-merge` +### Example B — copy-merge Scenario: Upstream changes a file that the local package also modified, but you want the upstream version to win (file-level overwrite). @@ -199,7 +250,7 @@ porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision= Outcome: Files present in both upstream and local are replaced with the upstream copy. Files only present locally are preserved. -### Example C — `force-delete-replace` +### Example C — force-delete-replace Scenario: The blueprint has diverged substantially; you want to reset the deployment package to exactly match upstream v2. @@ -211,7 +262,7 @@ porchctl rpkg upgrade porch-test.deployment.1 --namespace=porch-demo --revision= Outcome: The new draft contains only the upstream contents; local customizations are discarded. -### Example D — `fast-forward` +### Example D — fast-forward Scenario: You want to ensure upgrades are only applied to unmodified, pristine clones. diff --git a/static/images/porch/flowchart.drawio.svg b/static/images/porch/flowchart.drawio.svg index 8ef79e65..ffb07bad 100644 --- a/static/images/porch/flowchart.drawio.svg +++ b/static/images/porch/flowchart.drawio.svg @@ -1,4 +1,4 @@ -
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file +
Initialize Package
Pull Latest Version
Make Changes Locally
Push Changes
Propose Changes
(Create Pull Request)
Review
Approved
Published / Becomes Latest
Rejected
Changes Required
 \ No newline at end of file diff --git a/static/images/porch/upgrade.drawio.svg b/static/images/porch/upgrade.drawio.svg index 336c7937..5637ad50 100644 --- a/static/images/porch/upgrade.drawio.svg +++ b/static/images/porch/upgrade.drawio.svg @@ -1,4 +1,4 @@ -
Blueprint.v1
Blueprint.v2
Deployment.v1
Deployment.v2
1.CLONE
2.COPY
3.UPGRADE
Using the new blueprint
Blueprints repository
Deployments repository
 \ No newline at end of file +
Blueprint.v1
Blueprint.v2
Deployment.v1
Deployment.v2
1.CLONE
2.COPY
3.UPGRADE
Using the new blueprint
Blueprints repository
Deployments repository
 \ No newline at end of file From 663cf3608cca350f4ef8174534414322bd708f1b Mon Sep 17 00:00:00 2001 From: lapentafd Date: Mon, 17 Nov 2025 15:38:25 +0000 Subject: [PATCH 11/16] qtypo Signed-off-by: lapentafd --- .../neo-porch/4_tutorials_and_how-tos/upgrading-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 b017ecbb..7561fbcd 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 @@ -9,7 +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" %}}). -## Prerequisetes +## 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" %}}) From ca860667ff35a93eb9ebb08d8f5aa575efe31c22 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Mon, 17 Nov 2025 15:40:18 +0000 Subject: [PATCH 12/16] use case Signed-off-by: lapentafd --- .../4_tutorials_and_how-tos/upgrading-packages.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 7561fbcd..94ff04fb 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 @@ -199,22 +199,22 @@ The outcome of an upgrade depends on the changes made in the upstream blueprint #### **resource-merge (Default)** This is a structural 3-way merge designed for Kubernetes resources. It understands the structure of YAML files and attempts to intelligently merge changes from the upstream and local packages. -* **When to use:** This is the **recommended default strategy** for managing Kubernetes configuration. Use it when you want to preserve local customizations while incorporating upstream updates. +* **Use case:** This is the **recommended default strategy** for managing Kubernetes configuration. Use it when you want to preserve local customizations while incorporating upstream updates. #### **copy-merge** A file-level replacement strategy. For any file present in both local and upstream, the upstream version is used, overwriting local changes. Files that only exist locally are kept. -* **When to use:** When you trust the upstream source more than local changes or when Porch cannot parse the file contents (e.g., non-KRM files). +* **Use case:** When you trust the upstream source more than local changes or when Porch cannot parse the file contents (e.g., non-KRM files). #### **force-delete-replace** The most aggressive strategy. It completely discards the local package's contents and replaces them with the contents of the new upstream package. -* **When to use:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations. +* **Use case:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations. #### **fast-forward** A fail-fast safety check. The upgrade only succeeds if the local package has **zero modifications** compared to the original blueprint version it was cloned from. -* **When to use:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. +* **Use case:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. ## Practical examples: upgrade strategies in action From f52560bd54620120e1f1bbbfa8bd4b7209cd7eec Mon Sep 17 00:00:00 2001 From: lapentafd Date: Wed, 19 Nov 2025 14:18:48 +0000 Subject: [PATCH 13/16] added step-by-step schema Signed-off-by: lapentafd --- .../upgrading-packages.md | 56 +++++++++++++++++-- static/images/porch/upgrade-step1.drawio.svg | 4 ++ static/images/porch/upgrade-step2.drawio.svg | 4 ++ static/images/porch/upgrade-step3.drawio.svg | 4 ++ static/images/porch/upgrade-step4.drawio.svg | 4 ++ 5 files changed, 66 insertions(+), 6 deletions(-) create mode 100644 static/images/porch/upgrade-step1.drawio.svg create mode 100644 static/images/porch/upgrade-step2.drawio.svg create mode 100644 static/images/porch/upgrade-step3.drawio.svg create mode 100644 static/images/porch/upgrade-step4.drawio.svg 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 94ff04fb..e7bd3b65 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 @@ -35,18 +35,24 @@ Create the initial revision of our blueprint. This will be the "upstream" source ```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 -``` -```bash # Propose the draft for review porchctl rpkg propose porch-test.blueprint.1 --namespace=porch-demo -``` -```bash # Approve and publish the package, making it available as revision 1 porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo ``` +![Step 1: Create Base Blueprint](/images/porch/upgrade-step1.drawio.svg) + +**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. @@ -70,6 +76,17 @@ 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). +![Step 2: Create New Blueprint Revision](/images/porch/upgrade-step2.drawio.svg) + +**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. @@ -92,6 +109,19 @@ porchctl rpkg propose porch-test.deployment.1 --namespace=porch-demo porchctl rpkg approve porch-test.deployment.1 --namespace=porch-demo ``` +![Step 3: Clone Blueprint into Deployment Package](/images/porch/upgrade-step3.drawio.svg) + +**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. @@ -114,6 +144,20 @@ After approval, `porch-test.deployment.2` is the new, published deployment packa 1. The `new-configmap.yaml` from the upstream `blueprint.2`. 2. The local `kpt.dev/annotation=true` customization applied in Step 3. +![Step 4: Discover and Perform Upgrade](/images/porch/upgrade-step4.drawio.svg) + +**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 ![Package Upgrade Flow](/static/images/porch/upgrade.drawio.svg) @@ -300,8 +344,8 @@ To remove the packages created in this guide, you must first propose them for de rm -rf ./tmp # Propose all packages for deletion -porchctl rpkg propose-delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo +porchctl rpkg propose-delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 porch-test.blueprint.main porch-test.deployment.main --namespace=porch-demo # Delete the packages -porchctl rpkg delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 --namespace=porch-demo +porchctl rpkg delete porch-test.blueprint.1 porch-test.blueprint.2 porch-test.deployment.1 porch-test.deployment.2 porch-test.blueprint.main porch-test.deployment.main --namespace=porch-demo ``` diff --git a/static/images/porch/upgrade-step1.drawio.svg b/static/images/porch/upgrade-step1.drawio.svg new file mode 100644 index 00000000..756e3f9e --- /dev/null +++ b/static/images/porch/upgrade-step1.drawio.svg @@ -0,0 +1,4 @@ + + + +
Blueprint.v1
Blueprints repository
 \ No newline at end of file diff --git a/static/images/porch/upgrade-step2.drawio.svg b/static/images/porch/upgrade-step2.drawio.svg new file mode 100644 index 00000000..02f9c91c --- /dev/null +++ b/static/images/porch/upgrade-step2.drawio.svg @@ -0,0 +1,4 @@ + + + +
Blueprint.v1
Blueprint.v2
COPY
Blueprints repository
 \ No newline at end of file diff --git a/static/images/porch/upgrade-step3.drawio.svg b/static/images/porch/upgrade-step3.drawio.svg new file mode 100644 index 00000000..c950bd81 --- /dev/null +++ b/static/images/porch/upgrade-step3.drawio.svg @@ -0,0 +1,4 @@ + + + +
Blueprint.v1
Blueprint.v2
Deployment.v1
CLONE
Blueprints repository
Deployments repository
 \ No newline at end of file diff --git a/static/images/porch/upgrade-step4.drawio.svg b/static/images/porch/upgrade-step4.drawio.svg new file mode 100644 index 00000000..6550dc83 --- /dev/null +++ b/static/images/porch/upgrade-step4.drawio.svg @@ -0,0 +1,4 @@ + + + +
Blueprint.v1
Blueprint.v2
Deployment.v1
Deployment.v2
UPGRADE
Using the new blueprint
Blueprints repository
Deployments repository
 \ No newline at end of file From ce58ed6e30f35a67460b5d238b026e93440afdcf Mon Sep 17 00:00:00 2001 From: lapentafd Date: Wed, 19 Nov 2025 14:33:10 +0000 Subject: [PATCH 14/16] css style for table Signed-off-by: lapentafd --- .../upgrading-packages.md | 84 +++++++++---------- 1 file changed, 42 insertions(+), 42 deletions(-) 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 e7bd3b65..5ba3456e 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 @@ -175,65 +175,65 @@ The outcome of an upgrade depends on the changes made in the upstream blueprint ### Merge Strategy Comparison - - +
+ - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + +
Scenarioresource-merge (Default)copy-mergeforce-delete-replacefast-forwardScenarioresource-merge (Default)copy-mergeforce-delete-replacefast-forward
File added in UpstreamFile is added to Local.File is added to Local.File is added to Local.Fails (Local must be unchanged).File added in UpstreamFile is added to Local.File is added to Local.File is added to Local.Fails (Local must be unchanged).
File modified in Upstream onlyChanges are applied to Local.Upstream file overwrites Local file.Upstream file overwrites Local file.Fails (Local must be unchanged).File modified in Upstream onlyChanges are applied to Local.Upstream file overwrites Local file.Upstream file overwrites Local file.Fails (Local must be unchanged).
File modified in Local onlyLocal changes are kept.Local changes are kept.Local changes are discarded; Upstream version is used.Fails (Local must be unchanged).File modified in Local onlyLocal 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 (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 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 UpstreamFile is deleted from Local.File is deleted from Local.File is deleted from Local.Fails (Local must be unchanged).File deleted in UpstreamFile is deleted from Local.File is deleted from Local.File is deleted from Local.Fails (Local must be unchanged).
Local package is unmodifiedUpgrade succeeds.Upgrade succeeds.Upgrade succeeds.Upgrade succeeds.Local package is unmodifiedUpgrade succeeds.Upgrade succeeds.Upgrade succeeds.Upgrade succeeds.
From 8720bdead6a56baedbfd6e9c4a17c7ac4ed867d8 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Thu, 20 Nov 2025 11:02:44 +0000 Subject: [PATCH 15/16] alert style Signed-off-by: lapentafd --- content/en/docs/neo-porch/4_tutorials_and_how-tos/_index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 365d7d28..e370aff4 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 @@ -7,4 +7,6 @@ description: Tutorials in Porch ## Overview -> Note: 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: [Local Development Environment Setup]({{% relref "/docs/neo-porch/6_configuration_and_deployments/deployments/local-dev-env-deployment.md" %}}). +{{% 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 %}} From fef75cad12e960a4acc6b0924d0786198507be62 Mon Sep 17 00:00:00 2001 From: lapentafd Date: Thu, 20 Nov 2025 11:12:59 +0000 Subject: [PATCH 16/16] linkinspector links fix Signed-off-by: lapentafd --- .../4_tutorials_and_how-tos/upgrading-packages.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 5ba3456e..47194a7d 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 @@ -43,7 +43,7 @@ porchctl rpkg propose porch-test.blueprint.1 --namespace=porch-demo porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo ``` -![Step 1: Create Base Blueprint](/images/porch/upgrade-step1.drawio.svg) +![Step 1: Create Base Blueprint](/static/images/porch/upgrade-step1.drawio.svg) **PackageRevisions State After Step 1:** ```bash @@ -76,7 +76,7 @@ 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). -![Step 2: Create New Blueprint Revision](/images/porch/upgrade-step2.drawio.svg) +![Step 2: Create New Blueprint Revision](/static/images/porch/upgrade-step2.drawio.svg) **PackageRevisions State After Step 2:** ```bash @@ -109,7 +109,7 @@ porchctl rpkg propose porch-test.deployment.1 --namespace=porch-demo porchctl rpkg approve porch-test.deployment.1 --namespace=porch-demo ``` -![Step 3: Clone Blueprint into Deployment Package](/images/porch/upgrade-step3.drawio.svg) +![Step 3: Clone Blueprint into Deployment Package](/static/images/porch/upgrade-step3.drawio.svg) **PackageRevisions State After Step 3:** ```bash @@ -144,7 +144,7 @@ After approval, `porch-test.deployment.2` is the new, published deployment packa 1. The `new-configmap.yaml` from the upstream `blueprint.2`. 2. The local `kpt.dev/annotation=true` customization applied in Step 3. -![Step 4: Discover and Perform Upgrade](/images/porch/upgrade-step4.drawio.svg) +![Step 4: Discover and Perform Upgrade](/static/images/porch/upgrade-step4.drawio.svg) **PackageRevisions State After Step 4:** ```bash