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..2a7fd864 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. @@ -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,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 +``` + +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 + +# 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`). + ## Authoring Packages Several commands in the `porchctl rpkg` group support package authoring: @@ -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). ```bash $ porchctl rpkg clone porch-test.new-package.my-workspace new-package-clone --repository=porch-deployment -n porch-demo @@ -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 %}} + `porchctl rpkg clone` can also be used to clone package revisions that are in repositories not registered with Porch, for example: @@ -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. 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..efa31386 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 +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 +``` +
+ +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