diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md index a334864ea..b0ed077d6 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md @@ -7,9 +7,9 @@ description: A group of guides outlining how to interact with Package Revisions ## Prerequisites -- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/3_getting_started/installing-porch.md" %}}). -- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/3_getting_started/installing-porchctl.md" %}}). -- A Git repository registered with Porch [Setup Repositories Guide]({{% relref "/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}). +- Porch deployed on a Kubernetes cluster. See, [Setup Porch Guide]({{% relref "/docs/3_getting_started/installing-porch.md" %}}). +- **Porchctl** CLI tool installed. See, [Setup Porchctl Guide]({{% relref "/docs/3_getting_started/installing-porchctl.md" %}}). +- A Git repository registered with Porch. See, [Setup Repositories Guide]({{% relref "/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md" %}}). - **Kubectl** configured to access your cluster. --- @@ -27,12 +27,14 @@ PackageRevisions are Kubernetes resources that represent versioned collections o **PackageRevision Operations:** -- **Creation**: `init`, `clone`, `copy` - Create new PackageRevisions from scratch, existing packages, or new revisions -- **Inspection**: `get` - List and view PackageRevision information and metadata -- **Content Management**: `pull`, `push` - Move PackageRevision content between Git repositories and local filesystem -- **Lifecycle Management**: `propose`, `approve`, `reject` - Control PackageRevision workflow states -- **Upgrading**: `upgrade` - Create new revision upgrading downstream to more recent upstream package -- **Deletion**: `propose-delete`, `del` - Propose deletion of published PackageRevisions, then delete them +| Operation | Git Command | Description | +|----------------------|--------------------------------|-------------------------------------------------------------------------------| +| Creation | `init`, `clone`, `copy` | Create new PackageRevisions from scratch, existing packages, or new revisions | +| Inspection | `get` | List and view PackageRevision information and metadata | +| Content Management | `pull`, `push` | Move PackageRevision content between Git repositories and local filesystem | +| Lifecycle Management | `propose`, `approve`, `reject` | Control PackageRevision workflow states | +| Upgrading | `upgrade` | Create new revision upgrading downstream to more recent upstream package | +| Deletion | `propose-delete`, `del` | Propose deletion of published PackageRevisions, then delete them | --- @@ -44,36 +46,31 @@ PackageRevisions follow a structured lifecycle with three main states: - **Proposed**: Ready for review, contents are immutable. To make further changes, reject back to Draft. Revision number remains 0. - **Published**: Approved and immutable. Revision number increments to 1+. -**Lifecycle Transitions:** +PackageRevisions use the following lifecycle transitions: -1. **Draft → Proposed**: `porchctl rpkg propose` - Signal readiness for review -2. **Proposed → Published**: `porchctl rpkg approve` - Approve and make immutable -3. **Proposed → Draft**: `porchctl rpkg reject` - Return for more work - -**Additional States:** - -- **DeletionProposed**: PackageRevision marked for deletion, pending approval +| Transition | Command | Meaning | +|----------------------------------|--------------------------------|-------------------------------------| +| **Draft → Proposed** | `porchctl rpkg propose` | Signal readiness for review | +| **Proposed → Published** | `porchctl rpkg approve` | Approve and make immutable | +| **Proposed → Draft** | `porchctl rpkg reject` | Return for more work | +| **Published → DeletionProposed** | `porchctl rpkg propose-delete` | Mark for deletion, pending approval | +| **DeletionProposed → Published** | `porchctl rpkg reject` | Reject deletion proposal | --- ## PackageRevision Naming -Porch generates PackageRevision names automatically using a consistent format: +Porch generates PackageRevision names automatically using the `{repositoryName}.{packageName}.{workspaceName}` format. An example PackageRevision naming would be `porch-test.my-first-package.v1`. -- **Format**: `{repositoryName}.{packageName}.{workspaceName}` -- **Example**: `porch-test.my-first-package.v1` - -**Name Components:** +The name consists of the following components: - **Repository Name**: Name of the registered Git repository - **Package Name**: Logical name for the package (can have multiple revisions) - **Workspace Name**: Unique identifier within the package (maps to Git branch/tag) -**Important Notes:** - -- Workspace names must be unique within a package -- Multiple PackageRevisions can share the same package name with different workspaces -- Published PackageRevisions get tagged in Git using the workspace name +{{% alert title="Note" color="primary" %}} +Workspace names must be unique within a package. Multiple PackageRevisions can share the same package name with different workspaces and published PackageRevisions get tagged in Git using the workspace name. +{{% /alert %}} --- @@ -87,11 +84,7 @@ PackageRevisions contain structured configuration files that can be modified thr 2. **Modify**: Edit files locally using standard tools 3. **Push**: Upload changes back to Porch (triggers pipeline rendering) -**Pipeline Processing:** - -- KRM functions defined in the Kptfile automatically transform resources -- Functions run when PackageRevisions are pushed to Porch -- Common functions: set-namespace, apply-replacements, search-replace +KRM functions defined in the Kptfile automatically transform resources; they run when PackageRevisions are pushed to Porch. Common examples include `set-namespace`, `apply-replacements`, and `search-replace`. **Content Structure:** @@ -116,16 +109,9 @@ PackageRevisions are stored in Git repositories registered with Porch: - **Proposed**: Stored in `proposed/{workspace}` branch - **Published**: Tagged as `{workspace}` and stored in main branch -**Repository Types:** - -- **Blueprint Repositories**: Contain upstream package templates for cloning -- **Deployment Repositories**: Store deployment-ready packages (marked with `--deployment` flag) - -**Synchronization:** +Porch differentiates two types of repositories: "blueprint" and "deployment". Blueprint repositories are meant to contain upstream package templates for cloning, while deployment repositories should store deployment-ready packages. The latter are marked with the `--deployment` flag. -- Porch automatically syncs with Git repositories -- Manual sync: `porchctl repo sync ` -- Periodic sync can be configured with cron expressions +Porch automatically syncs with Git repositories, however you can perform a manual sync with the `porchctl repo sync ` command. You can also configure periodic sync with cron expressions. --- @@ -135,33 +121,33 @@ Common issues when working with PackageRevisions and their solutions: **PackageRevision stuck in Draft?** -- Check readiness conditions: `porchctl rpkg get -o yaml | grep -A 5 conditions` -- Verify all required fields are populated in the Kptfile -- Check for pipeline function errors in Porch server logs +- Check readiness conditions with the `porchctl rpkg get -o yaml | grep -A 5 conditions` command +- Verify that all required fields are populated in the Kptfile +- Check for pipeline function errors in the Porch server logs **Push fails with conflict?** -- Pull the latest version first: `porchctl rpkg pull ./dir` -- The PackageRevision may have been modified by someone else +- Pull the latest version first with the `porchctl rpkg pull ` command +- Check if the PackageRevision has been modified by someone else - Resolve conflicts locally and push again **Cannot modify Published PackageRevision?** - Published PackageRevisions are immutable by design -- Create a new revision using `porchctl rpkg copy` +- Create a new revision with the `porchctl rpkg copy` command - Use the copying workflow to create editable versions **PackageRevision not found?** -- Verify the exact PackageRevision name: `porchctl rpkg get --namespace default` -- Check you're using the correct namespace +- Verify the exact PackageRevision name with the `porchctl rpkg get --namespace default` command +- Check if you are using the correct namespace - Ensure the repository is registered and synchronized **Permission denied errors?** -- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default` -- Verify service account has proper roles for PackageRevision operations -- Ensure repository authentication is configured correctly +- Check RBAC permissions with the `kubectl auth can-i get packagerevisions -n default` command +- Verify that the service account has proper roles for PackageRevision operations +- Ensure the repository authentication is configured correctly **Errors about "placeholder package revision"?** @@ -172,10 +158,10 @@ Common issues when working with PackageRevisions and their solutions: **Pipeline functions failing?** -- Check function image availability and version -- Verify function configuration in Kptfile -- Review function logs in Porch server output during push operations -- **To save work-in-progress despite failures**: Add `porch.kpt.dev/push-on-render-failure: "true"` annotation to the PackageRevision +- Check the function image availability and version +- Verify the function configuration in Kptfile +- Review the function logs in the Porch server output during push operations +- To save work-in-progress despite failures, add the `porch.kpt.dev/push-on-render-failure: "true"` annotation to the PackageRevision ```bash kubectl annotate packagerevision porch.kpt.dev/push-on-render-failure=true ``` diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md index 7eabfd515..c230bcb7d 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/cloning-packages.md @@ -58,7 +58,7 @@ First, list available PackageRevisions to find one to clone: porchctl rpkg get --namespace default ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -67,11 +67,7 @@ blueprints.wordpress.v1 wordpress v1 3 t deployments.my-app.v1 my-app v1 1 true Published deployments ``` -**What to look for:** - -- Published PackageRevisions from blueprint repositories are good candidates for cloning -- Note the full NAME (e.g., `blueprints.nginx.main`) -- Check the REPOSITORY column to identify the source repository +Look for published PackageRevisions from blueprint repositories that are good candidates for cloning. Note the full NAME (e.g., `blueprints.nginx.main`) and check the REPOSITORY column to identify the source repository. --- @@ -88,22 +84,15 @@ porchctl rpkg clone \ --workspace v1 ``` -**What this does:** - -- Creates a new PackageRevision based on `blueprints.nginx.main` -- Names the new PackageRevision `my-nginx` (package name) -- Places it in the `deployments` repository (different from source) -- Uses `v1` as the workspace name -- Starts in `Draft` lifecycle state -- Maintains an upstream reference to `blueprints.nginx.main` +This command creates a new PackageRevision based on `blueprints.nginx.main` and names the new PackageRevision `my-nginx` (package name). The package is placed in the `deployments` repository (different from source) and receives `v1` as the workspace name. This PackageRevision starts in `Draft` lifecycle state. An upstream reference to `blueprints.nginx.main` is maintained. -**Verify the clone was created:** +Verify the clone was created: ```bash porchctl rpkg get --namespace default --name my-nginx ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -120,7 +109,7 @@ After cloning, you can modify the new PackageRevision. Pull it locally: porchctl rpkg pull deployments.my-nginx.v1 ./my-nginx --namespace default ``` -**Make your changes:** +Make your changes: ```bash vim ./my-nginx/Kptfile @@ -150,7 +139,7 @@ pipeline: namespace: production ``` -**Push the changes back:** +Push the changes back: ```bash porchctl rpkg push deployments.my-nginx.v1 ./my-nginx --namespace default @@ -166,32 +155,32 @@ Once you're satisfied with the changes, propose the PackageRevision: porchctl rpkg propose deployments.my-nginx.v1 --namespace default ``` -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get deployments.my-nginx.v1 --namespace default ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments.my-nginx.v1 my-nginx v1 0 false Proposed deployments ``` -**Approve to publish:** +Approve to publish: ```bash porchctl rpkg approve deployments.my-nginx.v1 --namespace default ``` -**Verify publication:** +Verify publication: ```bash porchctl rpkg get deployments.my-nginx.v1 --namespace default ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -259,13 +248,13 @@ Common issues when cloning PackageRevisions and how to resolve them. **Clone fails with "repository not found"?** -- Verify the target repository exists: `porchctl repo get --namespace default` -- Check the repository name is correct +- Verify the target repository exists with the `porchctl repo get --namespace default` command +- Check that the repository name is correct - Ensure you have permission to write to the target repository **Clone fails with "source not found"?** -- Verify the source PackageRevision exists: `porchctl rpkg get --namespace default` +- Verify 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 @@ -278,19 +267,19 @@ Common issues when cloning PackageRevisions and how to resolve them. **Clone fails with "workspace already exists"?** - The workspace name must be unique within the package in the target repository -- Choose a different workspace name: `--workspace v2` or `--workspace prod` -- List existing workspaces: `porchctl rpkg get --namespace default --name ` +- Choose a different workspace name, `--workspace v2` or `--workspace prod` +- List existing workspaces with the `porchctl rpkg get --namespace default --name ` command **Cloned PackageRevision has unexpected content?** - The clone includes all resources from the source at the time of cloning -- 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 clone within the same repository?** - Use `porchctl rpkg copy` instead of `clone` for same-repository operations -- The `copy` command is simpler and doesn't maintain upstream references +- The `copy` command is simpler and does not maintain upstream references - See [Copying Package Revisions Guide]({{% relref "/docs/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md" %}}) --- diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md index 6f28ce63b..8fe107b3a 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/copying-packages.md @@ -69,7 +69,7 @@ First, list available PackageRevisions to find one to copy: porchctl rpkg get --namespace default ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -77,11 +77,7 @@ porch-test.my-app.v1 my-app v1 1 t 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 +Look for published PackageRevisions that are good candidates for copying. Note the full NAME (e.g., `porch-test.my-app.v1`) and check the LATEST column to find the most recent version. --- @@ -91,27 +87,20 @@ Copy an existing PackageRevision to create a new one: ```bash porchctl rpkg copy \ - porch-test.my-app.v1 \ - my-app \ - --namespace default \ - --workspace v2 +porch-test.my-app.v1 \ +--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 +This command creates a new PackageRevision based on `porch-test.my-app.v1` for the package `my-app` with `v2` as the workspace name (must be unique within the package). This PackageRevision starts in `Draft` lifecycle state. The command copies all resources from the source PackageRevision. -**Verify the copy was created:** +Verify the copy was created: ```bash porchctl rpkg get --namespace default --name my-app ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -129,7 +118,7 @@ After copying, you can modify the new PackageRevision. Pull it locally: porchctl rpkg pull porch-test.my-app.v2 ./my-app-v2 --namespace default ``` -**Make your changes:** +Make your changes: ```bash vim ./my-app-v2/Kptfile @@ -153,7 +142,7 @@ pipeline: namespace: production ``` -**Push the changes back:** +Push the changes back: ```bash porchctl rpkg push porch-test.my-app.v2 ./my-app-v2 --namespace default @@ -169,32 +158,32 @@ Once you're satisfied with the changes, propose the PackageRevision: porchctl rpkg propose porch-test.my-app.v2 --namespace default ``` -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get porch-test.my-app.v2 --namespace default ``` -**Example output:** +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:** +Approve to publish: ```bash porchctl rpkg approve porch-test.my-app.v2 --namespace default ``` -**Verify the publication:** +Verify the publication: ```bash porchctl rpkg get --namespace default --name my-app ``` -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -262,7 +251,7 @@ 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` +- Choose a different workspace name, `--workspace v3` or `--workspace dev-2` - List existing workspaces with the `porchctl rpkg get --namespace default --name ` command **Copy fails with "source not found":** @@ -270,7 +259,7 @@ Common issues when copying PackageRevisions and how to resolve them. - 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) +- Ensure the source is in the same repository, as copy only works within the same repository **Copy fails with "source revision may not be the placeholder package revision":** diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md index 45c3e15bb..b42de25fe 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/creating-packages.md @@ -19,8 +19,8 @@ You will learn how to: --- {{% 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. +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 %}} ## Step 1: Initialize Your First Package Revision @@ -35,16 +35,11 @@ porchctl rpkg init my-first-package \ --description="My first Porch package" ``` -**What this does:** - -- Creates a new PackageRevision named `my-first-package` -- Places it in the `porch-test` repository -- Uses `v1` as the workspace name (must be unique within this package) -- Starts in `Draft` lifecycle state +This command creates a new package named `my-first-package` in the `porch-test` repository, initializing a PackageRevision with the workspace name of `v1` (this must be unique within this package). The PackageRevision starts in `Draft` lifecycle state. ![Diagram](/static/images/porch/guides/init-workflow.drawio.svg) -**Verify the package revision was created:** +Verify the package revision was created: ```bash porchctl rpkg get --namespace default @@ -67,24 +62,17 @@ Download the package revision contents to your local filesystem: porchctl rpkg pull porch-test.my-first-package.v1 ./my-first-package --namespace default ``` -**What this does:** - -- Fetches all resources from the PackageRevision -- Saves them to the `./my-first-package` directory -- Includes the Kptfile and any other resources +This command fetches all resources from the PackageRevision and saves them to the `./my-first-package` directory. This includes the Kptfile and all other resources. ![Diagram](/static/images/porch/guides/pull-workflow.drawio.svg) -**Explore the package revision contents:** +Explore the package revision contents: ```bash ls -al ./my-first-package ``` -You'll see: - -- The `Kptfile` - PackageRevision metadata and pipeline configuration -- Other YAML files (if any were created) +You should see the `Kptfile`, which contains Package metadata and pipeline configuration, as well as the `.KptRevisionMetadata` file, which contains PackageRevision metadata. Additionally, you should see other YAML files, if any were created. ```bash total 24 @@ -96,9 +84,7 @@ drwxr-xr-x 4 user user 4096 Nov 24 13:27 .. -rw-r--r-- 1 user user 148 Nov 24 13:27 package-context.yaml ``` -**Alternatively:** - -If you have the tree command installed on your system you can use it to view the hierarchy of the package +Alternatively, if you have the tree command installed on your system you can use it to view the hierarchy of the package ```bash tree ./my-first-package/ @@ -119,9 +105,7 @@ my-first-package/ ## Step 3: Modify the Package Revision -Let's add a simple KRM function to the pipeline. - -Open the `Kptfile` in your editor of choice: +Let's add a simple KRM function to the pipeline. Open the `Kptfile` in your editor of choice: ```bash vim ./my-first-package/Kptfile @@ -145,21 +129,15 @@ pipeline: namespace: production ``` -**What this does:** - -- Adds a `set-namespace` function to the pipeline -- This function will set the namespace to `production` for all resources -- These Functions are not rendered until the package is "pushed" to porch +This edit adds a `set-namespace` function to the pipeline. This function will set the namespace to `production` for all resources. The functions are not rendered until the package is "pushed" to Porch. -**Add new resource:** - -Create a new configmap: +Add new resource. First, create a new configmap: ```bash vim ./my-first-package/test-config.yaml ``` -Now add the following content to this new configmap +Then add the following content to this new configmap: ```yaml apiVersion: v1 @@ -170,7 +148,7 @@ data: key: "value" ``` -**Save and close the file.** +Save and close the file. {{% alert title="Note" color="primary" %}} Changes are LOCAL ONLY (Porch doesn't know about them yet) at this stage @@ -186,17 +164,11 @@ Upload your modified package revision back to Porch: porchctl rpkg push porch-test.my-first-package.v1 ./my-first-package --namespace default ``` -**What this does:** - -- Updates the PackageRevision in Porch -- Triggers rendering (executes pipeline functions) -- PackageRevision remains in `Draft` state +This command updates the PackageRevision in Porch and triggers rendering (executes pipeline functions). The PackageRevision remains in `Draft` state. ![Diagram](/static/images/porch/guides/push-workflow.drawio.svg) -**Successful output:** - -This describes how the KRM function was run by porch and has updated the namespace in our new configmap. +Successful output should look like a following. This describes how the KRM function was run by Porch and has updated the namespace in our new configmap. ```bash [RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" @@ -216,11 +188,7 @@ Move the package revision to `Proposed` state for review: porchctl rpkg propose porch-test.my-first-package.v1 --namespace default ``` -**What this does:** - -- Changes lifecycle from `Draft` to `Proposed` -- Signals the package revision is ready for review -- Package revision contents can no longer be modified directly; to make further changes, the proposal must first be rejected back to `Draft` +This command changes lifecycle from `Draft` to `Proposed` and signals that the package revision is ready for review. After this, the package revision contents can no longer be modified directly. To make further changes, you must first reject the proposal back to `Draft`. ![Diagram](/static/images/porch/guides/propose-workflow.drawio.svg) @@ -228,7 +196,7 @@ porchctl rpkg propose porch-test.my-first-package.v1 --namespace default A lifecycle state change from `Draft` to `Proposed` means that in Git the package revision has moved from the `draft` branch to the `proposed` branch {{% /alert %}} -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get porch-test.my-first-package.v1 --namespace default @@ -251,22 +219,17 @@ If the package revision looks good, approve it to publish: porchctl rpkg approve porch-test.my-first-package.v1 --namespace default ``` -**What this does:** - -- Changes PackageRevision lifecycle from `Proposed` (revision 0) to `Published` (revision 1) -- PackageRevision becomes **immutable** (content cannot be changed) -- Records who approved and when -- PackageRevision is now available for cloning/deployment +This command changes the PackageRevision lifecycle from `Proposed` (revision 0) to `Published` (revision 1). With this, the PackageRevision becomes **immutable**, which means that the content cannot be changed. The command also records who approved and when. The PackageRevision is now available for cloning/deployment. ![Diagram](/static/images/porch/guides/approve-workflow.drawio.svg) -**Verify publication:** +Verify the publication: ```bash porchctl rpkg get porch-test.my-first-package.v1 --namespace default -o yaml | grep -E "lifecycle|publishedBy|publishTimestamp" ``` -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get porch-test.my-first-package.v1 --namespace default @@ -294,11 +257,7 @@ If the package revision needs more work, reject it to return to `Draft`: porchctl rpkg reject porch-test.my-first-package.v1 --namespace default ``` -**What this does:** - -- Changes lifecycle from `Proposed` back to `Draft` -- Allows further modifications -- You can then make changes and re-propose +This command changes the lifecycle from `Proposed` back to `Draft`, which allows further modifications. You can then make changes and re-propose. ![Diagram](/static/images/porch/guides/reject-workflow.drawio.svg) diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md index 5a58dfee8..279960c1f 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/deleting-packages.md @@ -79,7 +79,7 @@ porchctl rpkg propose porch-test.test-published-package.published-v1 --namespace porchctl rpkg approve porch-test.test-published-package.published-v1 --namespace=default ``` -**Verify the PackageRevisions were created:** +Verify the PackageRevisions were created: ```bash porchctl rpkg get --namespace=default @@ -88,11 +88,11 @@ porchctl rpkg get --namespace=default You should see an output similar to: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-draft-package.draft-v1 test-draft-package draft-v1 0 false Draft porch-test -porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test -porch-test.test-published-package.main test-published-package main -1 false Published porch-test -porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-draft-package.draft-v1 test-draft-package draft-v1 0 false Draft porch-test +porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test ``` --- @@ -105,13 +105,9 @@ Draft PackageRevisions can be deleted immediately without any approval process: porchctl rpkg del porch-test.test-draft-package.draft-v1 --namespace=default ``` -**What this does:** +This command immediately removes the Draft PackageRevision and deletes the corresponding Git branch (`draft/draft-v1`). No approval or confirmation is required. -- Immediately removes the Draft PackageRevision -- Deletes the corresponding Git branch (`draft/draft-v1`) -- No approval or confirmation required - -**Verify the deletion:** +Verify the deletion: ```bash porchctl rpkg get --namespace=default @@ -120,10 +116,10 @@ porchctl rpkg get --namespace=default The Draft PackageRevision should no longer appear in the list: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test -porch-test.test-published-package.main test-published-package main -1 false Published porch-test -porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-proposed-package.proposed-v1 test-proposed-package proposed-v1 0 false Proposed porch-test +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test ``` --- @@ -136,13 +132,9 @@ Proposed PackageRevisions can also be deleted directly: porchctl rpkg del porch-test.test-proposed-package.proposed-v1 --namespace=default ``` -**What this does:** - -- Immediately removes the Proposed PackageRevision -- Deletes the corresponding Git branch (`proposed/proposed-v1`) -- No approval process required +This command immediately removes the Proposed PackageRevision and deletes the corresponding Git branch (`proposed/proposed-v1`). No approval process is required. -**Verify the deletion:** +Verify the deletion: ```bash porchctl rpkg get --namespace=default @@ -151,9 +143,9 @@ porchctl rpkg get --namespace=default The Proposed PackageRevision should no longer appear in the list: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-published-package.main test-published-package main -1 false Published porch-test -porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true Published porch-test ``` --- @@ -166,13 +158,10 @@ Published PackageRevisions cannot be deleted directly. You must first propose th porchctl rpkg propose-delete porch-test.test-published-package.published-v1 --namespace=default ``` -**What this does:** - -- Changes the PackageRevision lifecycle from `Published` to `DeletionProposed` -- Signals that the PackageRevision should be deleted -- Requires approval before actual deletion occurs +This command changes the PackageRevision lifecycle from `Published` to `DeletionProposed` and signals that its deletion is up for review. +Requires approval before actual deletion occurs. -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get porch-test.test-published-package.published-v1 --namespace=default @@ -181,9 +170,9 @@ porchctl rpkg get porch-test.test-published-package.published-v1 --namespace=def The lifecycle should now show `DeletionProposed`: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-published-package.main test-published-package main -1 false Published porch-test -porch-test.test-published-package.published-v1 test-published-package published-v1 1 true DeletionProposed porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-published-package.published-v1 test-published-package published-v1 1 true DeletionProposed porch-test ``` --- @@ -196,13 +185,11 @@ If you want to proceed with the deletion, approve the deletion proposal: porchctl rpkg del porch-test.test-published-package.published-v1 --namespace=default ``` -**What this does:** - -- Permanently deletes the PackageRevision -- Removes the Git tag and any associated branches -- **Important**: This cannot be undone once completed +{{% alert title="Warning" color="Warning" %}} +This command permanently deletes the PackageRevision, removing the Git tag and any associated branches. This cannot be undone once completed. +{{% /alert %}} -**Verify the deletion:** +Verify the deletion: ```bash porchctl rpkg get --namespace=default @@ -211,8 +198,8 @@ porchctl rpkg get --namespace=default The published PackageRevision should no longer exist, but the main branch-tracking PackageRevision remains: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-published-package.main test-published-package main -1 false Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test ``` --- @@ -239,13 +226,9 @@ porchctl rpkg propose-delete porch-test.test-reject-delete.reject-v1 --namespace porchctl rpkg reject porch-test.test-reject-delete.reject-v1 --namespace=default ``` -**What this does:** - -- Changes lifecycle from `DeletionProposed` back to `Published` -- PackageRevision returns to normal published state -- The package can be used again normally +These commands change lifecycle from `DeletionProposed` back to `Published`, which means that the PackageRevision returns to normal published state. The revision can be used again normally. -**Verify the state change:** +Verify the state change: ```bash porchctl rpkg get porch-test.test-reject-delete.reject-v1 --namespace=default @@ -254,8 +237,8 @@ porchctl rpkg get porch-test.test-reject-delete.reject-v1 --namespace=default The lifecycle should be back to `Published`: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-reject-delete.reject-v1 test-reject-delete reject-v1 1 true Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-reject-delete.reject-v1 test-reject-delete reject-v1 1 true Published porch-test ``` --- @@ -307,24 +290,17 @@ graph TD ## Safety Considerations -**Published PackageRevision Protection:** +**Published PackageRevision Protection** -- Two-step deletion process prevents accidental removal -- Deletion proposals can be reviewed before approval -- Rejected proposals restore the PackageRevision to Published state +The two-step deletion process prevents accidental removal: deletion proposals can be reviewed before approval, and if a proposal is rejected the PackageRevision returns to the **Published** state. -**Git Repository Impact:** +**Git Repository Impact** -- Draft/Proposed deletions remove Git branches -- Published deletions remove Git tags and references -- Deletion is permanent and cannot be undone +Draft/Proposed deletions remove Git branches as well, and published deletions remove Git tags and references. Deletion is permanent and cannot be undone. -**Upstream Reference Considerations:** +**Upstream Reference Considerations** -- Upstream PackageRevisions cannot be deleted while downstream PackageRevisions reference them -- Delete downstream PackageRevisions first, then you can delete the upstream PackageRevisions -- The error message identifies which downstream PackageRevision is blocking deletion -- Consider the impact on deployed workloads +Upstream PackageRevisions cannot be deleted while downstream PackageRevisions reference them. Make sure to delete downstream PackageRevisions first, then you can delete the upstream PackageRevisions. The error message identifies which downstream PackageRevision is blocking deletion. Also consider the impact on deployed workloads. --- @@ -341,8 +317,8 @@ Error: cannot delete published package revision directly, use propose-delete fir **PackageRevision not found:** - Verify the exact PackageRevision name with the `porchctl rpkg get --namespace=default` command -- Check you're using the correct namespace -- Ensure the PackageRevision hasn't already been deleted +- Check that you are using the correct namespace +- Ensure the PackageRevision has not already been deleted **Permission denied:** @@ -374,7 +350,7 @@ After deleting PackageRevisions, you may notice "main" branch-tracking PackageRe Main branch-tracking PackageRevisions (with workspace name "main" and revision "-1") are managed automatically by Porch. Do not modify, propose, approve, or otherwise interact with them except for deletion after all regular PackageRevisions of that specific package have been removed. {{% /alert %}} -**Check for remaining PackageRevisions:** +Check for remaining PackageRevisions: ```bash porchctl rpkg get --namespace=default @@ -383,12 +359,12 @@ porchctl rpkg get --namespace=default You might see an output like: ```bash -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -porch-test.test-published-package.main test-published-package main -1 false Published porch-test -porch-test.test-reject-delete.main test-reject-delete main -1 false Published porch-test +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.test-published-package.main test-published-package main -1 false Published porch-test +porch-test.test-reject-delete.main test-reject-delete main -1 false Published porch-test ``` -**Delete the main branch-tracking PackageRevisions:** +Delete the main branch-tracking PackageRevisions: ```bash # Propose deletion of main branch PackageRevisions @@ -400,7 +376,7 @@ porchctl rpkg del porch-test.test-published-package.main --namespace=default porchctl rpkg del porch-test.test-reject-delete.main --namespace=default ``` -**Verify complete cleanup:** +Verify complete cleanup: ```bash porchctl rpkg get --namespace=default diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md index ac514baa9..09df483c1 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/inspecting-packages.md @@ -21,11 +21,7 @@ Get all package revisions across all repositories in a namespace: porchctl rpkg get --namespace default ``` -**What this does:** - -- Queries Porch for all PackageRevisions in the specified namespace -- Displays a summary table with key information -- Shows PackageRevisions from all registered repositories +This command queries Porch for all PackageRevisions in the specified namespace and displays a summary table with key information. It shows PackageRevisions from all registered repositories in that namespace. {{% alert title="Note" color="primary" %}} `porchctl rpkg list` is an alias for `porchctl rpkg get` and can be used interchangeably: @@ -36,7 +32,7 @@ porchctl rpkg list --namespace default {{% /alert %}} -**Example output:** +Example output: ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -46,44 +42,17 @@ blueprints.nginx.main nginx main 5 t blueprints.postgres.v1 postgres v1 0 false Proposed blueprints ``` -**Understanding the output:** - -- **NAME**: Full package revision identifier following the pattern `repository.([pathnode.]*)package.workspace` - - Format: `.[.].` - - Example: `porch-test.basedir.subdir.edge-function.v1` - - Repository: `porch-test` - - Path: `basedir/subdir` (directory structure) - - Package: `edge-function` - - Workspace: `v1` - - Simple example: `blueprints.nginx.main` (no path nodes) - - Repository: `blueprints` - - Package: `nginx` - - Workspace: `main` - -- **PACKAGE**: Package name with directory path if not in repository root - - Example: `basedir/subdir/network-function` shows location in repository - -- **WORKSPACENAME**: User-selected identifier for this PackageRevision - - Scoped to the package - `v1` in package A is independent from `v1` in package B - - Maps to Git branch or tag name - -- **REVISION**: Version number indicating publication status - - `1+`: Published PackageRevisions (increments with each publish: 1, 2, 3...) - - `0`: Unpublished PackageRevisions (Draft or Proposed) - - `-1`: Placeholder PackageRevisions pointing to Git branch/tag head - -- **LATEST**: Whether this is the latest published PackageRevision - - Only one PackageRevision per package marked as latest - - Based on highest revision number - -- **LIFECYCLE**: Current state of the PackageRevision - - `Draft`: Work-in-progress, freely editable, visible to authors - - `Proposed`: Read-only, awaiting approval, can be approved or rejected - - `Published`: Immutable, production-ready, assigned revision numbers - - `DeletionProposed`: Marked for removal, awaiting deletion approval - -- **REPOSITORY**: Source repository name - +Understanding the output: + +| Column | Description | Example | +|--------|-------------|---------| +| **NAME** | Full package revision identifier: `repository.([pathnode.]*)package.workspace`, i.e. `.[.].` where path nodes reflect directory structure under the repo. | `porch-test.basedir.subdir.edge-function.v1` | +| **PACKAGE** | Package name, including subdirectory path when the package is not at the repository root. | `basedir/subdir/network-function` | +| **WORKSPACENAME** | User-chosen identifier for this PackageRevision, scoped to the package (so `v1` in package A is unrelated to `v1` in package B); corresponds to the Git branch or tag name. | `v1` | +| **REVISION** | Version number indicating publication status.
`1+` = published (increments with each publish: 1, 2, 3…)
`0` = unpublished (Draft or Proposed)
`-1` = placeholder pointing at Git branch/tag head. | `2` (published), `0` (unpublished), `-1` (placeholder) | +| **LATEST** | Indicates the latest published PackageRevision for the package (only one; highest revision number). | `true` / `false` | +| **LIFECYCLE** | Current state of the PackageRevision.
**Draft** — in progress, editable, visible to authors
**Proposed** — read-only, pending approval (approve or reject)
**Published** — immutable, production-ready, has revision numbers
**DeletionProposed** — marked for removal, pending deletion approval. | `Draft`, `Proposed`, `Published`, `DeletionProposed` | +| **REPOSITORY** | Name of the source repository. | `porch-test` | --- ### Get Detailed PackageRevision Information @@ -94,13 +63,9 @@ Get complete details about a specific PackageRevision: porchctl rpkg get porch-test.my-app.v1 --namespace default -o yaml ``` -**What this does:** - -- Retrieves the full PackageRevision resource -- Shows all metadata, spec, and status fields -- Displays in YAML format for easy reading +This command retrieves the full PackageRevision manifest, including all metadata, spec, and status fields. Displayed in YAML format for easy reading. -**Example output:** +Example output: ```yaml apiVersion: porch.kpt.dev/v1alpha1 @@ -128,7 +93,7 @@ status: upstreamLock: {} ``` -**Key fields to inspect:** +Key fields to inspect: - **spec.lifecycle**: Current PackageRevision state - **spec.tasks**: History of operations performed on this PackageRevision @@ -148,13 +113,9 @@ Display the root Kptfile of a specific package revision without downloading the porchctl rpkg get porch-test.my-app.v1 --show-kptfile --namespace default ``` -**What this does:** +This command fetches the PackageRevisionResources for the specified package revision and extracts and displays only the root `Kptfile`. It is useful for quickly inspecting package metadata, pipeline configuration, and status. -- Fetches the PackageRevisionResources for the specified package revision -- Extracts and displays only the root `Kptfile` -- Useful for quickly inspecting package metadata, pipeline configuration, and status - -**Example output:** +Example output: ```yaml apiVersion: kpt.dev/v1 @@ -189,13 +150,9 @@ Read the actual contents of a PackageRevision: porchctl rpkg read porch-test.my-first-package.v1 --namespace default ``` -**What this does:** - -- Fetches PackageRevision resources and outputs to stdout -- Shows all KRM resources in ResourceList format -- Displays the complete PackageRevision contents +This command fetches PackageRevision resources and outputs to stdout, showing all KRM resources in ResourceList format. It displays the complete PackageRevision content. -**Example output:** +Example output: ```yaml apiVersion: config.kubernetes.io/v1 @@ -253,27 +210,25 @@ Porch provides multiple ways to filter PackageRevisions. You can either use `por ### Using Porchctl Flags -Filter PackageRevisions using built-in porchctl flags: - -**Filter by package name (substring match):** +Filter by package name (substring match): ```bash porchctl rpkg get --namespace default --name my-app ``` -**Filter by revision number (exact match):** +Filter by revision number (exact match): ```bash porchctl rpkg get --namespace default --revision 1 ``` -**Filter by workspace name:** +Filter by workspace name: ```bash porchctl rpkg get --namespace default --workspace v1 ``` -**Example output:** +Example output: ```bash $ porchctl rpkg get --namespace default --name network-function @@ -289,13 +244,13 @@ porch-test.network-function.main network-function main 0 Filter using Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#list-and-watch-filtering) with the `--selector` flag: -**Get all "latest" published PackageRevisions:** +Get all "latest" published PackageRevisions: ```bash kubectl get packagerevisions -n default --selector 'kpt.dev/latest-revision=true' ``` -**Example output:** +Example output: ```bash $ kubectl get packagerevisions -n default --show-labels --selector 'kpt.dev/latest-revision=true' @@ -314,7 +269,7 @@ PackageRevision resources have limited labels. To filter by repository, package Filter using PackageRevision [fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/) with the `--field-selector` flag: -**Supported fields:** +Supported fields: - `metadata.name` - `metadata.namespace` @@ -324,32 +279,32 @@ Filter using PackageRevision [fields](https://kubernetes.io/docs/concepts/overvi - `spec.workspaceName` - `spec.lifecycle` -**Filter by repository:** +Filter by repository: ```bash kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test' ``` -**Filter by lifecycle:** +Filter by lifecycle: ```bash kubectl get packagerevisions -n default --field-selector 'spec.lifecycle==Published' ``` -**Filter by package name:** +Filter by package name: ```bash kubectl get packagerevisions -n default --field-selector 'spec.packageName==my-app' ``` -**Combine multiple filters:** +Combine multiple filters: ```bash kubectl get packagerevisions -n default \ --field-selector 'spec.repository==porch-test,spec.lifecycle==Published' ``` -**Example output:** +Example output: ```bash $ kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test' @@ -371,16 +326,12 @@ Beyond basic listing and filtering, these operations help you monitor changes an ### Watch for PackageRevision Changes -Monitor PackageRevisions in real-time: - ```bash kubectl get packagerevisions -n default --watch ``` ### Sort by Creation Time -Find recently created PackageRevisions: - ```bash kubectl get packagerevisions -n default --sort-by=.metadata.creationTimestamp ``` diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md index 5576b2425..1b7f8cadc 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/upgrading-packages.md @@ -40,7 +40,7 @@ porchctl rpkg approve porch-test.blueprint.1 --namespace=porch-demo ![Step 1: Create Base Blueprint](/static/images/porch/upgrade-step1.drawio.svg) -**PackageRevisions State After Step 1:** +PackageRevisions state after step 1: ```bash $ porchctl rpkg get --namespace=porch-demo NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -73,7 +73,7 @@ At this point, we have two published blueprint versions: `v1` (the original) and ![Step 2: Create New Blueprint Revision](/static/images/porch/upgrade-step2.drawio.svg) -**PackageRevisions State After Step 2:** +PackageRevisions state after step 2: ```bash $ porchctl rpkg get --namespace=porch-demo NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -106,7 +106,7 @@ porchctl rpkg approve porch-test.deployment.1 --namespace=porch-demo ![Step 3: Clone Blueprint into Deployment Package](/static/images/porch/upgrade-step3.drawio.svg) -**PackageRevisions State After Step 3:** +PackageRevisions state after step 3: ```bash $ porchctl rpkg get --namespace=porch-demo NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -135,13 +135,11 @@ 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. +After approval, `porch-test.deployment.2` is the new, published deployment package. It now contains the `new-configmap.yaml` from the upstream `blueprint.2` and the local `kpt.dev/annotation=true` customization applied in Step 3. ![Step 4: Discover and Perform Upgrade](/static/images/porch/upgrade-step4.drawio.svg) -**PackageRevisions State After Step 4:** +PackageRevisions state after step 4: ```bash $ porchctl rpkg get --namespace=porch-demo NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -236,24 +234,16 @@ The outcome of an upgrade depends on the changes made in the upstream blueprint ### 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. - -* **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. +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. 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. - -* **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). +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. Use copy-merge 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. - -* **Use case:** To completely reset a deployment package to a new blueprint version, abandoning all previous customizations. +The most aggressive strategy. It completely discards the local package's contents and replaces them with the contents of the new upstream package. Used 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. - -* **Use case:** To guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. +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. Use fast-forward to guarantee that you are only upgrading unmodified packages, preventing accidental overwrites of important local customizations. ## Practical examples: upgrade strategies in action @@ -263,8 +253,6 @@ 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: - ```bash # discover available upgrades porchctl rpkg upgrade --discover=upstream @@ -281,8 +269,6 @@ Outcome: A new draft `porch-test.deployment.2` is created containing both the ne 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 ``` @@ -293,8 +279,6 @@ Outcome: Files present in both upstream and local are replaced with the upstream 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 ``` @@ -305,8 +289,6 @@ Outcome: The new draft contains only the upstream contents; local customizations 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 ``` @@ -327,9 +309,11 @@ 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. -* **Use Fixed Revisions:** Do not upgrade packages' placeholder/main package revisions or attempt to use them as upstream for an upgrade - this is not supported. Select defined package revisions instead - see [Core Concepts]({{% relref "/docs/2_concepts#core-concepts" %}}) for the rules which identify a placeholder package revision +For better organization and access control, keep blueprint packages and deployment packages in separate Git repositories. + +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. + +Do not upgrade packages' placeholder/main package revisions or attempt to use them as upstream for an upgrade - this is not supported. Select defined package revisions instead - see [Core Concepts]({{% relref "/docs/2_concepts#core-concepts" %}}) for the rules which identify a placeholder package revision. ### Cleanup diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md index 13698aa25..5f48d5181 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/_index.md @@ -7,8 +7,8 @@ description: A group of guides outlining how to interact with Porch repositories ## Prerequisites -- Porch deployed on a Kubernetes cluster [Setup Porch Guide]({{% relref "/docs/3_getting_started/installing-porch.md" %}}). -- **Porchctl** CLI tool installed [Setup Porchctl Guide]({{% relref "/docs/3_getting_started/installing-porchctl.md" %}}). +- Porch deployed on a Kubernetes cluster. See, [Setup Porch Guide]({{% relref "/docs/3_getting_started/installing-porch.md" %}}). +- **Porchctl** CLI tool installed. See, [Setup Porchctl Guide]({{% relref "/docs/3_getting_started/installing-porchctl.md" %}}). - **Kubectl** configured to access your cluster. - A Git repository to register with Porch. If you need to create one, see [GitHub's Repository Guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). @@ -16,11 +16,7 @@ description: A group of guides outlining how to interact with Porch repositories ## Understanding Repositories -Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch: - -- Where to find package blueprints -- Where to store deployment packages -- How to authenticate with the repository +Before Porch can manage packages, you must register repositories where those packages are stored. Repositories tell Porch where to find package blueprints, where to store deployment packages and how to authenticate with the repository. Porch primarily supports **Git repositories** from providers like GitHub, GitLab, Gitea, Bitbucket, and other Git-compatible services. @@ -70,23 +66,23 @@ Common issues when working with repositories and their solutions: **Repository shows READY: False?** -- Check repository URL is accessible -- Verify authentication credentials are correct -- Inspect repository conditions: `porchctl repo get -n -o yaml` -- Check Porch server logs for detailed errors +- Check if the repository URL is accessible +- Verify that the authentication credentials are correct +- Inspect the repository conditions: `porchctl repo get -n -o yaml` +- Check the Porch server logs for detailed errors **Packages not appearing after registration?** -- Ensure repository has been synchronized (check SYNC SCHEDULE or trigger manual sync) -- Verify packages have valid Kptfile in repository -- Check repository directory configuration matches package location -- If re-registering a previously unregistered repository, packages in Git will reappear after sync +- Ensure that the repository has been synchronized (check SYNC SCHEDULE or trigger manual sync) +- Verify that the packages have valid Kptfile in repository +- Check if the repository directory configuration matches package location +- If you are re-registering a previously unregistered repository, the packages in Git will reappear after sync **Authentication failures?** -- For GitHub: Ensure Personal Access Token has `repo` scope -- For private repos: Verify credentials are correctly configured -- Check secret exists: `kubectl get secret -n ` +- For GitHub: Ensure that the Personal Access Token has `repo` scope +- For private repos: Verify that the credentials are correctly configured +- Check whether the secret exists: `kubectl get secret -n ` **Need to change repository configuration?** @@ -96,7 +92,7 @@ Common issues when working with repositories and their solutions: **Sync not working?** -- Verify cron expression syntax is correct +- Verify that the cron expression syntax is correct - Check minimum 1-minute delay for manual syncs - Inspect repository status for sync errors diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md index 548b75402..cbc8ed2a5 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-basic-usage.md @@ -17,11 +17,7 @@ View all repositories registered with Porch: porchctl repo get --namespace default ``` -**What this does:** - -- Queries Porch for all registered repositories in the specified namespace -- Displays repository type, content, sync schedule, and status -- Shows the repository address +This command queries Porch for all registered repositories in the specified namespace, displays the repository type, content type, sync schedule, and status and shows the repository address. {{% alert title="Note" color="primary" %}} `porchctl repo list` is an alias for `porchctl repo get` and can be used interchangeably: @@ -86,11 +82,7 @@ View complete details about a specific repository: porchctl repo get porch-test --namespace default -o yaml ``` -**What this does:** - -- Retrieves the full Repository resource -- Shows configuration, authentication, and status information -- Displays in YAML format for easy reading +This command retrieves the full Repository resource, shows configuration, authentication, and status information displayed in YAML format for easy reading. **Example output:** diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md index 43098721e..e0050bb18 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-registration.md @@ -19,11 +19,7 @@ porchctl repo register https://github.com/example/porch-test.git \ --branch=main ``` -**What this does:** - -- Registers the Git repository with Porch -- Creates a Repository resource in Kubernetes -- Begins synchronizing packages from the repository +This command registers the Git repository with Porch, creates a Repository resource in Kubernetes and begins synchronizing packages from the repository. **Example output:** diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md index a60c0d567..05609a3f0 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-synchronization.md @@ -21,11 +21,7 @@ Force an immediate synchronization of a repository: porchctl repo sync porch-test --namespace default ``` -**What this does:** - -- Schedules a one-time sync (minimum 1-minute delay) -- Updates packages from the repository -- Independent of periodic sync schedule +This command schedules a one-time sync (minimum 1-minute delay), updates packages from the repository. This sync is independent of the periodic sync schedule. **Example output:** @@ -77,12 +73,7 @@ porchctl repo sync porch-test --namespace default --run-once "2024-01-15T14:30:0 ``` {{% alert title="Note" color="primary" %}} -**Sync behavior:** - -- Minimum delay is 1 minute from command execution -- Updates `spec.sync.runOnceAt` field in Repository CR -- Independent of existing periodic sync schedule -- Past timestamps are automatically adjusted to minimum delay +The minimum delay is 1 minute from command execution and the `spec.sync.runOnceAt` field is updated in the Repository CR. This sync is independent of the existing periodic sync schedule and past timestamps are automatically adjusted to minimum delay. {{% /alert %}} --- \ No newline at end of file diff --git a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md index b1fd5b1e9..6b49ddf89 100644 --- a/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md +++ b/docs/content/en/docs/4_tutorials_and_how-tos/working_with_porch_repositories/repository-unregistration.md @@ -17,12 +17,7 @@ Remove a repository from Porch: porchctl repo unregister porch-test --namespace default ``` -**What this does:** - -- Removes the Repository resource from Kubernetes -- Stops synchronizing packages from the repository -- Removes Porch's cached metadata for the repository -- Does not delete the underlying Git repository or its contents +This command removes the Repository resource from Kubernetes, it stops synchronizing packages from the repository, removes Porch's cached metadata for the repository but **does not delete** the underlying Git repository or its contents. {{% alert title="Warning" color="warning" %}} Unregistering a repository does not delete the underlying Git repository or its contents. It only removes Porch's connection to it.