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 7 commits into
base: main
Choose a base branch
from
+163 −4
Open

Creating a Porch Basic Usage guide #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 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
2570c48
Implemented Catalin's comments
lovesprung Oct 10, 2025
b38808d
Corrected broken link
lovesprung Oct 10, 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
113 changes: 109 additions & 4 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
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 @@ -344,7 +346,7 @@ spec:
The `porchctl rpkg pull` command can be used to read the package revision resources.

The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables
[chaining](https://kpt.dev/book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe)
[chaining](https://kpt.dev/book/04-using-functions/#chaining-functions-using-the-unix-pipe)
evaluation of functions on the package revision pulled from the Package Orchestration server.

```bash
Expand All @@ -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.

```bash
$ porchctl rpkg pull -n porch-demo porch-test.network-function.innerhome ./innerhome
Expand All @@ -374,6 +382,87 @@ $ 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
```

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

# 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 a package is updated during the authoring process, in case current functions
of the pipline were changed or a new function was added to the pipeline list,
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`).

## Authoring Packages

Several commands in the `porchctl rpkg` group support package authoring:
Expand Down Expand Up @@ -408,7 +497,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/#getting-a-package).

```bash
$ porchctl rpkg clone porch-test.new-package.my-workspace new-package-clone --repository=porch-deployment -n porch-demo
Expand All @@ -420,6 +509,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 %}}

`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 +561,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.

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
porch-test.network-function.great-outdoors free5gc-cp main main false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-cp v1 v1 true Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator main main false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator v1 v1 false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator v2 v2 false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator v3 v3 false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator v4 v4 false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-operator v5 v5 true Published external-blueprints
porch-test.network-function.great-outdoors free5gc-upf main main false Published external-blueprints
porch-test.network-function.great-outdoors free5gc-upf v1 v1 true Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp main main false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp v1 v1 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp v2 v2 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp v3 v3 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp v4 v4 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-amf-bp v5 v5 true Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp main main false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp v1 v1 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp v2 v2 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp v3 v3 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp v4 v4 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-smf-bp v5 v5 true Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp main main false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp v1 v1 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp v2 v2 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp v3 v3 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp v4 v4 false Published external-blueprints
porch-test.network-function.great-outdoors pkg-example-upf-bp v5 v5 true Published external-blueprints
```
</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