From 56e2cadf52d8454864fef212f5f21802d4b1c9fa Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 15:26:04 +0000 Subject: [PATCH] Remove kpt alpha cli calls --- .../porch/running-porch/running-on-GKE.md | 33 +--- .../using-porch/install-and-using-porch.md | 4 +- .../porch/using-porch/usage-porch-kpt-cli.md | 143 ++++++------------ 3 files changed, 56 insertions(+), 124 deletions(-) diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index a450b072..4c896e2a 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -24,7 +24,7 @@ need: * A [GCP Project](https://console.cloud.google.com/projectcreate) * [gcloud](https://cloud.google.com/sdk/docs/install) * [kubectl](https://kubernetes.io/docs/tasks/tools/); you can install it via `gcloud components install kubectl` -* [kpt](https://kpt.dev/) +* [porchctl](https://github.com/nephio-project/porch/releases/download/main/porchctl.tgz) * Command line utilities such as *curl*, *tar* To build and run Porch on GKE, you will also need: @@ -32,7 +32,7 @@ To build and run Porch on GKE, you will also need: * A container registry which will work with your GKE cluster. [Artifact Registry](https://console.cloud.google.com/artifacts) or [Container Registry](https://console.cloud.google.com/gcr) work well though you can use others too. -* [go 1.17](https://go.dev/dl/) or newer +* [go 1.21](https://go.dev/dl/) or newer * [docker](https://docs.docker.com/get-docker/) * [Configured docker credential helper](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker) * [git](https://git-scm.com/) @@ -75,14 +75,14 @@ gcloud container clusters get-credentials --region us-central1 porch-dev To run a released version of Porch, download the release config bundle from [Porch release page](https://github.com/nephio-project/porch/releases). -Untar and apply the *deployment-blueprint.tar.gz* config bundle. This will install: +Untar and apply the *porch_blueprint.tar.gz* config bundle. This will install: * Porch server * [Config Sync](https://kpt.dev/gitops/configsync/) ```bash mkdir porch-install -tar xzf ~/Downloads/deployment-blueprint.tar.gz -C porch-install +tar xzf ~/Downloads/porch_blueprint.tar.gz -C porch-install kubectl apply -f porch-install kubectl wait deployment --for=condition=Available porch-server -n porch-system ``` @@ -136,7 +136,7 @@ IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa ``` If you want to use a different repository, you can set IMAGE_REPO variable -(see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L32) for details). +(see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L33) for details). The `make push-and-deploy-no-sa` target will install Porch but not Config Sync. You can install Config Sync in your k8s cluster manually following the @@ -190,11 +190,7 @@ kubectl annotate serviceaccount porch-server -n porch-system \ iam.gke.io/gcp-service-account=porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com ``` -<<<<<<< HEAD Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity -======= -Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity ->>>>>>> main service account annotations: ```bash @@ -210,7 +206,7 @@ kubectl api-resources | grep porch To register a repository, use the following command: ```bash -kpt alpha repo register --repo-workload-identity --namespace=default https://source.developers.google.com/p//r/ +porchctl repo register --repo-workload-identity --namespace=default https://source.developers.google.com/p//r/ ``` #### OCI @@ -248,20 +244,3 @@ gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}. --role roles/iam.workloadIdentityUser \ --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]" ``` - -<<<<<<< HEAD -Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity -======= -Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity ->>>>>>> main -service account annotations: - -```bash -IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy -``` - -As above, you can verify that Porch is running by querying the api-resources: - -```bash -kubectl api-resources | grep porch -``` \ No newline at end of file diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index 73a500ad..68a28b0c 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -7,7 +7,7 @@ description: "A tutorial to install and use Porch" This tutorial is a guide to installing and using Porch. It is based on the [Porch demo produced by Tal Liron of Google](https://github.com/tliron/klab/tree/main/environments/porch-demo). Users -should be very comfortable with using *git*, *docker*, and *kubernetes*. +should be comfortable using *git*, *docker*, and *kubernetes*. See also [the Nephio Learning Resource](https://github.com/nephio-project/docs/blob/main/learning.md) page for background help and information. @@ -1954,7 +1954,7 @@ In these packages, you will see that: 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 chages as we had to in 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: diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md index 3938f887..eff35cf1 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md @@ -28,13 +28,12 @@ To check whether `kubectl` is configured with your Porch cluster (or local insta kubectl api-resources | grep porch ``` -You should see the following four resourceds listed: +You should see the following api resources listed: ```bash repositories config.porch.kpt.dev/v1alpha1 true Repository packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision -functions porch.kpt.dev/v1alpha1 true Function ``` ## Porch Resources @@ -74,14 +73,14 @@ To use Porch with an OCI repository ([Artifact Registry](https://console.cloud.g (`iam.gke.io/gcp-service-account=porch-server@$(GCP_PROJECT_ID).iam.gserviceaccount.com`) to have appropriate level of access to your OCI repository. -Use the `kpt alpha repo register` command to register your repository with Porch: +Use the `porchctl repo register` command to register your repository with Porch: ```bash GITHUB_USERNAME= GITHUB_TOKEN= -$ kpt alpha repo register \ +$ porchctl repo register \ --namespace default \ --repo-basic-username=${GITHUB_USERNAME} \ --repo-basic-password=${GITHUB_TOKEN} \ @@ -102,37 +101,37 @@ All command line flags supported: Additionally, common `kubectl` command line flags for controlling aspects of interaction with the Kubernetes apiserver, logging, and more (this is true for -all `kpt` CLI commands which interact with Porch). +all `porchctl` CLI commands which interact with Porch). -Use the `kpt alpha repo get` command to query registered repositories: +Use the `porchctl repo get` command to query registered repositories: ```bash -$ kpt alpha repo get +$ porchctl repo get NAME TYPE CONTENT DEPLOYMENT READY ADDRESS blueprints git Package True https://github.com/platkrm/blueprints.git deployments git Package true True https://github.com/platkrm/deployments.git ``` -The `kpt alpha get` commands support common `kubectl` +The `porchctl get` commands support common `kubectl` [flags](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#formatting-output) to format output, for example -`kpt alpha repo get --output=yaml`. +`porchctl repo get --output=yaml`. -The command `kpt alpha repo unregister` can be used to unregister a repository: +The command `porchctl repo unregister` can be used to unregister a repository: ```bash -$ kpt alpha repo unregister deployments --namespace default +$ porchctl repo unregister deployments --namespace default ``` ## Package Discovery And Introspection -The `kpt alpha rpkg` command group contains commands for interacting with packages managed by the Package Orchestration +The `porchctl rpkg` command group contains commands for interacting with packages managed by the Package Orchestration service. the `r` prefix used in the command group name stands for 'remote'. -The `kpt alpha rpkg get` command list the packages in registered repositories: +The `porchctl rpkg get` command list the packages in registered repositories: ```bash -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-0349d71330b89ee48ac85167598ef23021fd0484 basens main main false Published blueprints @@ -146,14 +145,13 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 The `LATEST` column indicates whether the package revision is the latest among the revisions of the same package. In the output above, `v2` is the latest revision of `istions` package and `v1` is the latest revision of `basens` package. -The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Published`, `Draft` or -`Proposed`. +The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Draft`, `Proposed` or `Published`. The `REVISION` column indicates the revision of the package. Revisions are assigned when a package is `Published` and starts at `v1`. The `WORKSPACENAME` column indicates the workspace name of the package. The workspace name is assigned when a draft -revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be +revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be unique among package revisions in the same package. {{% alert title="Note" color="primary" %}} @@ -170,7 +168,7 @@ Simple filtering of package revisions by name (substring) and revision (exact ma `--name` and `--revision` flags: ```bash -$ kpt alpha rpkg get --name istio --revision=v2 +$ porchctl rpkg get --name istio --revision=v2 NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints @@ -179,7 +177,7 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 The common `kubectl` flags that control output format are available as well: ```bash -$ kpt alpha rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml +$ porchctl rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml apiVersion: porch.kpt.dev/v1alpha1 kind: PackageRevision @@ -197,14 +195,14 @@ spec: ... ``` -The `kpt alpha rpkg pull` command can be used to read the package resources. +The `porchctl rpkg pull` command can be used to read the package resources. The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables [chaining](https://kpt.dev/book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe) evaluation of functions on the package revision pulled from the Package Orchestration server. ```bash -$ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault +$ porchctl rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList @@ -219,7 +217,7 @@ items: Or, the package contents can be saved on local disk for direct introspection or editing: ```bash -$ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 ./istions -ndefault +$ porchctl rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 ./istions -ndefault $ find istions @@ -233,7 +231,7 @@ istions/package-context.yaml ## Authoring Packages -Several commands in the `kpt alpha rpkg` group support package authoring: +Several commands in the `porchctl rpkg` group support package authoring: * `init` - Initializes a new package revision in the target repository. * `clone` - Creates a clone of a source package in the target repository. @@ -241,15 +239,15 @@ Several commands in the `kpt alpha rpkg` group support package authoring: * `push` - Pushes package resources into a remote package. * `del` - Deletes one or more packages in registered repositories. -The `kpt alpha rpkg init` command can be used to initialize a new package revision. Porch server will create and +The `porchctl rpkg init` command can be used to initialize a new package revision. Porch server will create and initialize a new package (as a draft) and save it in the specified repository. ```bash -$ kpt alpha rpkg init new-package --repository=deployments --workspace=v1 -ndefault +$ porchctl rpkg init new-package --repository=deployments --workspace=v1 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 created -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments @@ -259,7 +257,7 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 The new package is created in the `Draft` lifecycle stage. This is true also for all commands that create new package revision (`init`, `clone` and `copy`). -Additional flags supported by the `kpt alpha rpkg init` command are: +Additional flags supported by the `porchctl rpkg init` command are: * `--repository` - Repository in which the package will be created. * `--workspace` - Workspace of the new package. @@ -268,24 +266,24 @@ Additional flags supported by the `kpt alpha rpkg init` command are: * `--site` - Link to page with information about the package. -Use `kpt alpha rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: +Use `porchctl rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: ```bash -$ kpt alpha rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ +$ porchctl rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ --repository=deployments -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 created # Confirm the package revision was created -kpt alpha rpkg get deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault +porchctl rpkg get deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 false Draft deployments ``` -`kpt alpha rpkg clone` can also be used to clone packages that are in repositories not registered with Porch, for +`porchctl rpkg clone` can also be used to clone packages that are in repositories not registered with Porch, for example: ```bash -$ kpt alpha rpkg clone \ +$ porchctl rpkg clone \ https://github.com/GoogleCloudPlatform/blueprints.git cloned-bucket \ --directory=catalog/bucket \ --ref=main \ @@ -294,12 +292,12 @@ $ kpt alpha rpkg clone \ deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac created # Confirm the package revision was created -kpt alpha rpkg get deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac -ndefault +porchctl rpkg get deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments ``` -The flags supported by the `kpt alpha rpkg clone` command are: +The flags supported by the `porchctl rpkg clone` command are: * `--directory` - Directory within the upstream repository where the upstream package is located. @@ -312,24 +310,24 @@ The flags supported by the `kpt alpha rpkg clone` command are: one of: `resource-merge`, `fast-forward`, `force-delete-replace`. -The `kpt alpha rpkg copy` command can be used to create a new revision of an existing package. It is a means to +The `porchctl rpkg copy` command can be used to create a new revision of an existing package. It is a means to modifying an already published package revision. ```bash -$ kpt alpha rpkg copy \ +$ porchctl rpkg copy \ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 \ --workspace=v3 -ndefault # Confirm the package revision was created -$ kpt alpha rpkg get blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault +$ porchctl rpkg get blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 istions v3 false Draft blueprints ``` -The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package _draft_: +The `porchctl rpkg push` command can be used to update the resources (package contents) of a package _draft_: ```bash -$ kpt alpha rpkg pull \ +$ porchctl rpkg pull \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault # Make edits using your favorite YAML editor, for example adding a new resource @@ -344,11 +342,11 @@ EOF # Push the updated contents to the Package Orchestration server, updating the # package contents. -$ kpt alpha rpkg push \ +$ porchctl rpkg push \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault # Confirm that the remote package now includes the new ConfigMap resource -$ kpt alpha rpkg pull deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +$ porchctl rpkg pull deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList @@ -363,11 +361,11 @@ items: ... ``` -Package revision can be deleted using `kpt alpha rpkg del` command: +Package revision can be deleted using `porchctl rpkg del` command: ```bash # Delete package revision -$ kpt alpha rpkg del blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault +$ porchctl rpkg del blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 deleted ``` @@ -389,7 +387,7 @@ we will create proposals for publishing some of them. ```bash # List package revisions to identify relevant drafts: -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -397,7 +395,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments # Propose two package revisions to be be published -$ kpt alpha rpkg propose \ +$ porchctl rpkg propose \ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 \ -ndefault @@ -406,7 +404,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 proposed deployments-c32b851b591b860efda29ba0e006725c8c1f7764 proposed # Confirm the package revisions are now Proposed -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -416,15 +414,15 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 At this point, a person in _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`. +commands above, such as `porchctl rpkg pull`. ```bash # Approve a proposal to publish a package revision -$ kpt alpha rpkg approve deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault +$ porchctl rpkg approve deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 approved # Reject a proposal to publish a package revision -$ kpt alpha rpkg reject deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +$ porchctl rpkg reject deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 rejected ``` @@ -432,7 +430,7 @@ Now the user can confirm lifecycle stages of the package revisions: ```bash # Confirm package revision lifecycle stages after approvals: -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -442,48 +440,3 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose proposal was approved is now in _Published_ state. - -## Deploying a Package - -Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named `sync` to -emphasize that Config Sync is the deploying mechanism and that configuration is being synchronized with the actuation -target as a means of deployment) and include: - -* `create` - Creates a sync of a package in the deployment cluster. -* `del` - Deletes the package RootSync. -* `get` - Gets a RootSync resource with which package was deployed. - -```bash -# Make sure Config Sync is configured to use multirepo mode -kubectl apply -f - <