From d6fe1fdc89b9ce74908cce4fbddd1d1b2d13e3a6 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 4 Dec 2025 16:07:33 +0000 Subject: [PATCH 1/3] Adding PackageRevision copying guide --- .../copying-packages.md | 299 +++++++++++++++++- 1 file changed, 294 insertions(+), 5 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md index d2f153ff..e761a508 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md @@ -1,10 +1,299 @@ --- -title: "Copying Packages" +title: "Copying Package Revisions" type: docs -weight: 6 -description: +weight: 4 +description: "A step by step guide to copying package revisions in Porch" --- -## Lorem Ipsum +## Prerequisites -tutorial in copying packges, how copying works regarding upstream downstream, when you can and should copy, when not to copy, impacts of copying etc etc. could again reffer back to the package-lifecycle diagram when its created. +- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). +- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}). +- **Kubectl** configured to access your cluster. +- At least one published PackageRevision to copy from. + +## Tutorial Overview + +You will learn how to: + +1. Find a PackageRevision to copy +2. Copy a PackageRevision to create a new revision +3. Modify the copied PackageRevision +4. Propose and approve the new revision + +{{% alert title="Understanding Terminology" color="primary" %}} +In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package". +{{% /alert %}} + +--- + +{{% alert title="Note" color="primary" %}} +Please note the tutorial assumes a porch repository is initialized with the "porch-test" name. +We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. +{{% /alert %}} + +## When to Use Copy + +**Use `porchctl rpkg copy` when:** + +- You need to create a new version of a published PackageRevision (published revisions are immutable) +- You want to create variations of a package within the same repository +- You need an independent copy with no upstream relationship +- You're iterating on a package and need a new workspace +- Source and target are in the **same repository** + +**Do NOT use copy when:** + +- You need to move a package to a **different repository** - use `porchctl rpkg clone` instead +- You want to maintain an upstream relationship for updates - use `porchctl rpkg clone` instead +- You're importing blueprints from a central repository - use `porchctl rpkg clone` instead + +{{% alert title="Note" color="primary" %}} +For cross-repository operations or maintaining upstream relationships, see [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md" %}}). +{{% /alert %}} + +--- + +## Understanding Copy Operations + +Copying creates a new PackageRevision based on an existing one **within the same repository**. The copied PackageRevision is completely independent with no upstream link to the source. + +--- + +## Step 1: Find a PackageRevision to Copy + +First, list available PackageRevisions to find one to copy: + +```bash +porchctl rpkg get --namespace default +``` + +**Example output:** + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-app.v1 my-app v1 1 true Published porch-test +blueprints.nginx.main nginx main 5 true Published blueprints +``` + +**What to look for:** + +- Published PackageRevisions are good candidates for copying +- Note the full NAME (e.g., `porch-test.my-app.v1`) +- Check the LATEST column to find the most recent version + +--- + +## Step 2: Copy the PackageRevision + +Copy an existing PackageRevision to create a new one: + +```bash +porchctl rpkg copy \ + porch-test.my-app.v1 \ + my-app \ + --namespace default \ + --workspace v2 +``` + +**What this does:** + +- Creates a new PackageRevision based on `porch-test.my-app.v1` +- Names the new PackageRevision `my-app` (package name) +- Uses `v2` as the workspace name (must be unique within the package) +- Starts in `Draft` lifecycle state +- Copies all resources from the source PackageRevision + +**Verify the copy was created:** + +```bash +porchctl rpkg get --namespace default --name my-app +``` + +**Example output:** + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-app.v1 my-app v1 1 true Published porch-test +porch-test.my-app.v2 my-app v2 0 false Draft porch-test +``` + +--- + +## Step 3: Modify the Copied PackageRevision + +After copying, you can modify the new PackageRevision. Pull it locally: + +```bash +porchctl rpkg pull porch-test.my-app.v2 ./my-app-v2 --namespace default +``` + +**Make your changes:** + +```bash +vim ./my-app-v2/Kptfile +``` + +For example, update the description: + +```yaml +apiVersion: kpt.dev/v1 +kind: Kptfile +metadata: + name: my-app + annotations: + config.kubernetes.io/local-config: "true" +info: + description: My app version 2 with improvements +pipeline: + mutators: + - image: gcr.io/kpt-fn/set-namespace:v0.4.1 + configMap: + namespace: production +``` + +**Push the changes back:** + +```bash +porchctl rpkg push porch-test.my-app.v2 ./my-app-v2 --namespace default +``` + +--- + +## Step 4: Propose and Approve + +Once you're satisfied with the changes, propose the PackageRevision: + +```bash +porchctl rpkg propose porch-test.my-app.v2 --namespace default +``` + +**Verify the state change:** + +```bash +porchctl rpkg get porch-test.my-app.v2 --namespace default +``` + +**Example output:** + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-app.v2 my-app v2 0 false Proposed porch-test +``` + +**Approve to publish:** + +```bash +porchctl rpkg approve porch-test.my-app.v2 --namespace default +``` + +**Verify publication:** + +```bash +porchctl rpkg get --namespace default --name my-app +``` + +**Example output:** + +```bash +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.my-app.v1 my-app v1 1 false Published porch-test +porch-test.my-app.v2 my-app v2 2 true Published porch-test +``` + +Notice: + +- `v2` now has revision number `2` +- `v2` is marked as `LATEST` +- `v1` is no longer the latest + +--- + +{{% alert title="Note" color="primary" %}} +For complete details on the `porchctl rpkg copy` command options and flags, see the [Porch CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). +{{% /alert %}} + +--- + +## Common Use Cases + +Here are practical scenarios where copying PackageRevisions is useful. + +### Creating a New Version + +When you need to update a published PackageRevision: + +```bash +# Copy the latest published version +porchctl rpkg copy porch-test.my-app.v2 my-app --namespace default --workspace v3 + +# Make changes +porchctl rpkg pull porch-test.my-app.v3 ./my-app-v3 --namespace default +# ... edit files ... +porchctl rpkg push porch-test.my-app.v3 ./my-app-v3 --namespace default + +# Publish +porchctl rpkg propose porch-test.my-app.v3 --namespace default +porchctl rpkg approve porch-test.my-app.v3 --namespace default +``` + +### Creating Environment-Specific Workspaces + +Create different workspace variations of the same base PackageRevision: + +```bash +# Copy for development environment +porchctl rpkg copy porch-test.my-app.v1 my-app --namespace default --workspace dev + +# Copy for staging environment +porchctl rpkg copy porch-test.my-app.v1 my-app --namespace default --workspace staging + +# Copy for production environment +porchctl rpkg copy porch-test.my-app.v1 my-app --namespace default --workspace prod +``` + +--- + +## Troubleshooting + +Common issues when copying PackageRevisions and how to resolve them. + +**Copy fails with "workspace already exists"?** + +- The workspace name must be unique within the package +- Choose a different workspace name: `--workspace v3` or `--workspace dev-2` +- List existing workspaces: `porchctl rpkg get --namespace default --name ` + +**Copy fails with "source not found"?** + +- Verify the source PackageRevision exists: `porchctl rpkg get --namespace default` +- Check the exact name including repository, package, and workspace +- Ensure you have permission to read the source PackageRevision +- Ensure the source is in the same repository (copy only works within the same repository) + +**Copied PackageRevision has unexpected content?** + +- The copy includes all resources from the source at the time of copying +- Pull and inspect: `porchctl rpkg pull ./dir --namespace default` +- Make corrections and push back + +**Need to copy to a different repository?** + +- Use `porchctl rpkg clone` instead of `copy` +- The `clone` command supports the `--repository` flag for cross-repository operations +- See [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md" %}}) + +--- + +## Key Concepts + +- **Copy**: Creates a new independent PackageRevision within the same repository +- **Source PackageRevision**: The original PackageRevision being copied +- **Target PackageRevision**: The new PackageRevision created by the copy operation +- **Workspace**: Must be unique within the package for the target +- **Same-repository operation**: Copy only works within a single repository +- **Immutability**: Published PackageRevisions cannot be modified, only copied +- **Clone vs Copy**: Use clone for cross-repository operations, copy for same-repository versions + +--- From 40224f1ba638672a8295c2dbb888ce392a6d6e77 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Thu, 4 Dec 2025 16:31:33 +0000 Subject: [PATCH 2/3] rebasing with main and fixing links & structure --- .../copying-packages.md | 34 ++++++------------- 1 file changed, 11 insertions(+), 23 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md index e761a508..cf0e95d2 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md @@ -5,14 +5,6 @@ weight: 4 description: "A step by step guide to copying package revisions in Porch" --- -## Prerequisites - -- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). -- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/neo-porch/3_getting_started/installing-porch.md" %}}). -- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}}). -- **Kubectl** configured to access your cluster. -- At least one published PackageRevision to copy from. - ## Tutorial Overview You will learn how to: @@ -22,17 +14,19 @@ You will learn how to: 3. Modify the copied PackageRevision 4. Propose and approve the new revision -{{% alert title="Understanding Terminology" color="primary" %}} -In Porch, you work with **PackageRevisions** - there is no separate "Package" resource. When we say "package" colloquially, we're referring to a PackageRevision. The `rpkg` command stands for "revision package". -{{% /alert %}} - ---- - {{% alert title="Note" color="primary" %}} Please note the tutorial assumes a porch repository is initialized with the "porch-test" name. We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. {{% /alert %}} +--- + +## Understanding Copy Operations + +Copying creates a new PackageRevision based on an existing one **within the same repository**. The copied PackageRevision is completely independent with no upstream link to the source. + +--- + ## When to Use Copy **Use `porchctl rpkg copy` when:** @@ -50,17 +44,11 @@ We recommended to use this for simpler copy pasting of commands otherwise replac - You're importing blueprints from a central repository - use `porchctl rpkg clone` instead {{% alert title="Note" color="primary" %}} -For cross-repository operations or maintaining upstream relationships, see [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md" %}}). +For cross-repository operations or maintaining upstream relationships, see [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md" %}}). {{% /alert %}} --- -## Understanding Copy Operations - -Copying creates a new PackageRevision based on an existing one **within the same repository**. The copied PackageRevision is completely independent with no upstream link to the source. - ---- - ## Step 1: Find a PackageRevision to Copy First, list available PackageRevisions to find one to copy: @@ -222,7 +210,7 @@ Here are practical scenarios where copying PackageRevisions is useful. ### Creating a New Version -When you need to update a published PackageRevision: +When you need to update a published PackageRevision in the same Repository: ```bash # Copy the latest published version @@ -282,7 +270,7 @@ Common issues when copying PackageRevisions and how to resolve them. - Use `porchctl rpkg clone` instead of `copy` - The `clone` command supports the `--repository` flag for cross-repository operations -- See [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/cloning-packages.md" %}}) +- See [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md" %}}) --- From a97db46b7602b09e38189d453dee4ffd0fdf9f45 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Fri, 5 Dec 2025 16:18:26 +0000 Subject: [PATCH 3/3] amending comments --- .../copying-packages.md | 54 +++++++++---------- 1 file changed, 24 insertions(+), 30 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md index cf0e95d2..2b7e1fe6 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md @@ -15,15 +15,27 @@ You will learn how to: 4. Propose and approve the new revision {{% alert title="Note" color="primary" %}} -Please note the tutorial assumes a porch repository is initialized with the "porch-test" name. +The tutorial assumes a porch repository is initialized with the "porch-test" name. We recommended to use this for simpler copy pasting of commands otherwise replace any "porch-test" value with your repository's name in the below commands. {{% /alert %}} --- +## Key Concepts + +- **Copy**: Creates a new independent PackageRevision within the same repository +- **Source PackageRevision**: The original PackageRevision being copied +- **Target PackageRevision**: The new PackageRevision created by the copy operation +- **Workspace**: Must be unique within the package for the target +- **Same-repository operation**: Copy only works within a single repository +- **Immutability**: Published PackageRevisions cannot be modified, only copied +- **Clone vs Copy**: Use clone for cross-repository operations, copy for same-repository versions + +--- + ## Understanding Copy Operations -Copying creates a new PackageRevision based on an existing one **within the same repository**. The copied PackageRevision is completely independent with no upstream link to the source. +Copying creates a new PackageRevision based on an existing one **within the same repository**. The copied PackageRevision is completely **independent with no upstream link** to the source. --- @@ -44,7 +56,7 @@ Copying creates a new PackageRevision based on an existing one **within the same - You're importing blueprints from a central repository - use `porchctl rpkg clone` instead {{% alert title="Note" color="primary" %}} -For cross-repository operations or maintaining upstream relationships, see [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md" %}}). +For cross-repository operations or maintaining upstream relationships, see the [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md" %}}). {{% /alert %}} --- @@ -123,7 +135,7 @@ porchctl rpkg pull porch-test.my-app.v2 ./my-app-v2 --namespace default vim ./my-app-v2/Kptfile ``` -For example, update the description: +For example, you can update the description: ```yaml apiVersion: kpt.dev/v1 @@ -176,7 +188,7 @@ porch-test.my-app.v2 my-app v2 0 f porchctl rpkg approve porch-test.my-app.v2 --namespace default ``` -**Verify publication:** +**Verify the publication:** ```bash porchctl rpkg get --namespace default --name my-app @@ -190,7 +202,7 @@ porch-test.my-app.v1 my-app v1 1 f porch-test.my-app.v2 my-app v2 2 true Published porch-test ``` -Notice: +Notice the following changes: - `v2` now has revision number `2` - `v2` is marked as `LATEST` @@ -247,41 +259,23 @@ porchctl rpkg copy porch-test.my-app.v1 my-app --namespace default --workspace p Common issues when copying PackageRevisions and how to resolve them. -**Copy fails with "workspace already exists"?** +**Copy fails with "workspace already exists":** - The workspace name must be unique within the package - Choose a different workspace name: `--workspace v3` or `--workspace dev-2` -- List existing workspaces: `porchctl rpkg get --namespace default --name ` +- List existing workspaces with the `porchctl rpkg get --namespace default --name ` command -**Copy fails with "source not found"?** +**Copy fails with "source not found":** -- Verify the source PackageRevision exists: `porchctl rpkg get --namespace default` +- Verify that the source PackageRevision exists with the `porchctl rpkg get --namespace default` command - Check the exact name including repository, package, and workspace - Ensure you have permission to read the source PackageRevision - Ensure the source is in the same repository (copy only works within the same repository) -**Copied PackageRevision has unexpected content?** +**Copied PackageRevision has unexpected content:** - The copy includes all resources from the source at the time of copying -- Pull and inspect: `porchctl rpkg pull ./dir --namespace default` +- Pull and inspect with the `porchctl rpkg pull ./dir --namespace default` command - Make corrections and push back -**Need to copy to a different repository?** - -- Use `porchctl rpkg clone` instead of `copy` -- The `clone` command supports the `--repository` flag for cross-repository operations -- See [Cloning Package Revisions Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md" %}}) - ---- - -## Key Concepts - -- **Copy**: Creates a new independent PackageRevision within the same repository -- **Source PackageRevision**: The original PackageRevision being copied -- **Target PackageRevision**: The new PackageRevision created by the copy operation -- **Workspace**: Must be unique within the package for the target -- **Same-repository operation**: Copy only works within a single repository -- **Immutability**: Published PackageRevisions cannot be modified, only copied -- **Clone vs Copy**: Use clone for cross-repository operations, copy for same-repository versions - ---