Skip to content

Creating a Porch Basic Usage guide #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Creating a Porch Basic Usage guide #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
483d7d7
Creating a Porch Basic Usage guide
lovesprung Jul 24, 2025
11b8a48
Merge branch 'main' into porch_basic_usage
lovesprung Jul 31, 2025
b7e2f3b
Creating the Use Cases page
lovesprung Jul 31, 2025
bf7a316
Fixed broken link
lovesprung Jul 31, 2025
6628203
Merging Use Cases into Porch cli guide
lovesprung Aug 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 107 additions & 3 deletions content/en/docs/porch/user-guides/porchctl-cli-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,9 @@ package content. The matching resources share the same `name` (as well as API gr

To use Porch with a Git repository, you will need:

* A Git repository for your blueprints.
* A Git repository for your blueprints. An otherwise empty repository with an
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this section looks good to me. its a useful addition of clarity to ensure users know that a fresh repository is not enough but they need to initialize it with a Readme or initial file/change

initial commit works best. The initial commit is required to establish the
`main` branch.
* If the repository requires authentication you will require either
- A [Personal Access Token](https://github.com/settings/tokens) (when using GitHub repository) for Porch to authenticate
with the repository if the repository. Porch requires the 'repo' scope.
Expand Down Expand Up @@ -360,7 +362,13 @@ items:
...
```

Or, the package revision contents can be saved on local disk for direct introspection or editing:
One of the driving motivations for the Package Orchestration service is enabling
WYSIWYG authoring of packages, including their contents, in highly usable UIs.
Porch therefore supports reading and updating package *contents*.

In addition to using a [UI](https://kpt.dev/guides/namespace-provisioning-ui/) with Porch, we
can change the package contents by pulling the package from Porch onto the local
disk, make any desired changes, and then pushing the updated contents to Porch.
Comment on lines +365 to +371
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good but im not sure what this UI is. ive personally never used it i dont think, is this a KPT UI, a porch one? where does it apply and if so it needs to be specified which project it belongs to i think this needs further clarification


```bash
$ porchctl rpkg pull -n porch-demo porch-test.network-function.innerhome ./innerhome
Expand All @@ -374,6 +382,86 @@ $ find innerhome
./innerhome/package-context.yaml
```

The command downloaded the `innerhome/v1` package revision contents and saved
them in the `./innerhome` directory. Now you will make some changes.

First, note that even though Porch updated the namespace name (in
`namespace.yaml`) to `innerhome` when the package was cloned, the `README.md`
was not updated. Let's fix it first.

Open the `README.md` in your favorite editor and update its contents, for
example:

```
# innerhome

## Description
kpt package for provisioning Innerhome namespace
```

In the second change, add a new mutator to the `Kptfile` pipeline. Use the
[set-labels](https://catalog.kpt.dev/set-labels/v0.1/) function which will add
labels to all resources in the package. Add the following mutator to the
`Kptfile` `pipeline` section:

```yaml
- image: gcr.io/kpt-fn/set-labels:v0.1.5
configMap:
color: orange
fruit: apple
```

The whole `pipeline` section now looks like this:

```yaml
pipeline:
mutators:
- image: gcr.io/kpt-fn/set-namespace:v0.4.1
configPath: package-context.yaml
- image: gcr.io/kpt-fn/apply-replacements:v0.1.1
configPath: update-rolebinding.yaml
- image: gcr.io/kpt-fn/set-labels:v0.1.5
configMap:
color: orange
fruit: apple
```

Save the changes and push the package contents back to the server:

```sh
# Push updated package contents to the server
$ porchctl rpkg push -n porch-demo porch-test.network-function.innerhome ./innerhome -ndefault
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

im pretty sure the "-ndefault" at the end is incorrect and should be removed

```

Now, pull the contents of the package revision again, and inspect one of the
configuration files.

```sh
# Pull the updated package contents to local drive for inspection:
$ porchctl rpkg pull -n porch-demo porch-test.network-function.innerhome ./updated-innerhome -ndefault
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as comment above


# Inspect updated-innerhome/namespace.yaml
$ cat updated-innerhome/namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
name: innerhome
labels:
color: orange
fruit: apple
spec: {}
```

The updated namespace now has new labels! What happened?

Whenever package is updated during the authoring process, Porch automatically
re-renders the package to make sure that all mutators and validators are
executed. So when we added the new `set-labels` mutator, as soon as we pushed
the updated package contents to Porch, Porch re-rendered the package and
the `set-labels` function applied the labels we requested (`color: orange` and
`fruit: apple`).
Comment on lines +458 to +463
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it only re-renders a package if it notices a change in the current pipelines functions (e.g. version of image ran set-namespace:v0.4.1 changed to v0.4.2 or something along the lines or a change to the config used for that function e.g. configPath: package-context.yaml either new file or changes were made to the contents of this input ) or a new function was added to the pipeline list.

This is done for efficient usage e.g. no need to rerun whole package renders if no changes have been made to the render pipeline.

e.g. if the pipeline had not added the new function the scan of the pipeline would have seen

pipeline:
  mutators:
  - image: gcr.io/kpt-fn/set-namespace:v0.4.1 ### did change happen here? ans=no ###
    configPath: package-context.yaml  ### did change happen here? ans=no ###
  - image: gcr.io/kpt-fn/apply-replacements:v0.1.1   ### did change happen here? ans=no ###
    configPath: update-rolebinding.yaml  ### did change happen here? ans=no ###
  - image: gcr.io/kpt-fn/set-labels:v0.1.5 ### <---- new func added
    configMap: ### <---- new input to func added
      color: orange
      fruit: apple


## Authoring Packages

Several commands in the `porchctl rpkg` group support package authoring:
Expand Down Expand Up @@ -408,7 +496,7 @@ Additional flags supported by the `porchctl rpkg init` command are:
* `--site` - Link to page with information about the package revision.


Use `porchctl rpkg clone` command to create a _downstream_ package revision by cloning an _upstream_ package revision:
Use `porchctl rpkg clone` command to create a _downstream_ package revision by cloning an _upstream_ package revision. You can find out more about the _upstream_ and _downstream_ sections of the `Kptfile` in a [Getting a Package](https://kpt.dev/book/03-packages/01-getting-a-package).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this link is broken now i think goes to 404 not found in kpt docs


```bash
$ porchctl rpkg clone porch-test.new-package.my-workspace new-package-clone --repository=porch-deployment -n porch-demo
Expand All @@ -420,6 +508,15 @@ NAME PACKAGE WORKSPACENAME REVI
porch-deployment.new-package-clone.v1 new-package-clone v1 0 false Draft porch-deployment
```

{{% alert title="Note" color="primary" %}}
A cloned package must be created in a repository in the same namespace as
the source package. Cloning a package with the Package Orchestration Service
retains a reference to the upstream package revision in the clone, and
cross-namespace references are not allowed. Package revisions in repositories
in other namespaces can be cloned using a reference directly to the underlying
oci or git repository as described below.
{{% /alert %}}

Comment on lines +511 to +519
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good addition. will need to be further clarified in a more in depth "porch operations" like section where we go in detail about what a clone does fundamentally but for this cli section this high level description is good

`porchctl rpkg clone` can also be used to clone package revisions that are in repositories not registered with Porch, for
example:

Expand Down Expand Up @@ -463,6 +560,13 @@ $ porchctl rpkg get porch-test.network-function.great-outdoors -n porch-demo
NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY
porch-test.network-function.great-outdoors network-function great-outdoors 0 false Draft porch-test
```
Unlike `clone` of a package which establishes the upstream-downstream
relationship between the respective packages, and updates the `Kptfile`
to reflect the relationship, the `copy` command does *not* change the
upstream-downstream relationships. The copy of a package shares the same
upstream package as the package from which it was copied. Specifically,
in this case both packages have identical contents,
including upstream information, and differ in revision only.
Comment on lines +563 to +569
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good high level description. another docs section in porch will need to explain at low level the copy also similar to comment above.


The `porchctl rpkg pull` and `porchctl rpkg push` commands can be used to update the resources (package revision contents) of a package _draft_:

Expand Down
54 changes: 54 additions & 0 deletions content/en/docs/porch/user-guides/preparing-the-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -873,6 +873,60 @@ status:
```
</details>

## The porchctl command

The `porchtcl` command is an administration command for acting on Porch `Repository` (repo) and `PackageRevision` (rpkg)
CRs. See its [documentation for usage information](porchctl-cli-guide.md).

Check that <code>porchctl</code> lists our repositories:</summary>

```bash
porchctl repo -n porch-demo get
NAME TYPE CONTENT DEPLOYMENT READY ADDRESS
edge1 git Package true True http://172.18.255.200:3000/nephio/edge1.git
external-blueprints git Package false True https://github.com/nephio-project/free5gc-packages.git
management git Package false True http://172.18.255.200:3000/nephio/management.git
```

<details>
<summary>Check that porchctl lists our remote packages (PackageRevisions):</summary>

```
porchctl rpkg -n porch-demo get
NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY
external-blueprints-922121d0bcdd56bfa8cae6c375720e2b5f358ab0 free5gc-cp main main false Published external-blueprints
external-blueprints-dabbc422fdf0b8e5942e767d929b524e25f7eef9 free5gc-cp v1 v1 true Published external-blueprints
external-blueprints-716aae722092dbbb9470e56079b90ad76ec8f0d5 free5gc-operator main main false Published external-blueprints
external-blueprints-d65dc89f7a2472650651e9aea90edfcc81a9afc6 free5gc-operator v1 v1 false Published external-blueprints
external-blueprints-9fee880e8fa52066f052c9cae7aac2e2bc1b5a54 free5gc-operator v2 v2 false Published external-blueprints
external-blueprints-91d60ee31d2d0a1a6d5f1807593d5419434accd3 free5gc-operator v3 v3 false Published external-blueprints
external-blueprints-21f19a0641cf520e7dc6268e64c58c2c30c27036 free5gc-operator v4 v4 false Published external-blueprints
external-blueprints-bf2e7522ee92680bd49571ab309e3f61320cf36d free5gc-operator v5 v5 true Published external-blueprints
external-blueprints-c1b9ecb73118e001ab1d1213e6a2c94ab67a0939 free5gc-upf main main false Published external-blueprints
external-blueprints-5d48b1516e7b1ea15830ffd76b230862119981bd free5gc-upf v1 v1 true Published external-blueprints
external-blueprints-ed97798b46b36d135cf23d813eccad4857dff90f pkg-example-amf-bp main main false Published external-blueprints
external-blueprints-ed744bfdf4a4d15d4fcf3c46fde27fd6ac32d180 pkg-example-amf-bp v1 v1 false Published external-blueprints
external-blueprints-5489faa80782f91f1a07d04e206935d14c1eb24c pkg-example-amf-bp v2 v2 false Published external-blueprints
external-blueprints-16e2255bd433ef532684a3c1434ae0bede175107 pkg-example-amf-bp v3 v3 false Published external-blueprints
external-blueprints-7689cc6c953fa83ea61283983ce966dcdffd9bae pkg-example-amf-bp v4 v4 false Published external-blueprints
external-blueprints-caff9609883eea7b20b73b7425e6694f8eb6adc3 pkg-example-amf-bp v5 v5 true Published external-blueprints
external-blueprints-00b6673c438909975548b2b9f20c2e1663161815 pkg-example-smf-bp main main false Published external-blueprints
external-blueprints-4f7dfbede99dc08f2b5144ca550ca218109c52f2 pkg-example-smf-bp v1 v1 false Published external-blueprints
external-blueprints-3d9ab8f61ce1d35e264d5719d4b3c0da1ab02328 pkg-example-smf-bp v2 v2 false Published external-blueprints
external-blueprints-2006501702e105501784c78be9e7d57e426d85e8 pkg-example-smf-bp v3 v3 false Published external-blueprints
external-blueprints-c97ed7c13b3aa47cb257217f144960743aec1253 pkg-example-smf-bp v4 v4 false Published external-blueprints
external-blueprints-3bd78e46b014dac5cc0c58788c1820d043d61569 pkg-example-smf-bp v5 v5 true Published external-blueprints
external-blueprints-c3f660848d9d7a4df5481ec2e06196884778cd84 pkg-example-upf-bp main main false Published external-blueprints
external-blueprints-4cb00a17c1ee2585d6c187ba4d0211da960c0940 pkg-example-upf-bp v1 v1 false Published external-blueprints
external-blueprints-5903efe295026124e6fea926df154a72c5bd1ea9 pkg-example-upf-bp v2 v2 false Published external-blueprints
external-blueprints-16142d8d23c1b8e868a9524a1b21634c79b432d5 pkg-example-upf-bp v3 v3 false Published external-blueprints
external-blueprints-60ef45bb8f55b63556e7467f16088325022a7ece pkg-example-upf-bp v4 v4 false Published external-blueprints
external-blueprints-7757966cc7b965f1b9372370a4b382c8375a2b40 pkg-example-upf-bp v5 v5 true Published external-blueprints
Comment on lines +897 to +924
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this section is outdated in regards to the package names all of this pages examples will need to change new format e.g. "porch-test.network-function.great-outdoors" not "repo-name-hash#" e.g. "external-blueprints-7757966cc7b965f1b9372370a4b382c8375a2b40"

```
</details>

The output above is similar to the output of `kubectl get packagerevision -n porch-demo` above.

## Creating a blueprint in Porch

### Blueprint with no Kpt pipelines
Expand Down
Loading