From 5d09d5863b3d6268d5645cca9b694f62cec6a170 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Wed, 26 Nov 2025 14:03:11 +0000 Subject: [PATCH 1/5] adding inspecting packages guide --- .../getting-and-listing.md | 16 - .../inspecting-packages.md | 422 ++++++++++++++++++ 2 files changed, 422 insertions(+), 16 deletions(-) delete mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/getting-and-listing.md create mode 100644 content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/getting-and-listing.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/getting-and-listing.md deleted file mode 100644 index 642ad732..00000000 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/getting-and-listing.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Getting & Listing Packages" -type: docs -weight: 4 -description: ---- - -## Lorem Ipsum - -[GET/LIST EXAMPLES] [FOR EACH: PORCHCTL EXAMPLE + KUBECTL ALTERNATIVE] - -- [LIST ALL PACKAGE REVISIONS] -- [GET SPECIFIC PACKAGE REVISION] -- [LIST WITH FILTER] - - [LABEL SELECTOR] --selector - - [FIELD SELECTOR] --field-selector diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md new file mode 100644 index 00000000..48dec956 --- /dev/null +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md @@ -0,0 +1,422 @@ +--- +title: "Inspecting Packages" +type: docs +weight: 3 +description: "A guide to viewing, querying, and inspecting packages 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. + +--- + +## Basic Operations + +These operations cover the fundamental commands for viewing and inspecting packages in Porch. + +### List All Packages + +View all packages across all repositories in a namespace: + +```bash +porchctl rpkg get --namespace default +``` + +**What this does:** + +- Queries Porch for all package revisions in the specified namespace +- Displays a summary table with key information +- Shows packages from all registered repositories + +{{% alert title="Note" color="primary" %}} +`porchctl rpkg list` is an alias for `porchctl rpkg get` and can be used interchangeably: + +```bash +porchctl rpkg list --namespace default +``` + +{{% /alert %}} + +**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 +blueprints.nginx.main nginx main 5 true Published blueprints +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 package revision + - 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 revisions (increments with each publish: 1, 2, 3...) + - `0`: Unpublished revisions (Draft or Proposed) + - `-1`: Placeholder pointing to Git branch/tag head + +- **LATEST**: Whether this is the latest published revision + - Only one revision per package marked as latest + - Based on highest revision number + +- **LIFECYCLE**: Current state of the package revision + - `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 + +--- + +### Get Detailed Package Information + +View complete details about a specific package: + +```bash +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 + +**Example output:** + +```yaml +apiVersion: porch.kpt.dev/v1alpha1 +kind: PackageRevision +metadata: + creationTimestamp: "2025-11-24T13:00:14Z" + labels: + kpt.dev/latest-revision: "true" + name: porch-test.my-first-package.v1 + namespace: default + resourceVersion: 5778e0e3e9a92d248fec770cef5baf142958aa54 + uid: f9f6507d-20fc-5319-97b2-6b8050c4f9cc +spec: + lifecycle: Published + packageName: my-first-package + repository: porch-test + revision: 1 + tasks: + - init: + description: My first Porch package + type: init + workspaceName: v1 +status: + publishTimestamp: "2025-11-24T16:38:41Z" + upstreamLock: {} +``` + +**Key fields to inspect:** + +- **spec.lifecycle**: Current package state +- **spec.tasks**: History of operations performed +- **status.publishTimestamp**: When it was published + +{{% alert title="Tip" color="primary" %}} +Use `jq` to extract specific fields: `porchctl rpkg get -n default -o json | jq '.metadata'` +{{% /alert %}} + +--- + +### View Package Resources + +Inspect the actual contents of a package: + +```bash +porchctl rpkg pull porch-test.my-first-package.v1 --namespace default +``` + +**What this does:** + +- Fetches package resources and outputs to stdout +- Shows all YAML files in ResourceList format +- Displays the complete package contents + +**Example output:** + +```yaml +apiVersion: config.kubernetes.io/v1 +kind: ResourceList +items: +- apiVersion: "" + kind: KptRevisionMetadata + metadata: + name: porch-test.my-first-package.v1 + namespace: default + creationTimestamp: "2025-11-24T13:00:14Z" + resourceVersion: 5778e0e3e9a92d248fec770cef5baf142958aa54 + uid: f9f6507d-20fc-5319-97b2-6b8050c4f9cc + annotations: + config.kubernetes.io/path: '.KptRevisionMetadata' +- apiVersion: kpt.dev/v1 + kind: Kptfile + metadata: + name: my-first-package + annotations: + config.kubernetes.io/local-config: "true" + config.kubernetes.io/path: 'Kptfile' + info: + description: My first Porch package + pipeline: + mutators: + - image: gcr.io/kpt-fn/set-namespace:v0.4.1 + configMap: + namespace: production +- apiVersion: v1 + kind: ConfigMap + metadata: + name: kptfile.kpt.dev + annotations: + config.kubernetes.io/local-config: "true" + config.kubernetes.io/path: 'package-context.yaml' + data: + name: example +- apiVersion: v1 + kind: ConfigMap + metadata: + name: test-config + namespace: production + annotations: + config.kubernetes.io/path: 'test-config.yaml' + data: + Key: "Value" +``` + +**Filter specific resources:** + +```bash +porchctl rpkg pull porch-test.my-first-package.v1 --namespace default | grep -A 15 "kind: Kptfile" +``` + +**Example output:** + +```yaml + kind: Kptfile + metadata: + name: my-first-package + annotations: + config.kubernetes.io/local-config: "true" + config.kubernetes.io/path: Kptfile + info: + description: My first Porch package + pipeline: + mutators: + - image: gcr.io/kpt-fn/set-namespace:v0.4.1 + configMap: + namespace: production +``` + +--- + +## Advanced Filtering + +Porch provides multiple ways to filter package revisions beyond basic listing. You can use porchctl's built-in flags, Kubernetes label selectors, or field selectors depending on your needs. + +### Using Porchctl Flags + +Filter package revisions using built-in porchctl flags: + +**Filter by package name (substring match):** + +```bash +porchctl rpkg get --namespace default --name my-app +``` + +**Filter by revision number (exact match):** + +```bash +porchctl rpkg get --namespace default --revision 1 +``` + +**Filter by workspace name:** + +```bash +porchctl rpkg get --namespace default --workspace v1 +``` + +**Example output:** + +```bash +$ porchctl rpkg get --namespace default --name network-function +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +porch-test.network-function.v1 network-function v1 1 false Published porch-test +porch-test.network-function.v2 network-function v2 2 true Published porch-test +porch-test.network-function.main network-function main 0 false Draft porch-test +``` + +--- + +### Using Kubectl Label Selectors + +Filter using Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#list-and-watch-filtering) with the `--selector` flag: + +**Find latest published revisions:** + +```bash +kubectl get packagerevisions -n default --selector 'kpt.dev/latest-revision=true' +``` + +**Example output:** + +```bash +$ kubectl get packagerevisions -n default --show-labels --selector 'kpt.dev/latest-revision=true' +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY LABELS +porch-test.my-app.v2 my-app v2 2 true Published porch-test kpt.dev/latest-revision=true +blueprints.nginx.main nginx main 5 true Published blueprints kpt.dev/latest-revision=true +``` + +{{% alert title="Note" color="primary" %}} +PackageRevision resources have limited labels. To filter by repository, package name, or other attributes, use `--field-selector` instead (see next section). +{{% /alert %}} + +--- + +### Using Kubectl Field Selectors + +Filter using PackageRevision [fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/) with the `--field-selector` flag: + +**Supported fields:** + +- `metadata.name` +- `metadata.namespace` +- `spec.revision` +- `spec.packageName` +- `spec.repository` +- `spec.workspaceName` +- `spec.lifecycle` + +**Filter by repository:** + +```bash +kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test' +``` + +**Filter by lifecycle:** + +```bash +kubectl get packagerevisions -n default --field-selector 'spec.lifecycle==Published' +``` + +**Filter by package name:** + +```bash +kubectl get packagerevisions -n default --field-selector 'spec.packageName==my-app' +``` + +**Combine multiple filters:** + +```bash +kubectl get packagerevisions -n default \ + --field-selector 'spec.repository==porch-test,spec.lifecycle==Published' +``` + +**Example output:** + +```bash +$ kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test' +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 +porch-test.my-service.main my-service main 3 true Published porch-test +``` + +{{% alert title="Note" color="primary" %}} +The `--field-selector` flag supports only the `=` and `==` operators. **The `!=` operator is not supported** due to Porch's internal caching behavior. +{{% /alert %}} + +{{% alert title="Tip" color="primary" %}} +For a complete reference of all available command options and flags, see the [Porch CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). +{{% /alert %}} + +--- + +## Additional Operations + +Beyond basic listing and filtering, these operations help you monitor changes and format output. + +### Watch for Package Changes + +Monitor package revisions in real-time: + +```bash +kubectl get packagerevisions -n default --watch +``` + +### Sort by Creation Time + +Find recently created packages: + +```bash +kubectl get packagerevisions -n default --sort-by=.metadata.creationTimestamp +``` + +### Output Formatting + +Both `porchctl` and `kubectl` support standard Kubernetes [output formatting flags](https://kubernetes.io/docs/reference/kubectl/#output-options): + +- `-o yaml` - YAML format +- `-o json` - JSON format +- `-o wide` - Additional columns +- `-o name` - Resource names only +- `-o custom-columns=...` - Custom column output + +--- + +## Troubleshooting + +**No packages shown?** + +- Verify repositories are registered and healthy (see [Repository Management Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}})) +- Ensure packages exist in the Git repository + +**Permission denied errors?** + +- Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default` +- Verify service account has proper roles + +**Package not found?** + +- Confirm the exact package name: `porchctl rpkg get --namespace default` +- Check you're using the correct namespace +- Verify the package hasn't been deleted + +--- + +## Key Concepts + +- **PackageRevision**: A specific version of a package in Porch +- **Namespace**: Kubernetes namespace where packages are managed +- **Repository**: Git repository containing package sources +- **Lifecycle**: Current state of the package (Draft, Proposed, Published) +- **Workspace**: Unique identifier for a package revision (maps to Git branch/tag) +- **Latest**: Flag indicating the most recent published revision +- **Path nodes**: Directory structure within repository where package is located + +--- From 399b01dcb7569961eb9a931aeb97b21a17335d9a Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Wed, 26 Nov 2025 14:07:25 +0000 Subject: [PATCH 2/5] moving cli ref --- .../4_tutorials_and_how-tos/inspecting-packages.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md index 48dec956..8ae5e445 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md @@ -351,10 +351,6 @@ porch-test.my-service.main my-service main 3 t The `--field-selector` flag supports only the `=` and `==` operators. **The `!=` operator is not supported** due to Porch's internal caching behavior. {{% /alert %}} -{{% alert title="Tip" color="primary" %}} -For a complete reference of all available command options and flags, see the [Porch CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). -{{% /alert %}} - --- ## Additional Operations @@ -387,6 +383,10 @@ Both `porchctl` and `kubectl` support standard Kubernetes [output formatting fla - `-o name` - Resource names only - `-o custom-columns=...` - Custom column output +{{% alert title="Note" color="primary" %}} +For a complete reference of all available command options and flags, see the [Porch CLI Guide]({{% relref "/docs/neo-porch/7_cli_api/relevant_old_docs/porchctl-cli-guide.md" %}}). +{{% /alert %}} + --- ## Troubleshooting From 05c295fa19be45b8f50e806b8e6bae280775d212 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 10:28:38 +0000 Subject: [PATCH 3/5] amending comments --- .../inspecting-packages.md | 42 ++++--------------- 1 file changed, 9 insertions(+), 33 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md index 8ae5e445..8f47274c 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md @@ -18,9 +18,9 @@ description: "A guide to viewing, querying, and inspecting packages in Porch" These operations cover the fundamental commands for viewing and inspecting packages in Porch. -### List All Packages +### Getting All Packages -View all packages across all repositories in a namespace: +Get all packages across all repositories in a namespace: ```bash porchctl rpkg get --namespace default @@ -93,7 +93,7 @@ blueprints.postgres.v1 postgres v1 0 f ### Get Detailed Package Information -View complete details about a specific package: +Get complete details about a specific package: ```bash porchctl rpkg get porch-test.my-app.v1 --namespace default -o yaml @@ -145,18 +145,18 @@ Use `jq` to extract specific fields: `porchctl rpkg get -n default -o jso --- -### View Package Resources +### Reading Package Resources -Inspect the actual contents of a package: +Read the actual contents of a package: ```bash -porchctl rpkg pull porch-test.my-first-package.v1 --namespace default +porchctl rpkg read porch-test.my-first-package.v1 --namespace default ``` **What this does:** - Fetches package resources and outputs to stdout -- Shows all YAML files in ResourceList format +- Shows all KRM of the package in ResourceList format - Displays the complete package contents **Example output:** @@ -209,35 +209,11 @@ items: Key: "Value" ``` -**Filter specific resources:** - -```bash -porchctl rpkg pull porch-test.my-first-package.v1 --namespace default | grep -A 15 "kind: Kptfile" -``` - -**Example output:** - -```yaml - kind: Kptfile - metadata: - name: my-first-package - annotations: - config.kubernetes.io/local-config: "true" - config.kubernetes.io/path: Kptfile - info: - description: My first Porch package - pipeline: - mutators: - - image: gcr.io/kpt-fn/set-namespace:v0.4.1 - configMap: - namespace: production -``` - --- ## Advanced Filtering -Porch provides multiple ways to filter package revisions beyond basic listing. You can use porchctl's built-in flags, Kubernetes label selectors, or field selectors depending on your needs. +Porch provides multiple ways to filter package revisions. You can either use `porchctl`'s built-in flags, Kubernetes label selectors, or field selectors depending on your needs. ### Using Porchctl Flags @@ -277,7 +253,7 @@ 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: -**Find latest published revisions:** +**Get all "latest" published package revisions:** ```bash kubectl get packagerevisions -n default --selector 'kpt.dev/latest-revision=true' From 3cb42a62753b6e7771021984267cc9aba8cd4998 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 10:35:26 +0000 Subject: [PATCH 4/5] changing to PackageRevision term --- .../inspecting-packages.md | 89 ++++++++++--------- 1 file changed, 47 insertions(+), 42 deletions(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md index 8f47274c..095f8e52 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md @@ -1,8 +1,8 @@ --- -title: "Inspecting Packages" +title: "Getting Package Revisions" type: docs weight: 3 -description: "A guide to viewing, querying, and inspecting packages in Porch" +description: "A guide to getting/listing, reading, querying, and inspecting package revisions in Porch" --- ## Prerequisites @@ -12,15 +12,19 @@ description: "A guide to viewing, querying, and inspecting packages in Porch" - 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. +{{% alert title="Understanding Terminology" color="info" %}} +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 %}} + --- ## Basic Operations -These operations cover the fundamental commands for viewing and inspecting packages in Porch. +These operations cover the fundamental commands for viewing and inspecting package revisions in Porch. -### Getting All Packages +### Getting All Package Revisions -Get all packages across all repositories in a namespace: +Get all package revisions across all repositories in a namespace: ```bash porchctl rpkg get --namespace default @@ -28,9 +32,9 @@ porchctl rpkg get --namespace default **What this does:** -- Queries Porch for all package revisions in the specified namespace +- Queries Porch for all PackageRevisions in the specified namespace - Displays a summary table with key information -- Shows packages from all registered repositories +- Shows PackageRevisions from all registered repositories {{% alert title="Note" color="primary" %}} `porchctl rpkg list` is an alias for `porchctl rpkg get` and can be used interchangeably: @@ -68,20 +72,20 @@ blueprints.postgres.v1 postgres v1 0 f - **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 package revision +- **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 revisions (increments with each publish: 1, 2, 3...) - - `0`: Unpublished revisions (Draft or Proposed) - - `-1`: Placeholder pointing to Git branch/tag head + - `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 revision - - Only one revision per package marked as latest +- **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 package revision +- **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 @@ -91,9 +95,9 @@ blueprints.postgres.v1 postgres v1 0 f --- -### Get Detailed Package Information +### Get Detailed PackageRevision Information -Get complete details about a specific package: +Get complete details about a specific PackageRevision: ```bash porchctl rpkg get porch-test.my-app.v1 --namespace default -o yaml @@ -135,9 +139,9 @@ status: **Key fields to inspect:** -- **spec.lifecycle**: Current package state -- **spec.tasks**: History of operations performed -- **status.publishTimestamp**: When it was published +- **spec.lifecycle**: Current PackageRevision state +- **spec.tasks**: History of operations performed on this PackageRevision +- **status.publishTimestamp**: When the PackageRevision was published {{% alert title="Tip" color="primary" %}} Use `jq` to extract specific fields: `porchctl rpkg get -n default -o json | jq '.metadata'` @@ -145,9 +149,9 @@ Use `jq` to extract specific fields: `porchctl rpkg get -n default -o jso --- -### Reading Package Resources +### Reading PackageRevision Resources -Read the actual contents of a package: +Read the actual contents of a PackageRevision: ```bash porchctl rpkg read porch-test.my-first-package.v1 --namespace default @@ -155,9 +159,9 @@ porchctl rpkg read porch-test.my-first-package.v1 --namespace default **What this does:** -- Fetches package resources and outputs to stdout -- Shows all KRM of the package in ResourceList format -- Displays the complete package contents +- Fetches PackageRevision resources and outputs to stdout +- Shows all KRM resources in ResourceList format +- Displays the complete PackageRevision contents **Example output:** @@ -213,11 +217,11 @@ items: ## Advanced Filtering -Porch provides multiple ways to filter package revisions. You can either use `porchctl`'s built-in flags, Kubernetes label selectors, or field selectors depending on your needs. +Porch provides multiple ways to filter PackageRevisions. You can either use `porchctl`'s built-in flags, Kubernetes label selectors, or field selectors depending on your needs. ### Using Porchctl Flags -Filter package revisions using built-in porchctl flags: +Filter PackageRevisions using built-in porchctl flags: **Filter by package name (substring match):** @@ -253,7 +257,7 @@ 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 package revisions:** +**Get all "latest" published PackageRevisions:** ```bash kubectl get packagerevisions -n default --selector 'kpt.dev/latest-revision=true' @@ -333,9 +337,9 @@ The `--field-selector` flag supports only the `=` and `==` operators. **The `!=` Beyond basic listing and filtering, these operations help you monitor changes and format output. -### Watch for Package Changes +### Watch for PackageRevision Changes -Monitor package revisions in real-time: +Monitor PackageRevisions in real-time: ```bash kubectl get packagerevisions -n default --watch @@ -343,7 +347,7 @@ kubectl get packagerevisions -n default --watch ### Sort by Creation Time -Find recently created packages: +Find recently created PackageRevisions: ```bash kubectl get packagerevisions -n default --sort-by=.metadata.creationTimestamp @@ -367,32 +371,33 @@ For a complete reference of all available command options and flags, see the [Po ## Troubleshooting -**No packages shown?** +**No PackageRevisions shown?** - Verify repositories are registered and healthy (see [Repository Management Guide]({{% relref "/docs/neo-porch/4_tutorials_and_how-tos/setting-up-repositories.md" %}})) -- Ensure packages exist in the Git repository +- Ensure PackageRevisions exist in the Git repository **Permission denied errors?** - Check RBAC permissions: `kubectl auth can-i get packagerevisions -n default` - Verify service account has proper roles -**Package not found?** +**PackageRevision not found?** -- Confirm the exact package name: `porchctl rpkg get --namespace default` +- Confirm the exact PackageRevision name: `porchctl rpkg get --namespace default` - Check you're using the correct namespace -- Verify the package hasn't been deleted +- Verify the PackageRevision hasn't been deleted --- ## Key Concepts -- **PackageRevision**: A specific version of a package in Porch -- **Namespace**: Kubernetes namespace where packages are managed -- **Repository**: Git repository containing package sources -- **Lifecycle**: Current state of the package (Draft, Proposed, Published) -- **Workspace**: Unique identifier for a package revision (maps to Git branch/tag) -- **Latest**: Flag indicating the most recent published revision -- **Path nodes**: Directory structure within repository where package is located +- **PackageRevision**: The Kubernetes resource managed by Porch (there is no separate "Package" resource) +- **Namespace**: Kubernetes namespace where PackageRevisions are managed +- **Repository**: Git repository containing PackageRevision sources +- **Lifecycle**: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed) +- **Workspace**: Unique identifier for a PackageRevision within a package (maps to Git branch/tag) +- **Latest**: Flag indicating the most recent published PackageRevision of a package +- **Path nodes**: Directory structure within repository where PackageRevision is located +- **Revision Number**: 0 for Draft/Proposed, 1+ for Published (increments with each publication) --- From c80b55394eb6b4a6868d361f6839bac366043a94 Mon Sep 17 00:00:00 2001 From: Catalin-Stratulat-Ericsson Date: Mon, 1 Dec 2025 10:39:16 +0000 Subject: [PATCH 5/5] chaning note color --- .../neo-porch/4_tutorials_and_how-tos/inspecting-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md index 095f8e52..fb638816 100644 --- a/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md +++ b/content/en/docs/neo-porch/4_tutorials_and_how-tos/inspecting-packages.md @@ -12,7 +12,7 @@ description: "A guide to getting/listing, reading, querying, and inspecting pack - 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. -{{% alert title="Understanding Terminology" color="info" %}} +{{% 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 %}}