diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md index 6b5d1cb4..8b42eea4 100644 --- a/content/en/docs/porch/user-guides/porchctl-cli-guide.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -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. @@ -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 @@ -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 @@ -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: @@ -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 @@ -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: @@ -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_: diff --git a/content/en/docs/porch/user-guides/preparing-the-environment.md b/content/en/docs/porch/user-guides/preparing-the-environment.md index 338f7609..890b82ac 100644 --- a/content/en/docs/porch/user-guides/preparing-the-environment.md +++ b/content/en/docs/porch/user-guides/preparing-the-environment.md @@ -873,6 +873,60 @@ status: ``` +## 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 porchctl lists our repositories: + +```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 +``` + +
+Check that porchctl lists our remote packages (PackageRevisions): + +``` +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 +``` +
+ +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