From 56e2cadf52d8454864fef212f5f21802d4b1c9fa Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 15:26:04 +0000 Subject: [PATCH 1/3] 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 - < Date: Mon, 9 Dec 2024 18:36:44 +0000 Subject: [PATCH 2/3] Refactor porch cli and user guides --- .../guides/install-guides/install-on-byoc.md | 2 +- .../install-guides/install-on-multiple-vm.md | 2 +- content/en/docs/porch/_index.md | 4 +- .../environment-setup-vm.md | 2 +- .../contributors-guide/environment-setup.md | 4 +- .../en/docs/porch/package-orchestration.md | 2 +- .../{using-porch => user-guides}/_index.md | 2 +- .../adding-external-git-ca-bundle.md | 0 .../install-and-using-porch.md | 0 .../porchctl-cli-guide.md} | 59 +++++++++++--- .../using-authenticated-private-registries.md | 0 .../porch/using-porch/porchctl-cli-guide.md | 78 ------------------- 12 files changed, 58 insertions(+), 97 deletions(-) rename content/en/docs/porch/{using-porch => user-guides}/_index.md (61%) rename content/en/docs/porch/{using-porch => user-guides}/adding-external-git-ca-bundle.md (100%) rename content/en/docs/porch/{using-porch => user-guides}/install-and-using-porch.md (100%) rename content/en/docs/porch/{using-porch/usage-porch-kpt-cli.md => user-guides/porchctl-cli-guide.md} (85%) rename content/en/docs/porch/{using-porch => user-guides}/using-authenticated-private-registries.md (100%) delete mode 100644 content/en/docs/porch/using-porch/porchctl-cli-guide.md diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 642f8e0b..2643f3c2 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -21,7 +21,7 @@ your environment and choices. - *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation - *kpt* [installed](https://kpt.dev/installation/kpt-cli) on your workstation (version v1.0.0-beta.43 or later) - - *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation + - *porchctl* [installed](/content/en/docs/porch/user-guides/porchctl-cli-guide.md) on your workstation - Sudo-less *docker*, *podman*, or *nerdctl*. If using *podman* or *nerdctl*, you must set the [`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index bc5c46b7..79d563c1 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -19,7 +19,7 @@ weight: 7 * Kubernetes version 1.26+ * *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) * *kpt* [installed](https://kpt.dev/installation/kpt-cli) (version v1.0.0-beta.43 or later) -* *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation +* *porchctl* [installed](/content/en/docs/porch/user-guides/porchctl-cli-guide.md) on your workstation ## Installation of the management cluster diff --git a/content/en/docs/porch/_index.md b/content/en/docs/porch/_index.md index 9d381def..8425fd58 100644 --- a/content/en/docs/porch/_index.md +++ b/content/en/docs/porch/_index.md @@ -7,8 +7,8 @@ description: Documentation of Porch ## Overview - Porch is “kpt-as-a-service”, providing opinionated package management, manipulation, and lifecycle operations in a - Kubernetes-based API. This allows automation of these operations using standard Kubernetes controller techniques. +Porch is “kpt-as-a-service”, providing opinionated package management, manipulation, and lifecycle operations in a +Kubernetes-based API. This allows automation of these operations using standard Kubernetes controller techniques. "Porch" is short for "Package Orchestration". diff --git a/content/en/docs/porch/contributors-guide/environment-setup-vm.md b/content/en/docs/porch/contributors-guide/environment-setup-vm.md index b113725c..d64ecc56 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup-vm.md +++ b/content/en/docs/porch/contributors-guide/environment-setup-vm.md @@ -8,7 +8,7 @@ description: This tutorial gives short instructions on how to set up a development environment for Porch on a Nephio VM. It outlines the steps to get a [kind](https://kind.sigs.k8s.io/) cluster up and running to which a Porch instance running in Visual Studio Code can connect to and interact with. If you are not familiar with how porch works, it is highly recommended that you go -through the [Starting with Porch tutorial](../using-porch/install-and-using-porch.md) before going through this one. +through the [Starting with Porch tutorial](../user-guides/install-and-using-porch.md) before going through this one. ## Setting up the environment diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 1bec3256..a790b750 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -8,7 +8,7 @@ description: This tutorial gives short instructions on how to set up a development environment for Porch on your local machine. It outlines the steps to get a [kind](https://kind.sigs.k8s.io/) cluster up and running to which a Porch instance running in Visual Studio Code can connect to and interact with. If you are not familiar with how porch works, it is highly recommended that you go -through the [Starting with Porch tutorial](../using-porch/install-and-using-porch.md) before going through this one. +through the [Starting with Porch tutorial](../user-guides/install-and-using-porch.md) before going through this one. {{% alert title="Note" color="primary" %}} @@ -123,7 +123,7 @@ packages porch.kpt.dev/v1alpha1 ## Create Repositories using your local Porch server -To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../using-porch/install-and-using-porch.md) +To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../user-guides/install-and-using-porch.md) tutorial to create the repositories in Porch. You will notice logging messages in VS Code when you run the `kubectl apply -f porch-repositories.yaml` command. diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index 091f10e2..ff329248 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -70,7 +70,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [porchctl](using-porch/porchctl-cli-guide.md) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [porchctl](user-guides/porchctl-cli-guide.md) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle diff --git a/content/en/docs/porch/using-porch/_index.md b/content/en/docs/porch/user-guides/_index.md similarity index 61% rename from content/en/docs/porch/using-porch/_index.md rename to content/en/docs/porch/user-guides/_index.md index 10c4c350..c8a18209 100644 --- a/content/en/docs/porch/using-porch/_index.md +++ b/content/en/docs/porch/user-guides/_index.md @@ -1,5 +1,5 @@ --- -title: "Using Porch" +title: "Porch user guides" type: docs weight: 6 description: diff --git a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md b/content/en/docs/porch/user-guides/adding-external-git-ca-bundle.md similarity index 100% rename from content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md rename to content/en/docs/porch/user-guides/adding-external-git-ca-bundle.md diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/user-guides/install-and-using-porch.md similarity index 100% rename from content/en/docs/porch/using-porch/install-and-using-porch.md rename to content/en/docs/porch/user-guides/install-and-using-porch.md diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md similarity index 85% rename from content/en/docs/porch/using-porch/usage-porch-kpt-cli.md rename to content/en/docs/porch/user-guides/porchctl-cli-guide.md index eff35cf1..8b620077 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -1,22 +1,60 @@ --- -title: "Using Porch with the kpt CLI" +title: "Using the Porch CLI tool" type: docs -weight: 3 +weight: 2 description: --- +## Setting up the porchctl CLI -This document is focused on using Porch via the `kpt` CLI. +When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved into a new command called `porchctl`. -Installation of Porch, including prerequisites, is covered in a [dedicated document](install-and-using-porch.md). +To use it locally, [download](https://github.com/nephio-project/porch/releases/tag/main), unpack and add it to your PATH. -## Prerequisites +{{% alert title="Note" color="primary" %}} + +Installation of Porch, including its prerequisites, is covered in a [dedicated document](install-and-using-porch.md). + +{{% /alert %}} + +*Optional*: Generate the autocompletion script for the specified shell to add to your sh profile. + +``` +porchctl completion bash +``` + +The `porchtcl` command is an administration command for acting on Porch *Repository* (repo) and *PackageRevision* (rpkg) +CRs. + +The commands for administering repositories are: + +| Command | Description | +| --------------------- | ------------------------------ | +| `porchctl repo get` | List registered repositories. | +| `porchctl repo reg` | Register a package repository. | +| `porchctl repo unreg` | Unregister a repository. | -To use Porch, you will need: +The commands for administering package revisions are: -* [`kpt`](https://kpt.dev) -* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) -* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE) +| Command | Description | +| ------------------------------ | --------------------------------------------------------------------------------------- | +| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | +| `porchctl rpkg clone` | Create a clone of an existing package revision. | +| `porchctl rpkg copy` | Create a new package revision from an existing one. | +| `porchctl rpkg del` | Delete a package revision. | +| `porchctl rpkg get` | List package revisions in registered repositories. | +| `porchctl rpkg init` | Initializes a new package in a repository. | +| `porchctl rpkg propose` | Propose that a package revision should be published. | +| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | +| `porchctl rpkg pull` | Pull the content of the package revision. | +| `porchctl rpkg push` | Push resources to a package revision. | +| `porchctl rpkg reject` | Reject a proposal to publish or delete a package revision. | +| `porchctl rpkg update` | Update a downstream package revision to a more recent revision of its upstream package. | + +## Using the porchctl CLI + +### Guide prerequisites +* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) Make sure that your `kubectl` context is set up for `kubectl` to interact with the correct Kubernetes instance (see [installation instructions](install-and-using-porch.md) or the [running-locally](../running-porch/running-locally.md) @@ -56,6 +94,7 @@ package content. The matching resources share the same `name` (as well as API gr {{% /alert %}} + ## Repository Registration To use Porch with a Git repository, you will need: @@ -439,4 +478,4 @@ 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. +proposal was approved is now in _Published_ state. \ No newline at end of file diff --git a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md b/content/en/docs/porch/user-guides/using-authenticated-private-registries.md similarity index 100% rename from content/en/docs/porch/using-porch/using-authenticated-private-registries.md rename to content/en/docs/porch/user-guides/using-authenticated-private-registries.md diff --git a/content/en/docs/porch/using-porch/porchctl-cli-guide.md b/content/en/docs/porch/using-porch/porchctl-cli-guide.md deleted file mode 100644 index b0275b16..00000000 --- a/content/en/docs/porch/using-porch/porchctl-cli-guide.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Using the Porch CLI" -type: docs -weight: 2 -description: ---- - -## Using the porchctl CLI - - -When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved into a new command called `porchctl`. - -To use it locally, [download](https://github.com/nephio-project/porch/releases), unpack and add it to your PATH. - -Optional: Generate the autocompletion script for the specified shell to add to your profile. - -``` -porchctl completion bash -``` - -Check that porchctl is working: - -``` -porchctl --help - -porchctl interacts with a Kubernetes API server with the Porch -server installed as an aggregated API server. It allows you to -manage Porch repository registrations and the packages within -those repositories. - -Usage: - porchctl [flags] - porchctl [command] - -Available Commands: - completion Generate the autocompletion script for the specified shell - help Help about any command - repo Manage package repositories. - rpkg Manage packages. - version Print the version number of porchctl - -Flags: - -h, --help help for porchctl - --log-flush-frequency duration Maximum number of seconds between log flushes (default 5s) - --truncate-output Enable the truncation for output (default true) - -v, --v Level number for the log level verbosity - -Use "porchctl [command] --help" for more information about a command. - -``` - -The `porchtcl` command is an administration command for acting on Porch *Repository* (repo) and *PackageRevision* (rpkg) -CRs. - -The commands for administering repositories are: - -| Command | Description | -| --------------------- | ------------------------------ | -| `porchctl repo get` | List registered repositories. | -| `porchctl repo reg` | Register a package repository. | -| `porchctl repo unreg` | Unregister a repository. | - -The commands for administering package revisions are: - -| Command | Description | -| ------------------------------ | --------------------------------------------------------------------------------------- | -| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | -| `porchctl rpkg clone` | Create a clone of an existing package revision. | -| `porchctl rpkg copy` | Create a new package revision from an existing one. | -| `porchctl rpkg del` | Delete a package revision. | -| `porchctl rpkg get` | List package revisions in registered repositories. | -| `porchctl rpkg init` | Initializes a new package in a repository. | -| `porchctl rpkg propose` | Propose that a package revision should be published. | -| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | -| `porchctl rpkg pull` | Pull the content of the package revision. | -| `porchctl rpkg push` | Push resources to a package revision. | -| `porchctl rpkg reject` | Reject a proposal to publish or delete a package revision. | -| `porchctl rpkg update` | Update a downstream package revision to a more recent revision of its upstream package. | From 508c12f02dab06a313928d25c7984a493b25d27e Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 19:01:53 +0000 Subject: [PATCH 3/3] Add workflow_dispatch trigger to link checker --- .github/workflows/check-links-md.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/check-links-md.yml b/.github/workflows/check-links-md.yml index 644c1506..d1e40606 100644 --- a/.github/workflows/check-links-md.yml +++ b/.github/workflows/check-links-md.yml @@ -1,6 +1,8 @@ name: "Check links of plain md files" -on: + +on: pull_request: + workflow_dispatch: jobs: docs: