Creating a Porch Basic Usage guide #254
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
I'm afraid that we have done a big update on the porch CLI user guide because teh old one was out of date and incorrect. |
✅ Deploy Preview for nephio ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Signed-off-by: Dominika Schweier <dominika.schweier@nokia.com>
Signed-off-by: Dominika Schweier <dominika.schweier@nokia.com>
|
@liamfallon @kispaljr Did some additional work on this PR. I added the Package Orchestration chapter from the kpt book (https://github.com/kptdev/kpt/blob/main/documentation/content/en/book/08-package-orchestration/_index.md) here under Use Cases. However, we noticed that it is almost exactly the same as the Using the Porch CLI tool page we have here in Nephio, under Porch. Only difference is that the kpt one has kpt commands while the Porch one has porchcli commands. Wondering if this Use Cases page is even needed at all. What are your thoughts? |
Signed-off-by: Dominika Schweier <dominika.schweier@nokia.com>
kpt alpha rpkg is defunct and has been replaced with porchctl rpkg |
So basically the Use Cases page would be duplicated content with outdated commands, thus not needed. |
I think most of it is already covered in the CLI guide yes. Although we may be missing some extra info. ie @liamfallon We should look to remove the "kpt alpha x" from the kpt docs etc. |
|
I've created kptdev/kpt#4235 to update the kpt documentation. Which alpha commands are deprecated? |
For sure the "rpkg" and "repo" commands have moved to porchctl. |
Signed-off-by: Dominika Schweier <dominika.schweier@nokia.com>
|
|
@efiacor @liamfallon So what we did was we merged content from the Use Cases to the Using the Porch CLI tool page. And since this Using the Porch CLI tool page would be the only page under Basic Usage, we decided to just toss that and move it back under Porch user guides. I copied and tried to rework some instructions on how to download and edit package, it starts around line 365. We are not sure if it is needed or the updates on it are correct, please check this part and let me know if. Thank you! |
|
/assign @liamfallon @efiacor |
| 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 |
There was a problem hiding this comment.
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
| 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. |
There was a problem hiding this comment.
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
|
|
||
| ```sh | ||
| # Push updated package contents to the server | ||
| $ porchctl rpkg push -n porch-demo porch-test.network-function.innerhome ./innerhome -ndefault |
There was a problem hiding this comment.
im pretty sure the "-ndefault" at the end is incorrect and should be removed
|
|
||
| ```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 |
There was a problem hiding this comment.
same as comment above
| 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`). |
There was a problem hiding this comment.
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|
|
||
|
|
||
| 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). |
There was a problem hiding this comment.
this link is broken now i think goes to 404 not found in kpt docs
| {{% 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 %}} | ||
|
|
There was a problem hiding this comment.
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
| 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. |
There was a problem hiding this comment.
good high level description. another docs section in porch will need to explain at low level the copy also similar to comment above.
| 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 |
There was a problem hiding this comment.
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"
Basic usage
Tutorial part of the “Install and use Porch” (Starting from "The porchctl command")
Using the Porch CLI tool
Merge https://kpt.dev/book/08-package-orchestration/02-quickstart, https://kpt.dev/book/08-package-orchestration/03-registering-a-repositoryto, https://kpt.dev/book/08-package-orchestration/04-package-authoring and https://kpt.dev/book/08-package-orchestration/05-package-lifecycle here