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..365d7d283 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.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 829952d23..4f00d7f12 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](/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 548f1661f..034986ae6 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,256 @@ --- -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] … +## 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 (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 +``` + +```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 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). + +### 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 +``` + +### 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 + +![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 + +| 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. + +## 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: + +```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 +``` + +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 + +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/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 d2e8e06cf..e1ede2bc6 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,91 @@ --- -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) + +## 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` diff --git a/static/images/flowchart.drawio.svg b/static/images/flowchart.drawio.svg new file mode 100644 index 000000000..8ef79e651 --- /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 000000000..336c79373 --- /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