From f1fd5f4c705a8fe5fd986fc83a1463b56d695030 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 18:36:44 +0000 Subject: [PATCH] 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. |