From 483d7d739e0754dadd53b8c00359e6eade8b6253 Mon Sep 17 00:00:00 2001 From: Dominika Schweier Date: Thu, 24 Jul 2025 11:27:50 +0200 Subject: [PATCH 1/4] Creating a Porch Basic Usage guide --- content/en/docs/porch/basic-usage/_index.md | 6 + .../porchctl-cli-guide.md | 0 .../en/docs/porch/basic-usage/tutorials.md | 810 ++++++++++++++++++ .../user-guides/install-and-using-porch.md | 806 +---------------- 4 files changed, 817 insertions(+), 805 deletions(-) create mode 100644 content/en/docs/porch/basic-usage/_index.md rename content/en/docs/porch/{user-guides => basic-usage}/porchctl-cli-guide.md (100%) create mode 100644 content/en/docs/porch/basic-usage/tutorials.md diff --git a/content/en/docs/porch/basic-usage/_index.md b/content/en/docs/porch/basic-usage/_index.md new file mode 100644 index 00000000..45c1702d --- /dev/null +++ b/content/en/docs/porch/basic-usage/_index.md @@ -0,0 +1,6 @@ +--- +title: "Porch basic usage" +type: docs +weight: 7 +description: +--- \ No newline at end of file diff --git a/content/en/docs/porch/user-guides/porchctl-cli-guide.md b/content/en/docs/porch/basic-usage/porchctl-cli-guide.md similarity index 100% rename from content/en/docs/porch/user-guides/porchctl-cli-guide.md rename to content/en/docs/porch/basic-usage/porchctl-cli-guide.md diff --git a/content/en/docs/porch/basic-usage/tutorials.md b/content/en/docs/porch/basic-usage/tutorials.md new file mode 100644 index 00000000..e1c1385f --- /dev/null +++ b/content/en/docs/porch/basic-usage/tutorials.md @@ -0,0 +1,810 @@ +--- +title: "Tutorials" +type: docs +weight: 1 +description: +--- + +## 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 + +Create a new package in our *management* repository using the sample *network-function* package provided. This network +function Kpt package is a demo Kpt package that installs [Nginx](https://github.com/nginx). + +``` +porchctl -n porch-demo rpkg init network-function --repository=management --workspace=v1 +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 created +porchctl -n porch-demo rpkg get --name network-function +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Draft management +``` + +This command creates a new *PackageRevision* CR in porch and also creates a branch called *network-function/v1* in our +Gitea *management* repository. Use the Gitea web UI to confirm that the branch has been created and note that it only has +default content as yet. + +We now pull the package we have initialized from Porch. + +``` +porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function +``` + +We update the initialized package and add our local changes. +``` +cp blueprints/local-changes/network-function/* blueprints/initialized/network-function +``` + +Now, we push the package contents to porch: +``` +porchctl -n porch-demo rpkg push management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function +``` + +Check on the Gitea web UI and we can see that the actual package contents have been pushed. + +Now we propose and approve the package. + +``` +porchctl -n porch-demo rpkg propose management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 proposed + +porchctl -n porch-demo rpkg get --name network-function +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Proposed management + +porchctl -n porch-demo rpkg approve management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 approved + +porchctl -n porch-demo rpkg get --name network-function +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management + +``` + +Once we approve the package, the package is merged into the main branch in the *management* repository and the branch called +*network-function/v1* in that repository is removed. Use the Gitea UI to verify this. We now have our blueprint package in our +*management* repository and we can deploy this package into workload clusters. + +### Blueprint with a Kpt pipeline + +The second blueprint in the *blueprint* directory is called *network-function-auto-namespace*. This network +function is exactly the same as the *network-function* package except that it has a Kpt function that automatically +creates a namespace with the namespace configured in the name field in the *package-context.yaml* file. Note that no +namespace is defined in the metadata of the *deployment.yaml* file of this Kpt package. + +We use the same sequence of commands again to publish our blueprint package for *network-function-auto-namespace*. + +``` +porchctl -n porch-demo rpkg init network-function-auto-namespace --repository=management --workspace=v1 +management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 created + +porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace + +cp blueprints/local-changes/network-function-auto-namespace/* blueprints/initialized/network-function-auto-namespace + +porchctl -n porch-demo rpkg push management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace +``` + +Examine the *drafts/network-function-auto-namespace/v1* branch in Gitea. Notice that the set-namespace Kpt function in +the pipeline in the *Kptfile* has set the namespace in the *deployment.yaml* file to the value default-namespace-name, +which it read from the *package-context.yaml* file. + +Now we propose and approve the package. + +``` +porchctl -n porch-demo rpkg propose management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 +management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 proposed + +porchctl -n porch-demo rpkg approve management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 +management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 approved + +porchctl -n porch-demo rpkg get --name network-function-auto-namespace +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management +management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management + +``` + +## Deploying a blueprint onto a workload cluster + +### Blueprint with no Kpt pipelines + +The process of deploying a blueprint package from our *management* repository clones the package, then modifies it for use on +the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the *edge1* repository. +Remember that the *edge1* repository is being monitored by configsync from the edge1 cluster, so once the package appears in +the *edge1* repository on the management cluster, it will be pulled by configsync and applied to the edge1 cluster. + +``` +porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp + +find tmp_packages_for_deployment/edge1-network-function-a.clone.tmp + +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/deployment.yaml +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/README.md +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/Kptfile +tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/package-context.yaml +``` +The package we created in the last section is cloned. We now remove the original metadata from the package. +``` +rm tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata +``` + +We use a *kpt* function to change the namespace that will be used for the deployment of the network function. + +``` +kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -- namespace=edge1-network-function-a + +[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" +[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" in 300ms + Results: + [info]: namespace "" updated to "edge1-network-function-a", 1 value(s) changed +``` + +We now initialize and push the package to the *edge1* repository: + +``` +porchctl -n porch-demo rpkg init edge1-network-function-a --repository=edge1 --workspace=v1 +edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 created + +porchctl -n porch-demo rpkg pull edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a + +cp tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-a +rm -fr tmp_packages_for_deployment/edge1-network-function-a.clone.tmp + +porchctl -n porch-demo rpkg push edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a + +porchctl -n porch-demo rpkg get --name edge1-network-function-a +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 false Draft edge1 +``` + +You can verify that the package is in the *network-function-a/v1* branch of the deployment repository using the Gitea web UI. + + +Check that the *edge1-network-function-a* package is not deployed on the edge1 cluster yet: +``` +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -n edge1-network-function-a +No resources found in network-function-a namespace. + +``` + +We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers +configsync to apply the package to the edge1 cluster. + +``` +export KUBECONFIG=~/.kube/kind-management-config + +porchctl -n porch-demo rpkg propose edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 +edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 proposed + +porchctl -n porch-demo rpkg approve edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 +edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 approved + +porchctl -n porch-demo rpkg get --name edge1-network-function-a +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 v1 true Published edge1 +``` + +We can now check that the *network-function-a* package is deployed on the edge1 cluster and that the pod is running +``` +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -n edge1-network-function-a +No resources found in network-function-a namespace. + +kubectl get pod -n edge1-network-function-a +NAME READY STATUS RESTARTS AGE +network-function-9779fc9f5-4rqp2 1/1 ContainerCreating 0 9s + +kubectl get pod -n edge1-network-function-a +NAME READY STATUS RESTARTS AGE +network-function-9779fc9f5-4rqp2 1/1 Running 0 44s +``` + +### Blueprint with a Kpt pipeline + +The process for deploying a blueprint with a *Kpt* pipeline runs the Kpt pipeline automatically with whatever configuration we give it. Rather than explicitly running a *Kpt* function to change the namespace, we will specify the namespace as configuration and the pipeline will apply it to the deployment. + +``` +porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp + +find tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp + +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/deployment.yaml +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/README.md +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/Kptfile +tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/package-context.yaml +``` + +We now remove the original metadata from the package. +``` +rm tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata +``` + +The package we created in the last section is cloned. We now initialize and push the package to the *edge1* repository: + +``` +porchctl -n porch-demo rpkg init edge1-network-function-auto-namespace-a --repository=edge1 --workspace=v1 +edge1-48997da49ca0a733b0834c1a27943f1a0e075180 created + +porchctl -n porch-demo rpkg pull edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a + +cp tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-auto-namespace-a +rm -fr tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp +``` + + +We now simply configure the namespace we want to apply. edit the *tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml* file and set the namespace to use: + +``` +8c8 +< name: default-namespace-name +--- +> name: edge1-network-function-auto-namespace-a +``` + +We now push the package to the *edge1* repository: + +``` +porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a +[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" +[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" + Results: + [info]: namespace "default-namespace-name" updated to "edge1-network-function-auto-namespace-a", 1 value(s) changed + +porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a +``` + +You can verify that the package is in the *network-function-auto-namespace-a/v1* branch of the deployment repository using the +Gitea web UI. You can see that the kpt pipeline fired and set the edge1-network-function-auto-namespace-a namespace in +the *deployment.yaml* file on the *drafts/edge1-network-function-auto-namespace-a/v1* branch on the *edge1* repository in +Gitea. + +Check that the *edge1-network-function-auto-namespace-a* package is not deployed on the edge1 cluster yet: +``` +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -n edge1-network-function-auto-namespace-a +No resources found in network-function-auto-namespace-a namespace. + +``` + +We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers +configsync to apply the package to the edge1 cluster. + +``` +export KUBECONFIG=~/.kube/kind-management-config + +porchctl -n porch-demo rpkg propose edge1-48997da49ca0a733b0834c1a27943f1a0e075180 +edge1-48997da49ca0a733b0834c1a27943f1a0e075180 proposed + +porchctl -n porch-demo rpkg approve edge1-48997da49ca0a733b0834c1a27943f1a0e075180 +edge1-48997da49ca0a733b0834c1a27943f1a0e075180 approved + +porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 +``` + +We can now check that the *network-function-auto-namespace-a* package is deployed on the edge1 cluster and that the pod is running +``` +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -n edge1-network-function-auto-namespace-a +No resources found in network-function-auto-namespace-a namespace. + +kubectl get pod -n edge1-network-function-auto-namespace-a +NAME READY STATUS RESTARTS AGE +network-function-auto-namespace-85bc658d67-rbzt6 1/1 ContainerCreating 0 3s + +kubectl get pod -n edge1-network-function-auto-namespace-a +NAME READY STATUS RESTARTS AGE +network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 0 10s +``` + +## Deploying using Package Variant Sets + +### Simple PackageVariantSet + +The PackageVariant CR is defined as: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha2 +kind: PackageVariantSet + +metadata: + name: network-function + namespace: porch-demo + +spec: + upstream: + repo: management + package: network-function + revision: v1 + targets: + - repositories: + - name: edge1 + packageNames: + - network-function-b + - network-function-c +``` + +In this very simple PackageVariant, the *network-function* package in the *management* repository is cloned into the *edge1* +repository as the *network-function-b* and *network-function-c* package variants. + +{{% alert title="Note" color="primary" %}} + +This simple package variant does not specify any configuration changes. Normally, as well as cloning and renaming, +configuration changes would be applied on a package variant. + +Use `kubectl explain PackageVariantSet` to get help on the structure of the PackageVariantSet CRD. + +{{% /alert %}} + +Applying the PackageVariantSet creates the new packages as draft packages: + +```bash +kubectl apply -f simple-variant.yaml + +kubectl get PackageRevisions -n porch-demo | grep -v 'external-blueprints' +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-bc8294d121360ad305c9a826a8734adcf5f1b9c0 network-function-a v1 main false Published edge1 +edge1-9b4b4d99c43b5c5c8489a47bbce9a61f79904946 network-function-a v1 v1 true Published edge1 +edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 +edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 +management-49580fc22bcf3bf51d334a00b6baa41df597219e network-function v1 main false Published management +management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management + +porchctl -n porch-demo rpkg get --name network-function-b +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 + +porchctl -n porch-demo rpkg get --name network-function-c +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 +``` + +We can see that our two new packages are created as draft packages on the *edge1* repository. We can also examine the +*PacakgeVariant* CRs that have been created: + +```bash +kubectl get PackageVariant -n porch-demo +NAMESPACE NAME READY STATUS RESTARTS AGE +network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h +network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s +network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s +``` + + +It is also interesting to examine the YAML of the *PackageVariant*: + +```yaml +kubectl get PackageVariant -n porch-demo -o yaml +apiVersion: v1 +items: +- apiVersion: config.porch.kpt.dev/v1alpha1 + kind: PackageVariant + metadata: + creationTimestamp: "2024-01-09T15:00:00Z" + finalizers: + - config.porch.kpt.dev/packagevariants + generation: 1 + labels: + config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 + name: network-function-edge1-network-function-b + namespace: porch-demo + ownerReferences: + - apiVersion: config.porch.kpt.dev/v1alpha2 + controller: true + kind: PackageVariantSet + name: network-function + uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 + resourceVersion: "237053" + uid: 7a81099c-5a0b-49d8-b73c-48e33cd134e5 + spec: + downstream: + package: network-function-b + repo: edge1 + upstream: + package: network-function + repo: management + revision: v1 + status: + conditions: + - lastTransitionTime: "2024-01-09T15:00:00Z" + message: all validation checks passed + reason: Valid + status: "False" + type: Stalled + - lastTransitionTime: "2024-01-09T15:00:31Z" + message: successfully ensured downstream package variant + reason: NoErrors + status: "True" + type: Ready + downstreamTargets: + - name: edge1-a31b56c7db509652f00724dd49746660757cd98a +- apiVersion: config.porch.kpt.dev/v1alpha1 + kind: PackageVariant + metadata: + creationTimestamp: "2024-01-09T15:00:00Z" + finalizers: + - config.porch.kpt.dev/packagevariants + generation: 1 + labels: + config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 + name: network-function-edge1-network-function-c + namespace: porch-demo + ownerReferences: + - apiVersion: config.porch.kpt.dev/v1alpha2 + controller: true + kind: PackageVariantSet + name: network-function + uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 + resourceVersion: "237056" + uid: da037d0a-9a7a-4e85-842c-1324e9da819a + spec: + downstream: + package: network-function-c + repo: edge1 + upstream: + package: network-function + repo: management + revision: v1 + status: + conditions: + - lastTransitionTime: "2024-01-09T15:00:01Z" + message: all validation checks passed + reason: Valid + status: "False" + type: Stalled + - lastTransitionTime: "2024-01-09T15:00:31Z" + message: successfully ensured downstream package variant + reason: NoErrors + status: "True" + type: Ready + downstreamTargets: + - name: edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 +kind: List +metadata: + resourceVersion: "" +``` + +We now want to customize and deploy our two packages. To do this we must pull the packages locally, render the *kpt* +functions, and then push the rendered packages back up to the *edge1* repository. + +```bash +porchctl rpkg pull edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo +kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-b -- namespace=network-function-b +porchctl rpkg push edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo + +porchctl rpkg pull edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo +kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-c -- namespace=network-function-c +porchctl rpkg push edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo +``` + +Check that the namespace has been updated on the two packages in the *edge1* repository using the Gitea web UI. + +Now our two packages are ready for deployment: + +```bash +porchctl rpkg propose edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo +edge1-a31b56c7db509652f00724dd49746660757cd98a proposed + +porchctl rpkg approve edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo +edge1-a31b56c7db509652f00724dd49746660757cd98a approved + +porchctl rpkg propose edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo +edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 proposed + +porchctl rpkg approve edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo +edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 approved +``` + +We can now check that the *network-function-b* and *network-function-c* packages are deployed on the edge1 cluster and +that the pods are running + +```bash +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h +network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s +network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s +``` + +### Using a PackageVariantSet to automatically set the package name and package namespace + +The *PackageVariant* CR defined as: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha2 +kind: PackageVariantSet +metadata: + name: network-function-auto-namespace + namespace: porch-demo +spec: + upstream: + repo: management + package: network-function-auto-namespace + revision: v1 + targets: + - repositories: + - name: edge1 + packageNames: + - network-function-auto-namespace-x + - network-function-auto-namespace-y + template: + downstream: + packageExpr: "target.package + '-cumulonimbus'" +``` + + +In this *PackageVariant*, the *network-function-auto-namespace* package in the *management* repository is cloned into the +*edge1* repository as the *network-function-auto-namespace-x* and *network-function-auto-namespace-y* package variants, +similar to the *PackageVariant* in *simple-variant.yaml*. + +An extra template section provided for the repositories in the PackageVariant: + +```yaml +template: + downstream: + packageExpr: "target.package + '-cumulus'" +``` + +This template means that each package in the spec.targets.repositories..packageNames list will have the suffix +-cumulus added to its name. This allows us to automatically generate unique package names. Applying the +*PackageVariantSet* also automatically sets a unique namespace for each network function because applying the +*PackageVariantSet* automatically triggers the Kpt pipeline in the *network-function-auto-namespace* *Kpt* package to +generate unique namespaces for each deployed package. + +{{% alert title="Note" color="primary" %}} + +Many other mutations can be performed using a *PackageVariantSet*. Use `kubectl explain PackageVariantSet` to get help on +the structure of the *PackageVariantSet* CRD to see the various mutations that are possible. + +{{% /alert %}} + +Applying the *PackageVariantSet* creates the new packages as draft packages: + +```bash +kubectl apply -f name-namespace-variant.yaml +packagevariantset.config.porch.kpt.dev/network-function-auto-namespace created + +kunectl get -n porch-demo PackageVariantSet network-function-auto-namespace +NAME AGE +network-function-auto-namespace 38s + +kubectl get PackageRevisions -n porch-demo | grep auto-namespace +edge1-1f521f05a684adfa8562bf330f7bc72b50e21cc5 edge1-network-function-auto-namespace-a v1 main false Published edge1 +edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 +edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 +edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 +management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management +management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management +``` + +{{% alert title="Note" color="primary" %}} + +The suffix `x-cumulonimbus` and `y-cumulonimbus` has been placed on the package names. + +{{% /alert %}} + +Examine the *edge1* repository on Gitea and you should see two new draft branches. + +- drafts/network-function-auto-namespace-x-cumulonimbus/packagevariant-1 +- drafts/network-function-auto-namespace-y-cumulonimbus/packagevariant-1 + +In these packages, you will see that: + +1. The package name has been generated as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus in all files in the packages +2. The namespace has been generated as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus respectively in the *demployment.yaml* files +3. The PackageVariant has set the data.name field as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus respectively in the *pckage-context.yaml* files + +This has all been performed automatically; we have not had to perform the +`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these changes as we had to in the +*simple-variant.yaml* case above. + +Now, let us explore the packages further: + +```bash +porchctl -n porch-demo rpkg get --name network-function-auto-namespace-x-cumulonimbus +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 + +porchctl -n porch-demo rpkg get --name network-function-auto-namespace-y-cumulonimbus +NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY +edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 +``` + +We can see that our two new packages are created as draft packages on the edge1 repository. We can also examine the +*PacakgeVariant* CRs that have been created: + +```bash +kubectl get PackageVariant -n porch-demo +NAME AGE +network-function-auto-namespace-edge1-network-function-35079f9f 3m41s +network-function-auto-namespace-edge1-network-function-d521d2c0 3m41s +network-function-edge1-network-function-b 38m +network-function-edge1-network-function-c 38m +``` + +It is also interesting to examine the YAML of a *PackageVariant*: + +```yaml +kubectl get PackageVariant -n porch-demo network-function-auto-namespace-edge1-network-function-35079f9f -o yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: PackageVariant +metadata: + creationTimestamp: "2024-01-24T15:10:19Z" + finalizers: + - config.porch.kpt.dev/packagevariants + generation: 1 + labels: + config.porch.kpt.dev/packagevariantset: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e + name: network-function-auto-namespace-edge1-network-function-35079f9f + namespace: porch-demo + ownerReferences: + - apiVersion: config.porch.kpt.dev/v1alpha2 + controller: true + kind: PackageVariantSet + name: network-function-auto-namespace + uid: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e + resourceVersion: "404083" + uid: 5ae69c2d-6aac-4942-b717-918325650190 +spec: + downstream: + package: network-function-auto-namespace-x-cumulonimbus + repo: edge1 + upstream: + package: network-function-auto-namespace + repo: management + revision: v1 +status: + conditions: + - lastTransitionTime: "2024-01-24T15:10:19Z" + message: all validation checks passed + reason: Valid + status: "False" + type: Stalled + - lastTransitionTime: "2024-01-24T15:10:49Z" + message: successfully ensured downstream package variant + reason: NoErrors + status: "True" + type: Ready + downstreamTargets: + - name: edge1-009659a8532552b86263434f68618554e12f4f7c +``` +Our two packages are ready for deployment: + +```bash +porchctl rpkg propose edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo +edge1-009659a8532552b86263434f68618554e12f4f7c proposed + +porchctl rpkg approve edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo +edge1-009659a8532552b86263434f68618554e12f4f7c approved + +porchctl rpkg propose edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo +edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e proposed + +porchctl rpkg approve edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo +edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e approved +``` + +We can now check that the packages are deployed on the edge1 cluster and that the pods are running + +```bash +export KUBECONFIG=~/.kube/kind-edge1-config + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 0/1 ContainerCreating 0 1s +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 10s +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 50s +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 51s +network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 0/1 ContainerCreating 0 1s +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m + +kubectl get pod -A | egrep '(NAMESPACE|network-function)' +NAMESPACE NAME READY STATUS RESTARTS AGE +edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h +edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h +network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 54s +network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 1/1 Running 0 4s +network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m +network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m +``` diff --git a/content/en/docs/porch/user-guides/install-and-using-porch.md b/content/en/docs/porch/user-guides/install-and-using-porch.md index 2971b8b9..5507d907 100644 --- a/content/en/docs/porch/user-guides/install-and-using-porch.md +++ b/content/en/docs/porch/user-guides/install-and-using-porch.md @@ -1292,808 +1292,4 @@ status: metadata: creationTimestamp: null ``` - - -## 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 - -Create a new package in our *management* repository using the sample *network-function* package provided. This network -function Kpt package is a demo Kpt package that installs [Nginx](https://github.com/nginx). - -``` -porchctl -n porch-demo rpkg init network-function --repository=management --workspace=v1 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 created -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Draft management -``` - -This command creates a new *PackageRevision* CR in porch and also creates a branch called *network-function/v1* in our -Gitea *management* repository. Use the Gitea web UI to confirm that the branch has been created and note that it only has -default content as yet. - -We now pull the package we have initialized from Porch. - -``` -porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function -``` - -We update the initialized package and add our local changes. -``` -cp blueprints/local-changes/network-function/* blueprints/initialized/network-function -``` - -Now, we push the package contents to porch: -``` -porchctl -n porch-demo rpkg push management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function -``` - -Check on the Gitea web UI and we can see that the actual package contents have been pushed. - -Now we propose and approve the package. - -``` -porchctl -n porch-demo rpkg propose management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 proposed - -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Proposed management - -porchctl -n porch-demo rpkg approve management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 approved - -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management - -``` - -Once we approve the package, the package is merged into the main branch in the *management* repository and the branch called -*network-function/v1* in that repository is removed. Use the Gitea UI to verify this. We now have our blueprint package in our -*management* repository and we can deploy this package into workload clusters. - -### Blueprint with a Kpt pipeline - -The second blueprint in the *blueprint* directory is called *network-function-auto-namespace*. This network -function is exactly the same as the *network-function* package except that it has a Kpt function that automatically -creates a namespace with the namespace configured in the name field in the *package-context.yaml* file. Note that no -namespace is defined in the metadata of the *deployment.yaml* file of this Kpt package. - -We use the same sequence of commands again to publish our blueprint package for *network-function-auto-namespace*. - -``` -porchctl -n porch-demo rpkg init network-function-auto-namespace --repository=management --workspace=v1 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 created - -porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace - -cp blueprints/local-changes/network-function-auto-namespace/* blueprints/initialized/network-function-auto-namespace - -porchctl -n porch-demo rpkg push management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace -``` - -Examine the *drafts/network-function-auto-namespace/v1* branch in Gitea. Notice that the set-namespace Kpt function in -the pipeline in the *Kptfile* has set the namespace in the *deployment.yaml* file to the value default-namespace-name, -which it read from the *package-context.yaml* file. - -Now we propose and approve the package. - -``` -porchctl -n porch-demo rpkg propose management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 proposed - -porchctl -n porch-demo rpkg approve management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 approved - -porchctl -n porch-demo rpkg get --name network-function-auto-namespace -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management - -``` - -## Deploying a blueprint onto a workload cluster - -### Blueprint with no Kpt pipelines - -The process of deploying a blueprint package from our *management* repository clones the package, then modifies it for use on -the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the *edge1* repository. -Remember that the *edge1* repository is being monitored by configsync from the edge1 cluster, so once the package appears in -the *edge1* repository on the management cluster, it will be pulled by configsync and applied to the edge1 cluster. - -``` -porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -find tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/deployment.yaml -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/README.md -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/Kptfile -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/package-context.yaml -``` -The package we created in the last section is cloned. We now remove the original metadata from the package. -``` -rm tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata -``` - -We use a *kpt* function to change the namespace that will be used for the deployment of the network function. - -``` -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -- namespace=edge1-network-function-a - -[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" -[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" in 300ms - Results: - [info]: namespace "" updated to "edge1-network-function-a", 1 value(s) changed -``` - -We now initialize and push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg init edge1-network-function-a --repository=edge1 --workspace=v1 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 created - -porchctl -n porch-demo rpkg pull edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a - -cp tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-a -rm -fr tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -porchctl -n porch-demo rpkg push edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a - -porchctl -n porch-demo rpkg get --name edge1-network-function-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 false Draft edge1 -``` - -You can verify that the package is in the *network-function-a/v1* branch of the deployment repository using the Gitea web UI. - - -Check that the *edge1-network-function-a* package is not deployed on the edge1 cluster yet: -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-a -No resources found in network-function-a namespace. - -``` - -We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers -configsync to apply the package to the edge1 cluster. - -``` -export KUBECONFIG=~/.kube/kind-management-config - -porchctl -n porch-demo rpkg propose edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 proposed - -porchctl -n porch-demo rpkg approve edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 approved - -porchctl -n porch-demo rpkg get --name edge1-network-function-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 v1 true Published edge1 -``` - -We can now check that the *network-function-a* package is deployed on the edge1 cluster and that the pod is running -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-a -No resources found in network-function-a namespace. - -kubectl get pod -n edge1-network-function-a -NAME READY STATUS RESTARTS AGE -network-function-9779fc9f5-4rqp2 1/1 ContainerCreating 0 9s - -kubectl get pod -n edge1-network-function-a -NAME READY STATUS RESTARTS AGE -network-function-9779fc9f5-4rqp2 1/1 Running 0 44s -``` - -### Blueprint with a Kpt pipeline - -The process for deploying a blueprint with a *Kpt* pipeline runs the Kpt pipeline automatically with whatever configuration we give it. Rather than explicitly running a *Kpt* function to change the namespace, we will specify the namespace as configuration and the pipeline will apply it to the deployment. - -``` -porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp - -find tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp - -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/deployment.yaml -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/README.md -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/Kptfile -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/package-context.yaml -``` - -We now remove the original metadata from the package. -``` -rm tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata -``` - -The package we created in the last section is cloned. We now initialize and push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg init edge1-network-function-auto-namespace-a --repository=edge1 --workspace=v1 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 created - -porchctl -n porch-demo rpkg pull edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a - -cp tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-auto-namespace-a -rm -fr tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp -``` - - -We now simply configure the namespace we want to apply. edit the *tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml* file and set the namespace to use: - -``` -8c8 -< name: default-namespace-name ---- -> name: edge1-network-function-auto-namespace-a -``` - -We now push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a -[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" -[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" - Results: - [info]: namespace "default-namespace-name" updated to "edge1-network-function-auto-namespace-a", 1 value(s) changed - -porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a -``` - -You can verify that the package is in the *network-function-auto-namespace-a/v1* branch of the deployment repository using the -Gitea web UI. You can see that the kpt pipeline fired and set the edge1-network-function-auto-namespace-a namespace in -the *deployment.yaml* file on the *drafts/edge1-network-function-auto-namespace-a/v1* branch on the *edge1* repository in -Gitea. - -Check that the *edge1-network-function-auto-namespace-a* package is not deployed on the edge1 cluster yet: -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-auto-namespace-a -No resources found in network-function-auto-namespace-a namespace. - -``` - -We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers -configsync to apply the package to the edge1 cluster. - -``` -export KUBECONFIG=~/.kube/kind-management-config - -porchctl -n porch-demo rpkg propose edge1-48997da49ca0a733b0834c1a27943f1a0e075180 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 proposed - -porchctl -n porch-demo rpkg approve edge1-48997da49ca0a733b0834c1a27943f1a0e075180 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 approved - -porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 -``` - -We can now check that the *network-function-auto-namespace-a* package is deployed on the edge1 cluster and that the pod is running -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-auto-namespace-a -No resources found in network-function-auto-namespace-a namespace. - -kubectl get pod -n edge1-network-function-auto-namespace-a -NAME READY STATUS RESTARTS AGE -network-function-auto-namespace-85bc658d67-rbzt6 1/1 ContainerCreating 0 3s - -kubectl get pod -n edge1-network-function-auto-namespace-a -NAME READY STATUS RESTARTS AGE -network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 0 10s -``` - -## Deploying using Package Variant Sets - -### Simple PackageVariantSet - -The PackageVariant CR is defined as: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha2 -kind: PackageVariantSet - -metadata: - name: network-function - namespace: porch-demo - -spec: - upstream: - repo: management - package: network-function - revision: v1 - targets: - - repositories: - - name: edge1 - packageNames: - - network-function-b - - network-function-c -``` - -In this very simple PackageVariant, the *network-function* package in the *management* repository is cloned into the *edge1* -repository as the *network-function-b* and *network-function-c* package variants. - -{{% alert title="Note" color="primary" %}} - -This simple package variant does not specify any configuration changes. Normally, as well as cloning and renaming, -configuration changes would be applied on a package variant. - -Use `kubectl explain PackageVariantSet` to get help on the structure of the PackageVariantSet CRD. - -{{% /alert %}} - -Applying the PackageVariantSet creates the new packages as draft packages: - -```bash -kubectl apply -f simple-variant.yaml - -kubectl get PackageRevisions -n porch-demo | grep -v 'external-blueprints' -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-bc8294d121360ad305c9a826a8734adcf5f1b9c0 network-function-a v1 main false Published edge1 -edge1-9b4b4d99c43b5c5c8489a47bbce9a61f79904946 network-function-a v1 v1 true Published edge1 -edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 -management-49580fc22bcf3bf51d334a00b6baa41df597219e network-function v1 main false Published management -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management - -porchctl -n porch-demo rpkg get --name network-function-b -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 - -porchctl -n porch-demo rpkg get --name network-function-c -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 -``` - -We can see that our two new packages are created as draft packages on the *edge1* repository. We can also examine the -*PacakgeVariant* CRs that have been created: - -```bash -kubectl get PackageVariant -n porch-demo -NAMESPACE NAME READY STATUS RESTARTS AGE -network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h -network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s -network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s -``` - - -It is also interesting to examine the YAML of the *PackageVariant*: - -```yaml -kubectl get PackageVariant -n porch-demo -o yaml -apiVersion: v1 -items: -- apiVersion: config.porch.kpt.dev/v1alpha1 - kind: PackageVariant - metadata: - creationTimestamp: "2024-01-09T15:00:00Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - name: network-function-edge1-network-function-b - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function - uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - resourceVersion: "237053" - uid: 7a81099c-5a0b-49d8-b73c-48e33cd134e5 - spec: - downstream: - package: network-function-b - repo: edge1 - upstream: - package: network-function - repo: management - revision: v1 - status: - conditions: - - lastTransitionTime: "2024-01-09T15:00:00Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-09T15:00:31Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-a31b56c7db509652f00724dd49746660757cd98a -- apiVersion: config.porch.kpt.dev/v1alpha1 - kind: PackageVariant - metadata: - creationTimestamp: "2024-01-09T15:00:00Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - name: network-function-edge1-network-function-c - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function - uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - resourceVersion: "237056" - uid: da037d0a-9a7a-4e85-842c-1324e9da819a - spec: - downstream: - package: network-function-c - repo: edge1 - upstream: - package: network-function - repo: management - revision: v1 - status: - conditions: - - lastTransitionTime: "2024-01-09T15:00:01Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-09T15:00:31Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 -kind: List -metadata: - resourceVersion: "" -``` - -We now want to customize and deploy our two packages. To do this we must pull the packages locally, render the *kpt* -functions, and then push the rendered packages back up to the *edge1* repository. - -```bash -porchctl rpkg pull edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-b -- namespace=network-function-b -porchctl rpkg push edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo - -porchctl rpkg pull edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-c -- namespace=network-function-c -porchctl rpkg push edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo -``` - -Check that the namespace has been updated on the two packages in the *edge1* repository using the Gitea web UI. - -Now our two packages are ready for deployment: - -```bash -porchctl rpkg propose edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo -edge1-a31b56c7db509652f00724dd49746660757cd98a proposed - -porchctl rpkg approve edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo -edge1-a31b56c7db509652f00724dd49746660757cd98a approved - -porchctl rpkg propose edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 proposed - -porchctl rpkg approve edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 approved -``` - -We can now check that the *network-function-b* and *network-function-c* packages are deployed on the edge1 cluster and -that the pods are running - -```bash -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h -network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s -network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s -``` - -### Using a PackageVariantSet to automatically set the package name and package namespace - -The *PackageVariant* CR defined as: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha2 -kind: PackageVariantSet -metadata: - name: network-function-auto-namespace - namespace: porch-demo -spec: - upstream: - repo: management - package: network-function-auto-namespace - revision: v1 - targets: - - repositories: - - name: edge1 - packageNames: - - network-function-auto-namespace-x - - network-function-auto-namespace-y - template: - downstream: - packageExpr: "target.package + '-cumulonimbus'" -``` - - -In this *PackageVariant*, the *network-function-auto-namespace* package in the *management* repository is cloned into the -*edge1* repository as the *network-function-auto-namespace-x* and *network-function-auto-namespace-y* package variants, -similar to the *PackageVariant* in *simple-variant.yaml*. - -An extra template section provided for the repositories in the PackageVariant: - -```yaml -template: - downstream: - packageExpr: "target.package + '-cumulus'" -``` - -This template means that each package in the spec.targets.repositories..packageNames list will have the suffix --cumulus added to its name. This allows us to automatically generate unique package names. Applying the -*PackageVariantSet* also automatically sets a unique namespace for each network function because applying the -*PackageVariantSet* automatically triggers the Kpt pipeline in the *network-function-auto-namespace* *Kpt* package to -generate unique namespaces for each deployed package. - -{{% alert title="Note" color="primary" %}} - -Many other mutations can be performed using a *PackageVariantSet*. Use `kubectl explain PackageVariantSet` to get help on -the structure of the *PackageVariantSet* CRD to see the various mutations that are possible. - -{{% /alert %}} - -Applying the *PackageVariantSet* creates the new packages as draft packages: - -```bash -kubectl apply -f name-namespace-variant.yaml -packagevariantset.config.porch.kpt.dev/network-function-auto-namespace created - -kunectl get -n porch-demo PackageVariantSet network-function-auto-namespace -NAME AGE -network-function-auto-namespace 38s - -kubectl get PackageRevisions -n porch-demo | grep auto-namespace -edge1-1f521f05a684adfa8562bf330f7bc72b50e21cc5 edge1-network-function-auto-namespace-a v1 main false Published edge1 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 -edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 -management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management -``` - -{{% alert title="Note" color="primary" %}} - -The suffix `x-cumulonimbus` and `y-cumulonimbus` has been placed on the package names. - -{{% /alert %}} - -Examine the *edge1* repository on Gitea and you should see two new draft branches. - -- drafts/network-function-auto-namespace-x-cumulonimbus/packagevariant-1 -- drafts/network-function-auto-namespace-y-cumulonimbus/packagevariant-1 - -In these packages, you will see that: - -1. The package name has been generated as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus in all files in the packages -2. The namespace has been generated as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus respectively in the *demployment.yaml* files -3. The PackageVariant has set the data.name field as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus respectively in the *pckage-context.yaml* files - -This has all been performed automatically; we have not had to perform the -`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these changes as we had to in the -*simple-variant.yaml* case above. - -Now, let us explore the packages further: - -```bash -porchctl -n porch-demo rpkg get --name network-function-auto-namespace-x-cumulonimbus -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 - -porchctl -n porch-demo rpkg get --name network-function-auto-namespace-y-cumulonimbus -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 -``` - -We can see that our two new packages are created as draft packages on the edge1 repository. We can also examine the -*PacakgeVariant* CRs that have been created: - -```bash -kubectl get PackageVariant -n porch-demo -NAME AGE -network-function-auto-namespace-edge1-network-function-35079f9f 3m41s -network-function-auto-namespace-edge1-network-function-d521d2c0 3m41s -network-function-edge1-network-function-b 38m -network-function-edge1-network-function-c 38m -``` - -It is also interesting to examine the YAML of a *PackageVariant*: - -```yaml -kubectl get PackageVariant -n porch-demo network-function-auto-namespace-edge1-network-function-35079f9f -o yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: PackageVariant -metadata: - creationTimestamp: "2024-01-24T15:10:19Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e - name: network-function-auto-namespace-edge1-network-function-35079f9f - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function-auto-namespace - uid: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e - resourceVersion: "404083" - uid: 5ae69c2d-6aac-4942-b717-918325650190 -spec: - downstream: - package: network-function-auto-namespace-x-cumulonimbus - repo: edge1 - upstream: - package: network-function-auto-namespace - repo: management - revision: v1 -status: - conditions: - - lastTransitionTime: "2024-01-24T15:10:19Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-24T15:10:49Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-009659a8532552b86263434f68618554e12f4f7c -``` -Our two packages are ready for deployment: - -```bash -porchctl rpkg propose edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo -edge1-009659a8532552b86263434f68618554e12f4f7c proposed - -porchctl rpkg approve edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo -edge1-009659a8532552b86263434f68618554e12f4f7c approved - -porchctl rpkg propose edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e proposed - -porchctl rpkg approve edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e approved -``` - -We can now check that the packages are deployed on the edge1 cluster and that the pods are running - -```bash -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 0/1 ContainerCreating 0 1s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 10s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 50s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 51s -network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 0/1 ContainerCreating 0 1s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 54s -network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 1/1 Running 0 4s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m -``` + \ No newline at end of file From b7e2f3b80d9c3189feefaebd3b161eed2bf687b7 Mon Sep 17 00:00:00 2001 From: Dominika Schweier Date: Thu, 31 Jul 2025 11:28:39 +0200 Subject: [PATCH 2/4] Creating the Use Cases page Signed-off-by: Dominika Schweier --- .../en/docs/porch/basic-usage/tutorials.md | 810 ------------------ .../en/docs/porch/basic-usage/use-cases.md | 717 ++++++++++++++++ .../user-guides/preparing-the-environment.md | 54 ++ 3 files changed, 771 insertions(+), 810 deletions(-) delete mode 100644 content/en/docs/porch/basic-usage/tutorials.md create mode 100644 content/en/docs/porch/basic-usage/use-cases.md diff --git a/content/en/docs/porch/basic-usage/tutorials.md b/content/en/docs/porch/basic-usage/tutorials.md deleted file mode 100644 index e1c1385f..00000000 --- a/content/en/docs/porch/basic-usage/tutorials.md +++ /dev/null @@ -1,810 +0,0 @@ ---- -title: "Tutorials" -type: docs -weight: 1 -description: ---- - -## 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 - -Create a new package in our *management* repository using the sample *network-function* package provided. This network -function Kpt package is a demo Kpt package that installs [Nginx](https://github.com/nginx). - -``` -porchctl -n porch-demo rpkg init network-function --repository=management --workspace=v1 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 created -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Draft management -``` - -This command creates a new *PackageRevision* CR in porch and also creates a branch called *network-function/v1* in our -Gitea *management* repository. Use the Gitea web UI to confirm that the branch has been created and note that it only has -default content as yet. - -We now pull the package we have initialized from Porch. - -``` -porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function -``` - -We update the initialized package and add our local changes. -``` -cp blueprints/local-changes/network-function/* blueprints/initialized/network-function -``` - -Now, we push the package contents to porch: -``` -porchctl -n porch-demo rpkg push management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 blueprints/initialized/network-function -``` - -Check on the Gitea web UI and we can see that the actual package contents have been pushed. - -Now we propose and approve the package. - -``` -porchctl -n porch-demo rpkg propose management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 proposed - -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Proposed management - -porchctl -n porch-demo rpkg approve management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 approved - -porchctl -n porch-demo rpkg get --name network-function -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management - -``` - -Once we approve the package, the package is merged into the main branch in the *management* repository and the branch called -*network-function/v1* in that repository is removed. Use the Gitea UI to verify this. We now have our blueprint package in our -*management* repository and we can deploy this package into workload clusters. - -### Blueprint with a Kpt pipeline - -The second blueprint in the *blueprint* directory is called *network-function-auto-namespace*. This network -function is exactly the same as the *network-function* package except that it has a Kpt function that automatically -creates a namespace with the namespace configured in the name field in the *package-context.yaml* file. Note that no -namespace is defined in the metadata of the *deployment.yaml* file of this Kpt package. - -We use the same sequence of commands again to publish our blueprint package for *network-function-auto-namespace*. - -``` -porchctl -n porch-demo rpkg init network-function-auto-namespace --repository=management --workspace=v1 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 created - -porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace - -cp blueprints/local-changes/network-function-auto-namespace/* blueprints/initialized/network-function-auto-namespace - -porchctl -n porch-demo rpkg push management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace -``` - -Examine the *drafts/network-function-auto-namespace/v1* branch in Gitea. Notice that the set-namespace Kpt function in -the pipeline in the *Kptfile* has set the namespace in the *deployment.yaml* file to the value default-namespace-name, -which it read from the *package-context.yaml* file. - -Now we propose and approve the package. - -``` -porchctl -n porch-demo rpkg propose management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 proposed - -porchctl -n porch-demo rpkg approve management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 approved - -porchctl -n porch-demo rpkg get --name network-function-auto-namespace -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management - -``` - -## Deploying a blueprint onto a workload cluster - -### Blueprint with no Kpt pipelines - -The process of deploying a blueprint package from our *management* repository clones the package, then modifies it for use on -the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the *edge1* repository. -Remember that the *edge1* repository is being monitored by configsync from the edge1 cluster, so once the package appears in -the *edge1* repository on the management cluster, it will be pulled by configsync and applied to the edge1 cluster. - -``` -porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -find tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/deployment.yaml -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/README.md -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/Kptfile -tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/package-context.yaml -``` -The package we created in the last section is cloned. We now remove the original metadata from the package. -``` -rm tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata -``` - -We use a *kpt* function to change the namespace that will be used for the deployment of the network function. - -``` -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -- namespace=edge1-network-function-a - -[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" -[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" in 300ms - Results: - [info]: namespace "" updated to "edge1-network-function-a", 1 value(s) changed -``` - -We now initialize and push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg init edge1-network-function-a --repository=edge1 --workspace=v1 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 created - -porchctl -n porch-demo rpkg pull edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a - -cp tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-a -rm -fr tmp_packages_for_deployment/edge1-network-function-a.clone.tmp - -porchctl -n porch-demo rpkg push edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 tmp_packages_for_deployment/edge1-network-function-a - -porchctl -n porch-demo rpkg get --name edge1-network-function-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 false Draft edge1 -``` - -You can verify that the package is in the *network-function-a/v1* branch of the deployment repository using the Gitea web UI. - - -Check that the *edge1-network-function-a* package is not deployed on the edge1 cluster yet: -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-a -No resources found in network-function-a namespace. - -``` - -We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers -configsync to apply the package to the edge1 cluster. - -``` -export KUBECONFIG=~/.kube/kind-management-config - -porchctl -n porch-demo rpkg propose edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 proposed - -porchctl -n porch-demo rpkg approve edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 approved - -porchctl -n porch-demo rpkg get --name edge1-network-function-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 v1 true Published edge1 -``` - -We can now check that the *network-function-a* package is deployed on the edge1 cluster and that the pod is running -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-a -No resources found in network-function-a namespace. - -kubectl get pod -n edge1-network-function-a -NAME READY STATUS RESTARTS AGE -network-function-9779fc9f5-4rqp2 1/1 ContainerCreating 0 9s - -kubectl get pod -n edge1-network-function-a -NAME READY STATUS RESTARTS AGE -network-function-9779fc9f5-4rqp2 1/1 Running 0 44s -``` - -### Blueprint with a Kpt pipeline - -The process for deploying a blueprint with a *Kpt* pipeline runs the Kpt pipeline automatically with whatever configuration we give it. Rather than explicitly running a *Kpt* function to change the namespace, we will specify the namespace as configuration and the pipeline will apply it to the deployment. - -``` -porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp - -find tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp - -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/deployment.yaml -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/README.md -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/Kptfile -tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/package-context.yaml -``` - -We now remove the original metadata from the package. -``` -rm tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata -``` - -The package we created in the last section is cloned. We now initialize and push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg init edge1-network-function-auto-namespace-a --repository=edge1 --workspace=v1 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 created - -porchctl -n porch-demo rpkg pull edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a - -cp tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/* tmp_packages_for_deployment/edge1-network-function-auto-namespace-a -rm -fr tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp -``` - - -We now simply configure the namespace we want to apply. edit the *tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml* file and set the namespace to use: - -``` -8c8 -< name: default-namespace-name ---- -> name: edge1-network-function-auto-namespace-a -``` - -We now push the package to the *edge1* repository: - -``` -porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a -[RUNNING] "gcr.io/kpt-fn/set-namespace:v0.4.1" -[PASS] "gcr.io/kpt-fn/set-namespace:v0.4.1" - Results: - [info]: namespace "default-namespace-name" updated to "edge1-network-function-auto-namespace-a", 1 value(s) changed - -porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a -``` - -You can verify that the package is in the *network-function-auto-namespace-a/v1* branch of the deployment repository using the -Gitea web UI. You can see that the kpt pipeline fired and set the edge1-network-function-auto-namespace-a namespace in -the *deployment.yaml* file on the *drafts/edge1-network-function-auto-namespace-a/v1* branch on the *edge1* repository in -Gitea. - -Check that the *edge1-network-function-auto-namespace-a* package is not deployed on the edge1 cluster yet: -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-auto-namespace-a -No resources found in network-function-auto-namespace-a namespace. - -``` - -We now propose and approve the deployment package, which merges the package to the *edge1* repository and further triggers -configsync to apply the package to the edge1 cluster. - -``` -export KUBECONFIG=~/.kube/kind-management-config - -porchctl -n porch-demo rpkg propose edge1-48997da49ca0a733b0834c1a27943f1a0e075180 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 proposed - -porchctl -n porch-demo rpkg approve edge1-48997da49ca0a733b0834c1a27943f1a0e075180 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 approved - -porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 -``` - -We can now check that the *network-function-auto-namespace-a* package is deployed on the edge1 cluster and that the pod is running -``` -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -n edge1-network-function-auto-namespace-a -No resources found in network-function-auto-namespace-a namespace. - -kubectl get pod -n edge1-network-function-auto-namespace-a -NAME READY STATUS RESTARTS AGE -network-function-auto-namespace-85bc658d67-rbzt6 1/1 ContainerCreating 0 3s - -kubectl get pod -n edge1-network-function-auto-namespace-a -NAME READY STATUS RESTARTS AGE -network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 0 10s -``` - -## Deploying using Package Variant Sets - -### Simple PackageVariantSet - -The PackageVariant CR is defined as: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha2 -kind: PackageVariantSet - -metadata: - name: network-function - namespace: porch-demo - -spec: - upstream: - repo: management - package: network-function - revision: v1 - targets: - - repositories: - - name: edge1 - packageNames: - - network-function-b - - network-function-c -``` - -In this very simple PackageVariant, the *network-function* package in the *management* repository is cloned into the *edge1* -repository as the *network-function-b* and *network-function-c* package variants. - -{{% alert title="Note" color="primary" %}} - -This simple package variant does not specify any configuration changes. Normally, as well as cloning and renaming, -configuration changes would be applied on a package variant. - -Use `kubectl explain PackageVariantSet` to get help on the structure of the PackageVariantSet CRD. - -{{% /alert %}} - -Applying the PackageVariantSet creates the new packages as draft packages: - -```bash -kubectl apply -f simple-variant.yaml - -kubectl get PackageRevisions -n porch-demo | grep -v 'external-blueprints' -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-bc8294d121360ad305c9a826a8734adcf5f1b9c0 network-function-a v1 main false Published edge1 -edge1-9b4b4d99c43b5c5c8489a47bbce9a61f79904946 network-function-a v1 v1 true Published edge1 -edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 -management-49580fc22bcf3bf51d334a00b6baa41df597219e network-function v1 main false Published management -management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 v1 true Published management - -porchctl -n porch-demo rpkg get --name network-function-b -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-a31b56c7db509652f00724dd49746660757cd98a network-function-b packagevariant-1 false Draft edge1 - -porchctl -n porch-demo rpkg get --name network-function-c -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 -``` - -We can see that our two new packages are created as draft packages on the *edge1* repository. We can also examine the -*PacakgeVariant* CRs that have been created: - -```bash -kubectl get PackageVariant -n porch-demo -NAMESPACE NAME READY STATUS RESTARTS AGE -network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h -network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s -network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s -``` - - -It is also interesting to examine the YAML of the *PackageVariant*: - -```yaml -kubectl get PackageVariant -n porch-demo -o yaml -apiVersion: v1 -items: -- apiVersion: config.porch.kpt.dev/v1alpha1 - kind: PackageVariant - metadata: - creationTimestamp: "2024-01-09T15:00:00Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - name: network-function-edge1-network-function-b - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function - uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - resourceVersion: "237053" - uid: 7a81099c-5a0b-49d8-b73c-48e33cd134e5 - spec: - downstream: - package: network-function-b - repo: edge1 - upstream: - package: network-function - repo: management - revision: v1 - status: - conditions: - - lastTransitionTime: "2024-01-09T15:00:00Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-09T15:00:31Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-a31b56c7db509652f00724dd49746660757cd98a -- apiVersion: config.porch.kpt.dev/v1alpha1 - kind: PackageVariant - metadata: - creationTimestamp: "2024-01-09T15:00:00Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - name: network-function-edge1-network-function-c - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function - uid: a923d4fc-a3a7-437c-84d1-52b30dd6cf49 - resourceVersion: "237056" - uid: da037d0a-9a7a-4e85-842c-1324e9da819a - spec: - downstream: - package: network-function-c - repo: edge1 - upstream: - package: network-function - repo: management - revision: v1 - status: - conditions: - - lastTransitionTime: "2024-01-09T15:00:01Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-09T15:00:31Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 -kind: List -metadata: - resourceVersion: "" -``` - -We now want to customize and deploy our two packages. To do this we must pull the packages locally, render the *kpt* -functions, and then push the rendered packages back up to the *edge1* repository. - -```bash -porchctl rpkg pull edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-b -- namespace=network-function-b -porchctl rpkg push edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo - -porchctl rpkg pull edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo -kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-c -- namespace=network-function-c -porchctl rpkg push edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo -``` - -Check that the namespace has been updated on the two packages in the *edge1* repository using the Gitea web UI. - -Now our two packages are ready for deployment: - -```bash -porchctl rpkg propose edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo -edge1-a31b56c7db509652f00724dd49746660757cd98a proposed - -porchctl rpkg approve edge1-a31b56c7db509652f00724dd49746660757cd98a --namespace=porch-demo -edge1-a31b56c7db509652f00724dd49746660757cd98a approved - -porchctl rpkg propose edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 proposed - -porchctl rpkg approve edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace=porch-demo -edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 approved -``` - -We can now check that the *network-function-b* and *network-function-c* packages are deployed on the edge1 cluster and -that the pods are running - -```bash -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -network-function-a network-function-9779fc9f5-2tswc 1/1 Running 0 19h -network-function-b network-function-9779fc9f5-6zwhh 1/1 Running 0 76s -network-function-c network-function-9779fc9f5-h7nsb 1/1 Running 0 41s -``` - -### Using a PackageVariantSet to automatically set the package name and package namespace - -The *PackageVariant* CR defined as: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha2 -kind: PackageVariantSet -metadata: - name: network-function-auto-namespace - namespace: porch-demo -spec: - upstream: - repo: management - package: network-function-auto-namespace - revision: v1 - targets: - - repositories: - - name: edge1 - packageNames: - - network-function-auto-namespace-x - - network-function-auto-namespace-y - template: - downstream: - packageExpr: "target.package + '-cumulonimbus'" -``` - - -In this *PackageVariant*, the *network-function-auto-namespace* package in the *management* repository is cloned into the -*edge1* repository as the *network-function-auto-namespace-x* and *network-function-auto-namespace-y* package variants, -similar to the *PackageVariant* in *simple-variant.yaml*. - -An extra template section provided for the repositories in the PackageVariant: - -```yaml -template: - downstream: - packageExpr: "target.package + '-cumulus'" -``` - -This template means that each package in the spec.targets.repositories..packageNames list will have the suffix --cumulus added to its name. This allows us to automatically generate unique package names. Applying the -*PackageVariantSet* also automatically sets a unique namespace for each network function because applying the -*PackageVariantSet* automatically triggers the Kpt pipeline in the *network-function-auto-namespace* *Kpt* package to -generate unique namespaces for each deployed package. - -{{% alert title="Note" color="primary" %}} - -Many other mutations can be performed using a *PackageVariantSet*. Use `kubectl explain PackageVariantSet` to get help on -the structure of the *PackageVariantSet* CRD to see the various mutations that are possible. - -{{% /alert %}} - -Applying the *PackageVariantSet* creates the new packages as draft packages: - -```bash -kubectl apply -f name-namespace-variant.yaml -packagevariantset.config.porch.kpt.dev/network-function-auto-namespace created - -kunectl get -n porch-demo PackageVariantSet network-function-auto-namespace -NAME AGE -network-function-auto-namespace 38s - -kubectl get PackageRevisions -n porch-demo | grep auto-namespace -edge1-1f521f05a684adfa8562bf330f7bc72b50e21cc5 edge1-network-function-auto-namespace-a v1 main false Published edge1 -edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 -edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 -management-f9a6f2802111b9e81c296422c03aae279725f6df network-function-auto-namespace v1 main false Published management -management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-namespace v1 v1 true Published management -``` - -{{% alert title="Note" color="primary" %}} - -The suffix `x-cumulonimbus` and `y-cumulonimbus` has been placed on the package names. - -{{% /alert %}} - -Examine the *edge1* repository on Gitea and you should see two new draft branches. - -- drafts/network-function-auto-namespace-x-cumulonimbus/packagevariant-1 -- drafts/network-function-auto-namespace-y-cumulonimbus/packagevariant-1 - -In these packages, you will see that: - -1. The package name has been generated as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus in all files in the packages -2. The namespace has been generated as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus respectively in the *demployment.yaml* files -3. The PackageVariant has set the data.name field as network-function-auto-namespace-x-cumulonimbus and - network-function-auto-namespace-y-cumulonimbus respectively in the *pckage-context.yaml* files - -This has all been performed automatically; we have not had to perform the -`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these changes as we had to in the -*simple-variant.yaml* case above. - -Now, let us explore the packages further: - -```bash -porchctl -n porch-demo rpkg get --name network-function-auto-namespace-x-cumulonimbus -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-009659a8532552b86263434f68618554e12f4f7c network-function-auto-namespace-x-cumulonimbus packagevariant-1 false Draft edge1 - -porchctl -n porch-demo rpkg get --name network-function-auto-namespace-y-cumulonimbus -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace-y-cumulonimbus packagevariant-1 false Draft edge1 -``` - -We can see that our two new packages are created as draft packages on the edge1 repository. We can also examine the -*PacakgeVariant* CRs that have been created: - -```bash -kubectl get PackageVariant -n porch-demo -NAME AGE -network-function-auto-namespace-edge1-network-function-35079f9f 3m41s -network-function-auto-namespace-edge1-network-function-d521d2c0 3m41s -network-function-edge1-network-function-b 38m -network-function-edge1-network-function-c 38m -``` - -It is also interesting to examine the YAML of a *PackageVariant*: - -```yaml -kubectl get PackageVariant -n porch-demo network-function-auto-namespace-edge1-network-function-35079f9f -o yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: PackageVariant -metadata: - creationTimestamp: "2024-01-24T15:10:19Z" - finalizers: - - config.porch.kpt.dev/packagevariants - generation: 1 - labels: - config.porch.kpt.dev/packagevariantset: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e - name: network-function-auto-namespace-edge1-network-function-35079f9f - namespace: porch-demo - ownerReferences: - - apiVersion: config.porch.kpt.dev/v1alpha2 - controller: true - kind: PackageVariantSet - name: network-function-auto-namespace - uid: 71edbdff-21c1-45f4-b9cb-6d2ecfc3da4e - resourceVersion: "404083" - uid: 5ae69c2d-6aac-4942-b717-918325650190 -spec: - downstream: - package: network-function-auto-namespace-x-cumulonimbus - repo: edge1 - upstream: - package: network-function-auto-namespace - repo: management - revision: v1 -status: - conditions: - - lastTransitionTime: "2024-01-24T15:10:19Z" - message: all validation checks passed - reason: Valid - status: "False" - type: Stalled - - lastTransitionTime: "2024-01-24T15:10:49Z" - message: successfully ensured downstream package variant - reason: NoErrors - status: "True" - type: Ready - downstreamTargets: - - name: edge1-009659a8532552b86263434f68618554e12f4f7c -``` -Our two packages are ready for deployment: - -```bash -porchctl rpkg propose edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo -edge1-009659a8532552b86263434f68618554e12f4f7c proposed - -porchctl rpkg approve edge1-009659a8532552b86263434f68618554e12f4f7c --namespace=porch-demo -edge1-009659a8532552b86263434f68618554e12f4f7c approved - -porchctl rpkg propose edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e proposed - -porchctl rpkg approve edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e --namespace=porch-demo -edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e approved -``` - -We can now check that the packages are deployed on the edge1 cluster and that the pods are running - -```bash -export KUBECONFIG=~/.kube/kind-edge1-config - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 0/1 ContainerCreating 0 1s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 44m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 10s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 45m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 50s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 51s -network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 0/1 ContainerCreating 0 1s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m - -kubectl get pod -A | egrep '(NAMESPACE|network-function)' -NAMESPACE NAME READY STATUS RESTARTS AGE -edge1-network-function-a network-function-9779fc9f5-87scj 1/1 Running 1 (2d1h ago) 4d22h -edge1-network-function-auto-namespace-a network-function-auto-namespace-85bc658d67-rbzt6 1/1 Running 1 (2d1h ago) 4d22h -network-function-auto-namespace-x-cumulonimbus network-function-auto-namespace-85bc658d67-86gml 1/1 Running 0 54s -network-function-auto-namespace-y-cumulonimbus network-function-auto-namespace-85bc658d67-tp5m8 1/1 Running 0 4s -network-function-b network-function-9779fc9f5-twh2g 1/1 Running 0 46m -network-function-c network-function-9779fc9f5-whhr8 1/1 Running 0 45m -``` diff --git a/content/en/docs/porch/basic-usage/use-cases.md b/content/en/docs/porch/basic-usage/use-cases.md new file mode 100644 index 00000000..6237df27 --- /dev/null +++ b/content/en/docs/porch/basic-usage/use-cases.md @@ -0,0 +1,717 @@ +--- +title: "Use Cases" +type: docs +weight: 4 +description: +--- + +## Quickstart + +​​In this quickstart you will use Porch to discover configuration packages +in a [sample repository](https://github.com/kptdev/kpt-samples). + +You will use the kpt CLI - the new `kpt alpha` command sub-groups to interact +with the Package Orchestration service. + +### Register the repository + +Start by registering the sample repository with Porch. The repository already +contains a [`basens`](https://github.com/kptdev/kpt-samples/tree/main/basens) package. + +```sh +# Register a sample Git repository: +$ kpt alpha repo register --namespace default \ + https://github.com/kptdev/kpt-samples.git +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [register command reference](https://kpt.dev/reference/cli/alpha/repo/reg/) for usage. +{{% /alert %}} + +The sample repository is public and Porch therefore doesn't require +authentication to read the repository and discover packages within it. + +You can confirm the repository is now registered with Porch by using the +`kpt alpha repo get` command. Similar to `kubectl get`, the command will list +all repositories registered with Porch, or get information about specific ones +if list of names is provided + +```sh +# Query repositories registered with Porch: +$ kpt alpha repo get +NAME TYPE CONTENT DEPLOYMENT READY ADDRESS +kpt-samples git Package True https://github.com/kptdev/kpt-samples.git +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. +{{% /alert %}} + +From the output you can see that: + +* the repository was registered by the name `kpt-samples`. This was chosen + by kpt automatically from the repository URL, but can be overridden +* it is a `git` repository (OCI repositories are also supported, though + currently with some limitations) +* the repository is *not* a deployment repository. Repository can be marked + as deployment repository which indicates that packages in the repository are + intended to be deployed into live state. +* the repository is ready - Porch successfully registered it and discovered + packages stored in the repository. + +The Package Orchestration service is designed to be part of the Kubernetes +ecosystem. The [resources](porchctl-cli-guide.md) managed by Porch are KRM +resources. + +You can use the `-oyaml` to see the YAML representation of the repository +registration resource: + +{{% alert title="Note" color="primary" %}} + kpt uses the same output format flags as `kubectl`. Flags with which you are +already familiar from using `kubectl get` will work with the kpt commands +that get or list Porch resources. +{{% /alert %}} + +```sh +# View the Repository registration resource as YAML: +$ kpt alpha repo get kpt-samples --namespace default -oyaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: Repository +metadata: + name: kpt-samples + namespace: default +spec: + content: Package + git: + branch: main + directory: / + repo: https://github.com/kptdev/kpt-samples.git + secretRef: + name: "" + type: git +status: + conditions: + - reason: Ready + status: "True" + type: Ready +``` + +Few additional details are available in the YAML listing: + +The name of the `main` branch and a directory. These specify location within +the repository where Porch will be managing packages. Porch also analyzes tags +in the repository to identify all packages (and their specific versions), all +within the directory specified. By default Porch will analyze the whole +repository. + +The `secretRef` can contain a name of a Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) +resource with authentication credentials for Porch to access the repository. + +#### kubectl + +Thanks to the integration with Kubernetes ecosystem, you can also use `kubectl` +directly to interact with Porch, such as listing repository resources: + +```sh +# List registered repositories using kubectl +$ kubectl get repository +NAME TYPE CONTENT DEPLOYMENT READY ADDRESS +kpt-samples git Package True https://github.com/kptdev/kpt-samples.git +``` + +You can use kubectl for _all_ interactions with Porch server if you prefer. +The kpt CLI integration provides a variety of convenience features. + +### Discover packages + +You can use the `kpt alpha rpkg get` command to list the packages discovered +by Porch across all registered repositories. + +```sh +# List package revisions in registered repositories +$ kpt alpha rpkg get +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +kpt-samples-da07e9611f9b99028f761c07a79e3c746d6fc43b basens main false Published kpt-samples +kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 basens v0 true Published kpt-samples +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. +{{% /alert %}} + +{{% alert title="Note" color="primary" %}} + The `r` prefix of the `rpkg` command group stands for `remote`. The commands +in the `kpt alpha rpkg` group interact with packages managed (remotely) by Porch +server. The commands in the `rpkg` group are similar to the `kpt pkg` commands +except that they operate on remote packages managed by Porch server rather than +on a local disk. +{{% /alert %}} + +The output shows that Porch discovered the `basens` package, and found two +different revisions of it. The `v0` revision (associated with the +[`basens/v0`](https://github.com/kptdev/kpt-samples/tree/basens/v0) tag) and the `main` revision associated with the +[`main` branch](https://github.com/kptdev/kpt-samples/tree/main) in the repository. + +The `LIFECYCLE` column indicates the lifecycle stage of the package revision. +The package revisions in the repository are *`Published`* - ready to be used. +Package revision may be also *`Draft`* (the package revision is being authored) +or *`Proposed`* (the author of the package revision proposed that it be +published). We will encounter examples of these + +Porch identifies the latest revision of the package (`LATEST` column). + +#### View package resources + +The `kpt alpha rpkg get` command displays package metadata. To view the +_contents_ of the package revision, use the `kpt alpha rpkg pull` command. + +You can use the command to output the resources as a +[`ResourceList`][resourcelist] on standard output, or save them into a local +directory: + +```sh +# View contents of the basens/v0 package revision +$ kpt alpha rpkg pull kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 -ndefault + +apiVersion: config.kubernetes.io/v1 +kind: ResourceList +items: +- apiVersion: kpt.dev/v1 + kind: Kptfile + metadata: + name: basens + annotations: +... +``` + +Add a name of a local directory on the command line to save the package onto +local disk for inspection or editing. + +```sh +# Pull package revision resources, save to local disk into `./basens` directory +$ kpt alpha rpkg pull kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 ./basens -ndefault + +# Explore the package contents +$ find basens + +basens +basens/README.md +basens/namespace.yaml +basens/Kptfile +... +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [pull command reference](https://kpt.dev/reference/cli/alpha/rpkg/pull/) for usage. +{{% /alert %}} + +### Unregister the repository + +When you are done using the repository with Porch, you can unregister it: + +```sh +# Unregister the repository +$ kpt alpha repo unregister kpt-samples -ndefault +``` + +### More resources + +To continue learning about Porch, you can review: + +* [Using the Porch CLI tool](porchctl-cli-guide.md) +* [Provisioning Namespaces with the UI](https://kpt.dev/guides/namespace-provisioning-ui/) +* [Package Orchestration](../package-orchestration.md) + +## Registering a Repository + +In the following sections of this chapter you will explore package authoring +using Porch. You will need: + +* A GitHub repository for your blueprints. An otherwise empty repository with an + initial commit works best. The initial commit is required to establish the + `main` branch. +* A GitHub [Personal Access Token](https://github.com/settings/tokens) with + the `repo` scope for Porch to authenticate with the repository and allow it + to create commits in the repository. + +A repository is a porch representation of either a git repo or an oci registry. +Package revisions always belong to a single repository. A repository exists in +a Kubernetes namespace and all package revisions in a repo also belong to +the same namespace. + +Use the `kpt alpha repo register` command to register your repository with +Porch: The command below uses the repository `deployments.git`. +Your repository name may be different; please update the command with the +correct repository name. + +```sh +# Register your Git repository: + +GITHUB_USERNAME= + +GITHUB_TOKEN= + +REPOSITORY_ADDRESS= + + +$ kpt alpha repo register \ + --namespace default \ + --name deployments \ + --deployment \ + --repo-basic-username=${GITHUB_USERNAME} \ + --repo-basic-password=${GITHUB_TOKEN} \ + ${REPOSITORY_ADDRESS} +``` + +And register the sample repository we used in the [quickstart](#quickstart): + +```sh +# Register the sample repository: + +kpt alpha repo register --namespace default \ + https://github.com/kptdev/kpt-samples.git +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [register command reference](https://kpt.dev/reference/cli/alpha/repo/reg/) for usage. +{{% /alert %}} + +You now have two repositories registered, and your repository is marked as +deployment repository. This indicates that published packages in the repository +are considered deployment-ready. + +```sh +# Query repositories registered with Porch: +$ kpt alpha repo get +NAME TYPE CONTENT DEPLOYMENT READY ADDRESS +deployments git Package true True [Your repository address] +kpt-samples git Package True https://github.com/kptdev/kpt-samples.git +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. +{{% /alert %}} + +## Package Authoring + +There are several ways to author a package revision, including creating +a completely new one, cloning an existing package, or creating a new revision +of an existing package. In this section we will explore the different ways to +author package revisions, and explore how to modify package contents. + +### Create a new package revision + +Create a new package revision in a repository managed by Porch: + +```sh +# Initialize a new (empty) package revision: +$ kpt alpha rpkg init new-package --repository=deployments --revision=v1 -ndefault + +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 created + +# List the available package revisions. +$ kpt alpha rpkg get + +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments +kpt-samples-da07e9611f9b99028f761c07a79e3c746d6fc43b basens main false Published kpt-samples +kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 basens v0 true Published kpt-samples +... +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [init command reference](https://kpt.dev/reference/cli/alpha/rpkg/init/) for usage. +{{% /alert %}} + +You can see the `new-package` is created in the `Draft` lifecycle stage. This +means that the package is being authored. + +{{% alert title="Note" color="primary" %}} + You may notice that the name of the package revision + `deployments-c32b851b591b860efda29ba0e006725c8c1f7764` was assigned + automatically. Packages in a git repository may be located in subdirectories + and to make sure Porch works well with the rest of the Kubernetes ecosystem, + the resource names must meet Kubernetes requirements. The resource names + assigned by Porch are stable, and computed as hash of the repository name, + directory path within the repository, and revision. +{{% /alert %}} + +The contents of the new package revision are the same as if it was created using +the [`kpt pkg init`](https://kpt.dev/book/03-packages/06-creating-a-package) command, except it +was created by the Package Orchestration service in your repository. + +In fact, if you check your Git repository, you will see a new branch called +`drafts/new-package/v1` which Porch created for the draft authoring. You will +also see one or more commits made into the branch by Porch on your behalf. + +### Clone an existing package + +Another way to create a new package revision is by cloning an already existing +package. The existing package is referred to as *upstream* and the newly created +package is *downstream*. + +Use `kpt alpha rpkg clone` command to create a new *downstream* package +`istions` by cloning the sample `basens/v0` package revision: + +```sh +# Clone an upstream package to create a downstream package +$ kpt alpha rpkg clone \ + kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 \ + istions \ + --repository=deployments -ndefault + +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b created + +# Confirm the package revision was created +kpt alpha rpkg get deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Draft deployments +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [clone command reference](https://kpt.dev/reference/cli/alpha/rpkg/clone/) for usage. +{{% /alert %}} + +Cloning a package using the Package Orchestration service is an action similar to +[`kpt pkg get`](https://kpt.dev/book/03-packages/01-getting-a-package) command. Porch will +create the appropriate upstream package links in the new package's `Kptfile`. +Let's take a look: + +```sh +# Examine the new package's upstream link (the output has been abbreviated): +$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault + +kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault +apiVersion: config.kubernetes.io/v1 +kind: ResourceList +items: +- apiVersion: kpt.dev/v1 + kind: Kptfile + metadata: + name: istions + upstream: + type: git + git: + repo: https://github.com/kptdev/kpt-samples.git + directory: basens + ref: basens/v0 + upstreamLock: + type: git + git: + repo: https://github.com/kptdev/kpt-samples.git + directory: basens + ref: basens/v0 + commit: 026dfe8e3ef8d99993bc8f7c0c6ba639faa9a634 + info: + description: kpt package for provisioning namespace +... +``` + +You can find out more about the `upstream` and `upstreamLock` sections of the +`Kptfile` in an [earlier chapter](https://kpt.dev/book/03-packages/01-getting-a-package) +of the book. + +{{% 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 %}} + +You can also clone a package from a repository that is _not_ registered with +Porch, for example: + +```sh +# Clone a package from Git repository directly (repository is not registered) +$ kpt alpha rpkg clone \ + https://github.com/GoogleCloudPlatform/blueprints.git/catalog/bucket@main my-bucket \ + --repository=deployments \ + --namespace=default + +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 created + +# Confirm the package revision was created +$ kpt alpha rpkg get deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 -ndefault +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments +``` + +### Create a new revision of an existing package + +Finally, with Porch you can create a new revision of an existing, +**`Published`** package. All the package revisions in your repository are +**`Draft`** revisions and need to be published first. We will cover the package +approval flow in more detail in the next section. For now we will quickly +propose and approve one of our draft package revisions and create a new revision +from it. + +```sh +# Propose the package draft to be published +$ kpt alpha rpkg propose deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 proposed + +# Approve the proposed package revision for publishing +$ kpt alpha rpkg approve deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 approved +``` + +You now have a **`Published`** package revision in the repository managed by Porch +and next you will create a new revision of it. A **`Published`** package is ready +to be used, such as deployed or copied. + +```sh +# Confirm the package is published: +$ kpt alpha rpkg get deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 true Published deployments +``` + +Copy the existing, **`Published`** package revision to create a **`Draft`** of +a new package revision that you can further customize: + +```sh +# Copy the published package: +$ kpt alpha rpkg copy deployments-c32b851b591b860efda29ba0e006725c8c1f7764 \ + -ndefault --revision v2 +deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a created + +# List all revisions of the new-package that we just copied: +$ kpt alpha rpkg get --name new-package +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-af86ae3c767b0602a198856af513733e4e37bf10 new-package main false Published deployments +deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 true Published deployments +deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [copy command reference](https://kpt.dev/reference/cli/alpha/rpkg/copy/) for usage. +{{% /alert %}} + +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 `new-package/v1` and `new-package/v2` have identical contents, +including upstream information, and differ in revision only. + +### Editing package revision resources + +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. + +```sh +# Pull the package contents of istions/v1 onto the local disk: +$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./istions -ndefault +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [pull command reference][rpkg-pull] for usage. +{{% /alert %}} + +The command downloaded the `istions/v1` package revision contents and saved +them in the `./istions` directory. Now you will make some changes. + +First, note that even though Porch updated the namespace name (in +`namespace.yaml`) to `istions` 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: + +``` +# istions + +## Description +kpt package for provisioning Istio 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 +$ kpt alpha rpkg push deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./istions -ndefault +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [push command reference](https://kpt.dev/reference/cli/alpha/rpkg/push/) for usage. +{{% /alert %}} + +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: +$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./updated-istions -ndefault + +# Inspect updated-istions/namespace.yaml +$ cat updated-istions/namespace.yaml + +apiVersion: v1 +kind: Namespace +metadata: + name: istions + 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`). + +### Summary of package authoring + +In this section we reviewed how to use Porch to author packages, including + +* creating a new package ([`kpt alpha rpkg init`](https://kpt.dev/reference/cli/alpha/rpkg/init/)) +* cloning an existing package ([`kpt alpha rpkg clone`](https://kpt.dev/reference/cli/alpha/rpkg/clone/)) +* creating a new revision of an existing package + ([`kpt alpha rpkg copy`](https://kpt.dev/reference/cli/alpha/rpkg/copy/)) +* pulling package contents for local editing + ([`kpt alpha rpkg pull`](https://kpt.dev/reference/cli/alpha/rpkg/pull/)) +* and pushing updated package contents to Porch + ([`kpt alpha rpkg push`](https://kpt.dev/reference/cli/alpha/rpkg/push/)) + +## Package Lifecycle + +When a new package revision is created, it is in a **`Draft`** lifecycle stage, +where the package can be authored, including updating its contents. + +Before a package can be deployed or cloned, it must be **`Published`**. +The approval flow is the process by which the package is advanced from +**`Draft`** to **`Proposed`** and finally **`Published`** lifecycle stage. + +In the [previous section](#package-authoring) we created several packages, +let's explore how to publish some of them. + +```sh +# List package revisions (the output was abbreviated to only include Draft) +# packages +$ kpt alpha rpkg get +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Draft deployments +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments +deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments +... +``` + +Now, in the role of the package author, we will propose two of those packages +to be published: `istions/v1` and `my-bucket/v2`. + +```sh +# Propose two package revisions to be be published +$ kpt alpha rpkg propose \ + deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b \ + deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 \ + -ndefault + +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b proposed +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 proposed +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [propose command reference](https://kpt.dev/reference/cli/alpha/rpkg/propose/) for usage. +{{% /alert %}} + +The two package revisions are now **`Proposed`**: + +```sh +# Confirm the package revisions are now Proposed (the output was abbreviated +# to only show relevant packages) +$ kpt alpha rpkg get +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Proposed deployments +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Proposed deployments +deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments +... +``` + +At this point, a person in the _platform administrator_ role, or even an +automated process, will review and either approve or reject the proposals. +To aid with the decision, the platform administrator may inspect the package +contents using the commands above, such as `kpt alpha rpkg pull`. + +```sh +# Approve a proposal to publish istions/v1 +$ kpt alpha rpkg approve deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b approved + +# Reject a proposal to publish a my-bucket/v1 +$ kpt alpha rpkg reject deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 -ndefault +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 rejected +``` + +{{% alert title="Note" color="primary" %}} + Refer to the [approve](https://kpt.dev/reference/cli/alpha/rpkg/approve/) and [reject](https://kpt.dev/reference/cli/alpha/rpkg/reject/) + command reference for usage. + {{% /alert %}} + +{{% alert title="Note" color="primary" %}} + Approving a package revisions requires that the current user has been granted + update access to the `approve` subresource of `packagerevisions`. This allows + for giving only a limited set of users permission to approve package revisions. +{{% /alert %}} + +Now, confirm lifecycle stages of the package revisions: + +```sh +# Confirm package revision lifecycle stages after approvals (output was +# abbreviated to display only relevant package revisions): +$ kpt alpha rpkg get +NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY +deployments-98bc9a49246a5bd0f4c7a82f3d07d0d2d1293cd0 istions main false Published deployments +deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 true Published deployments +deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments +deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments +... +``` + +The rejected proposal returned the package to **`Draft`**, and the approved +proposal resulted in **`Published`** package revision. + +You may have noticed that a `main` revision of the istions package appeared. +When a package is approved, Porch will commit it into the branch which was +provided at the repository registration (`main` in this case) and apply a tag. +As a result, the package revision exists in two locations - tag, and the `main` +branch. \ No newline at end of file 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 From bf7a31677faa4bd7df498922ea14508df321eea7 Mon Sep 17 00:00:00 2001 From: Dominika Schweier Date: Thu, 31 Jul 2025 11:34:00 +0200 Subject: [PATCH 3/4] Fixed broken link Signed-off-by: Dominika Schweier --- content/en/docs/porch/user-guides/preparing-the-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 efa31386..3b175ab2 100644 --- a/content/en/docs/porch/user-guides/preparing-the-environment.md +++ b/content/en/docs/porch/user-guides/preparing-the-environment.md @@ -876,7 +876,7 @@ 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). +CRs. See its [documentation for usage information](../basic-usage/porchctl-cli-guide.md). Check that porchctl lists our repositories: From 662820321a1f0dd82b4d66f23de6b8d655f336bf Mon Sep 17 00:00:00 2001 From: Dominika Schweier Date: Thu, 7 Aug 2025 11:19:36 +0200 Subject: [PATCH 4/4] Merging Use Cases into Porch cli guide Signed-off-by: Dominika Schweier --- content/en/docs/porch/basic-usage/_index.md | 6 - .../en/docs/porch/basic-usage/use-cases.md | 717 ------------------ .../porchctl-cli-guide.md | 110 ++- .../user-guides/preparing-the-environment.md | 2 +- 4 files changed, 108 insertions(+), 727 deletions(-) delete mode 100644 content/en/docs/porch/basic-usage/_index.md delete mode 100644 content/en/docs/porch/basic-usage/use-cases.md rename content/en/docs/porch/{basic-usage => user-guides}/porchctl-cli-guide.md (90%) diff --git a/content/en/docs/porch/basic-usage/_index.md b/content/en/docs/porch/basic-usage/_index.md deleted file mode 100644 index 45c1702d..00000000 --- a/content/en/docs/porch/basic-usage/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Porch basic usage" -type: docs -weight: 7 -description: ---- \ No newline at end of file diff --git a/content/en/docs/porch/basic-usage/use-cases.md b/content/en/docs/porch/basic-usage/use-cases.md deleted file mode 100644 index 6237df27..00000000 --- a/content/en/docs/porch/basic-usage/use-cases.md +++ /dev/null @@ -1,717 +0,0 @@ ---- -title: "Use Cases" -type: docs -weight: 4 -description: ---- - -## Quickstart - -​​In this quickstart you will use Porch to discover configuration packages -in a [sample repository](https://github.com/kptdev/kpt-samples). - -You will use the kpt CLI - the new `kpt alpha` command sub-groups to interact -with the Package Orchestration service. - -### Register the repository - -Start by registering the sample repository with Porch. The repository already -contains a [`basens`](https://github.com/kptdev/kpt-samples/tree/main/basens) package. - -```sh -# Register a sample Git repository: -$ kpt alpha repo register --namespace default \ - https://github.com/kptdev/kpt-samples.git -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [register command reference](https://kpt.dev/reference/cli/alpha/repo/reg/) for usage. -{{% /alert %}} - -The sample repository is public and Porch therefore doesn't require -authentication to read the repository and discover packages within it. - -You can confirm the repository is now registered with Porch by using the -`kpt alpha repo get` command. Similar to `kubectl get`, the command will list -all repositories registered with Porch, or get information about specific ones -if list of names is provided - -```sh -# Query repositories registered with Porch: -$ kpt alpha repo get -NAME TYPE CONTENT DEPLOYMENT READY ADDRESS -kpt-samples git Package True https://github.com/kptdev/kpt-samples.git -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. -{{% /alert %}} - -From the output you can see that: - -* the repository was registered by the name `kpt-samples`. This was chosen - by kpt automatically from the repository URL, but can be overridden -* it is a `git` repository (OCI repositories are also supported, though - currently with some limitations) -* the repository is *not* a deployment repository. Repository can be marked - as deployment repository which indicates that packages in the repository are - intended to be deployed into live state. -* the repository is ready - Porch successfully registered it and discovered - packages stored in the repository. - -The Package Orchestration service is designed to be part of the Kubernetes -ecosystem. The [resources](porchctl-cli-guide.md) managed by Porch are KRM -resources. - -You can use the `-oyaml` to see the YAML representation of the repository -registration resource: - -{{% alert title="Note" color="primary" %}} - kpt uses the same output format flags as `kubectl`. Flags with which you are -already familiar from using `kubectl get` will work with the kpt commands -that get or list Porch resources. -{{% /alert %}} - -```sh -# View the Repository registration resource as YAML: -$ kpt alpha repo get kpt-samples --namespace default -oyaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: Repository -metadata: - name: kpt-samples - namespace: default -spec: - content: Package - git: - branch: main - directory: / - repo: https://github.com/kptdev/kpt-samples.git - secretRef: - name: "" - type: git -status: - conditions: - - reason: Ready - status: "True" - type: Ready -``` - -Few additional details are available in the YAML listing: - -The name of the `main` branch and a directory. These specify location within -the repository where Porch will be managing packages. Porch also analyzes tags -in the repository to identify all packages (and their specific versions), all -within the directory specified. By default Porch will analyze the whole -repository. - -The `secretRef` can contain a name of a Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) -resource with authentication credentials for Porch to access the repository. - -#### kubectl - -Thanks to the integration with Kubernetes ecosystem, you can also use `kubectl` -directly to interact with Porch, such as listing repository resources: - -```sh -# List registered repositories using kubectl -$ kubectl get repository -NAME TYPE CONTENT DEPLOYMENT READY ADDRESS -kpt-samples git Package True https://github.com/kptdev/kpt-samples.git -``` - -You can use kubectl for _all_ interactions with Porch server if you prefer. -The kpt CLI integration provides a variety of convenience features. - -### Discover packages - -You can use the `kpt alpha rpkg get` command to list the packages discovered -by Porch across all registered repositories. - -```sh -# List package revisions in registered repositories -$ kpt alpha rpkg get -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -kpt-samples-da07e9611f9b99028f761c07a79e3c746d6fc43b basens main false Published kpt-samples -kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 basens v0 true Published kpt-samples -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. -{{% /alert %}} - -{{% alert title="Note" color="primary" %}} - The `r` prefix of the `rpkg` command group stands for `remote`. The commands -in the `kpt alpha rpkg` group interact with packages managed (remotely) by Porch -server. The commands in the `rpkg` group are similar to the `kpt pkg` commands -except that they operate on remote packages managed by Porch server rather than -on a local disk. -{{% /alert %}} - -The output shows that Porch discovered the `basens` package, and found two -different revisions of it. The `v0` revision (associated with the -[`basens/v0`](https://github.com/kptdev/kpt-samples/tree/basens/v0) tag) and the `main` revision associated with the -[`main` branch](https://github.com/kptdev/kpt-samples/tree/main) in the repository. - -The `LIFECYCLE` column indicates the lifecycle stage of the package revision. -The package revisions in the repository are *`Published`* - ready to be used. -Package revision may be also *`Draft`* (the package revision is being authored) -or *`Proposed`* (the author of the package revision proposed that it be -published). We will encounter examples of these - -Porch identifies the latest revision of the package (`LATEST` column). - -#### View package resources - -The `kpt alpha rpkg get` command displays package metadata. To view the -_contents_ of the package revision, use the `kpt alpha rpkg pull` command. - -You can use the command to output the resources as a -[`ResourceList`][resourcelist] on standard output, or save them into a local -directory: - -```sh -# View contents of the basens/v0 package revision -$ kpt alpha rpkg pull kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 -ndefault - -apiVersion: config.kubernetes.io/v1 -kind: ResourceList -items: -- apiVersion: kpt.dev/v1 - kind: Kptfile - metadata: - name: basens - annotations: -... -``` - -Add a name of a local directory on the command line to save the package onto -local disk for inspection or editing. - -```sh -# Pull package revision resources, save to local disk into `./basens` directory -$ kpt alpha rpkg pull kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 ./basens -ndefault - -# Explore the package contents -$ find basens - -basens -basens/README.md -basens/namespace.yaml -basens/Kptfile -... -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [pull command reference](https://kpt.dev/reference/cli/alpha/rpkg/pull/) for usage. -{{% /alert %}} - -### Unregister the repository - -When you are done using the repository with Porch, you can unregister it: - -```sh -# Unregister the repository -$ kpt alpha repo unregister kpt-samples -ndefault -``` - -### More resources - -To continue learning about Porch, you can review: - -* [Using the Porch CLI tool](porchctl-cli-guide.md) -* [Provisioning Namespaces with the UI](https://kpt.dev/guides/namespace-provisioning-ui/) -* [Package Orchestration](../package-orchestration.md) - -## Registering a Repository - -In the following sections of this chapter you will explore package authoring -using Porch. You will need: - -* A GitHub repository for your blueprints. An otherwise empty repository with an - initial commit works best. The initial commit is required to establish the - `main` branch. -* A GitHub [Personal Access Token](https://github.com/settings/tokens) with - the `repo` scope for Porch to authenticate with the repository and allow it - to create commits in the repository. - -A repository is a porch representation of either a git repo or an oci registry. -Package revisions always belong to a single repository. A repository exists in -a Kubernetes namespace and all package revisions in a repo also belong to -the same namespace. - -Use the `kpt alpha repo register` command to register your repository with -Porch: The command below uses the repository `deployments.git`. -Your repository name may be different; please update the command with the -correct repository name. - -```sh -# Register your Git repository: - -GITHUB_USERNAME= - -GITHUB_TOKEN= - -REPOSITORY_ADDRESS= - - -$ kpt alpha repo register \ - --namespace default \ - --name deployments \ - --deployment \ - --repo-basic-username=${GITHUB_USERNAME} \ - --repo-basic-password=${GITHUB_TOKEN} \ - ${REPOSITORY_ADDRESS} -``` - -And register the sample repository we used in the [quickstart](#quickstart): - -```sh -# Register the sample repository: - -kpt alpha repo register --namespace default \ - https://github.com/kptdev/kpt-samples.git -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [register command reference](https://kpt.dev/reference/cli/alpha/repo/reg/) for usage. -{{% /alert %}} - -You now have two repositories registered, and your repository is marked as -deployment repository. This indicates that published packages in the repository -are considered deployment-ready. - -```sh -# Query repositories registered with Porch: -$ kpt alpha repo get -NAME TYPE CONTENT DEPLOYMENT READY ADDRESS -deployments git Package true True [Your repository address] -kpt-samples git Package True https://github.com/kptdev/kpt-samples.git -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [get command reference](https://kpt.dev/reference/cli/alpha/repo/get/) for usage. -{{% /alert %}} - -## Package Authoring - -There are several ways to author a package revision, including creating -a completely new one, cloning an existing package, or creating a new revision -of an existing package. In this section we will explore the different ways to -author package revisions, and explore how to modify package contents. - -### Create a new package revision - -Create a new package revision in a repository managed by Porch: - -```sh -# Initialize a new (empty) package revision: -$ kpt alpha rpkg init new-package --repository=deployments --revision=v1 -ndefault - -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 created - -# List the available package revisions. -$ kpt alpha rpkg get - -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments -kpt-samples-da07e9611f9b99028f761c07a79e3c746d6fc43b basens main false Published kpt-samples -kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 basens v0 true Published kpt-samples -... -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [init command reference](https://kpt.dev/reference/cli/alpha/rpkg/init/) for usage. -{{% /alert %}} - -You can see the `new-package` is created in the `Draft` lifecycle stage. This -means that the package is being authored. - -{{% alert title="Note" color="primary" %}} - You may notice that the name of the package revision - `deployments-c32b851b591b860efda29ba0e006725c8c1f7764` was assigned - automatically. Packages in a git repository may be located in subdirectories - and to make sure Porch works well with the rest of the Kubernetes ecosystem, - the resource names must meet Kubernetes requirements. The resource names - assigned by Porch are stable, and computed as hash of the repository name, - directory path within the repository, and revision. -{{% /alert %}} - -The contents of the new package revision are the same as if it was created using -the [`kpt pkg init`](https://kpt.dev/book/03-packages/06-creating-a-package) command, except it -was created by the Package Orchestration service in your repository. - -In fact, if you check your Git repository, you will see a new branch called -`drafts/new-package/v1` which Porch created for the draft authoring. You will -also see one or more commits made into the branch by Porch on your behalf. - -### Clone an existing package - -Another way to create a new package revision is by cloning an already existing -package. The existing package is referred to as *upstream* and the newly created -package is *downstream*. - -Use `kpt alpha rpkg clone` command to create a new *downstream* package -`istions` by cloning the sample `basens/v0` package revision: - -```sh -# Clone an upstream package to create a downstream package -$ kpt alpha rpkg clone \ - kpt-samples-afcf4d1fac605a60ba1ea4b87b5b5b82e222cb69 \ - istions \ - --repository=deployments -ndefault - -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b created - -# Confirm the package revision was created -kpt alpha rpkg get deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Draft deployments -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [clone command reference](https://kpt.dev/reference/cli/alpha/rpkg/clone/) for usage. -{{% /alert %}} - -Cloning a package using the Package Orchestration service is an action similar to -[`kpt pkg get`](https://kpt.dev/book/03-packages/01-getting-a-package) command. Porch will -create the appropriate upstream package links in the new package's `Kptfile`. -Let's take a look: - -```sh -# Examine the new package's upstream link (the output has been abbreviated): -$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault - -kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault -apiVersion: config.kubernetes.io/v1 -kind: ResourceList -items: -- apiVersion: kpt.dev/v1 - kind: Kptfile - metadata: - name: istions - upstream: - type: git - git: - repo: https://github.com/kptdev/kpt-samples.git - directory: basens - ref: basens/v0 - upstreamLock: - type: git - git: - repo: https://github.com/kptdev/kpt-samples.git - directory: basens - ref: basens/v0 - commit: 026dfe8e3ef8d99993bc8f7c0c6ba639faa9a634 - info: - description: kpt package for provisioning namespace -... -``` - -You can find out more about the `upstream` and `upstreamLock` sections of the -`Kptfile` in an [earlier chapter](https://kpt.dev/book/03-packages/01-getting-a-package) -of the book. - -{{% 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 %}} - -You can also clone a package from a repository that is _not_ registered with -Porch, for example: - -```sh -# Clone a package from Git repository directly (repository is not registered) -$ kpt alpha rpkg clone \ - https://github.com/GoogleCloudPlatform/blueprints.git/catalog/bucket@main my-bucket \ - --repository=deployments \ - --namespace=default - -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 created - -# Confirm the package revision was created -$ kpt alpha rpkg get deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 -ndefault -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments -``` - -### Create a new revision of an existing package - -Finally, with Porch you can create a new revision of an existing, -**`Published`** package. All the package revisions in your repository are -**`Draft`** revisions and need to be published first. We will cover the package -approval flow in more detail in the next section. For now we will quickly -propose and approve one of our draft package revisions and create a new revision -from it. - -```sh -# Propose the package draft to be published -$ kpt alpha rpkg propose deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 proposed - -# Approve the proposed package revision for publishing -$ kpt alpha rpkg approve deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 approved -``` - -You now have a **`Published`** package revision in the repository managed by Porch -and next you will create a new revision of it. A **`Published`** package is ready -to be used, such as deployed or copied. - -```sh -# Confirm the package is published: -$ kpt alpha rpkg get deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 true Published deployments -``` - -Copy the existing, **`Published`** package revision to create a **`Draft`** of -a new package revision that you can further customize: - -```sh -# Copy the published package: -$ kpt alpha rpkg copy deployments-c32b851b591b860efda29ba0e006725c8c1f7764 \ - -ndefault --revision v2 -deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a created - -# List all revisions of the new-package that we just copied: -$ kpt alpha rpkg get --name new-package -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-af86ae3c767b0602a198856af513733e4e37bf10 new-package main false Published deployments -deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 true Published deployments -deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [copy command reference](https://kpt.dev/reference/cli/alpha/rpkg/copy/) for usage. -{{% /alert %}} - -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 `new-package/v1` and `new-package/v2` have identical contents, -including upstream information, and differ in revision only. - -### Editing package revision resources - -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. - -```sh -# Pull the package contents of istions/v1 onto the local disk: -$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./istions -ndefault -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [pull command reference][rpkg-pull] for usage. -{{% /alert %}} - -The command downloaded the `istions/v1` package revision contents and saved -them in the `./istions` directory. Now you will make some changes. - -First, note that even though Porch updated the namespace name (in -`namespace.yaml`) to `istions` 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: - -``` -# istions - -## Description -kpt package for provisioning Istio 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 -$ kpt alpha rpkg push deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./istions -ndefault -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [push command reference](https://kpt.dev/reference/cli/alpha/rpkg/push/) for usage. -{{% /alert %}} - -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: -$ kpt alpha rpkg pull deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b ./updated-istions -ndefault - -# Inspect updated-istions/namespace.yaml -$ cat updated-istions/namespace.yaml - -apiVersion: v1 -kind: Namespace -metadata: - name: istions - 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`). - -### Summary of package authoring - -In this section we reviewed how to use Porch to author packages, including - -* creating a new package ([`kpt alpha rpkg init`](https://kpt.dev/reference/cli/alpha/rpkg/init/)) -* cloning an existing package ([`kpt alpha rpkg clone`](https://kpt.dev/reference/cli/alpha/rpkg/clone/)) -* creating a new revision of an existing package - ([`kpt alpha rpkg copy`](https://kpt.dev/reference/cli/alpha/rpkg/copy/)) -* pulling package contents for local editing - ([`kpt alpha rpkg pull`](https://kpt.dev/reference/cli/alpha/rpkg/pull/)) -* and pushing updated package contents to Porch - ([`kpt alpha rpkg push`](https://kpt.dev/reference/cli/alpha/rpkg/push/)) - -## Package Lifecycle - -When a new package revision is created, it is in a **`Draft`** lifecycle stage, -where the package can be authored, including updating its contents. - -Before a package can be deployed or cloned, it must be **`Published`**. -The approval flow is the process by which the package is advanced from -**`Draft`** to **`Proposed`** and finally **`Published`** lifecycle stage. - -In the [previous section](#package-authoring) we created several packages, -let's explore how to publish some of them. - -```sh -# List package revisions (the output was abbreviated to only include Draft) -# packages -$ kpt alpha rpkg get -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Draft deployments -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments -deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments -... -``` - -Now, in the role of the package author, we will propose two of those packages -to be published: `istions/v1` and `my-bucket/v2`. - -```sh -# Propose two package revisions to be be published -$ kpt alpha rpkg propose \ - deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b \ - deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 \ - -ndefault - -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b proposed -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 proposed -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [propose command reference](https://kpt.dev/reference/cli/alpha/rpkg/propose/) for usage. -{{% /alert %}} - -The two package revisions are now **`Proposed`**: - -```sh -# Confirm the package revisions are now Proposed (the output was abbreviated -# to only show relevant packages) -$ kpt alpha rpkg get -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 false Proposed deployments -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Proposed deployments -deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments -... -``` - -At this point, a person in the _platform administrator_ role, or even an -automated process, will review and either approve or reject the proposals. -To aid with the decision, the platform administrator may inspect the package -contents using the commands above, such as `kpt alpha rpkg pull`. - -```sh -# Approve a proposal to publish istions/v1 -$ kpt alpha rpkg approve deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b -ndefault -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b approved - -# Reject a proposal to publish a my-bucket/v1 -$ kpt alpha rpkg reject deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 -ndefault -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 rejected -``` - -{{% alert title="Note" color="primary" %}} - Refer to the [approve](https://kpt.dev/reference/cli/alpha/rpkg/approve/) and [reject](https://kpt.dev/reference/cli/alpha/rpkg/reject/) - command reference for usage. - {{% /alert %}} - -{{% alert title="Note" color="primary" %}} - Approving a package revisions requires that the current user has been granted - update access to the `approve` subresource of `packagerevisions`. This allows - for giving only a limited set of users permission to approve package revisions. -{{% /alert %}} - -Now, confirm lifecycle stages of the package revisions: - -```sh -# Confirm package revision lifecycle stages after approvals (output was -# abbreviated to display only relevant package revisions): -$ kpt alpha rpkg get -NAME PACKAGE REVISION LATEST LIFECYCLE REPOSITORY -deployments-98bc9a49246a5bd0f4c7a82f3d07d0d2d1293cd0 istions main false Published deployments -deployments-eeb52a8072ca2602e7ee27f3c56ad6344b024f5b istions v1 true Published deployments -deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 my-bucket v1 false Draft deployments -deployments-93bb9ac8c2fb7a5759547a38f5f48b369f42d08a new-package v2 false Draft deployments -... -``` - -The rejected proposal returned the package to **`Draft`**, and the approved -proposal resulted in **`Published`** package revision. - -You may have noticed that a `main` revision of the istions package appeared. -When a package is approved, Porch will commit it into the branch which was -provided at the repository registration (`main` in this case) and apply a tag. -As a result, the package revision exists in two locations - tag, and the `main` -branch. \ No newline at end of file diff --git a/content/en/docs/porch/basic-usage/porchctl-cli-guide.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md similarity index 90% rename from content/en/docs/porch/basic-usage/porchctl-cli-guide.md rename to content/en/docs/porch/user-guides/porchctl-cli-guide.md index 6b5d1cb4..2a7fd864 100644 --- a/content/en/docs/porch/basic-usage/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 3b175ab2..efa31386 100644 --- a/content/en/docs/porch/user-guides/preparing-the-environment.md +++ b/content/en/docs/porch/user-guides/preparing-the-environment.md @@ -876,7 +876,7 @@ 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](../basic-usage/porchctl-cli-guide.md). +CRs. See its [documentation for usage information](porchctl-cli-guide.md). Check that porchctl lists our repositories: