Refactor porch cli and user guides

nephio-project · Dec 9, 2024 · f1fd5f4 · f1fd5f4
1 parent 56e2cad
commit f1fd5f4
Show file tree

Hide file tree

Showing 12 changed files with 58 additions and 97 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 → content/en/docs/porch/user-guides/_index.md b/content/en/docs/porch/using-porch/_index.md → 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/...ng-porch/adding-external-git-ca-bundle.md → ...r-guides/adding-external-git-ca-bundle.md b/...ng-porch/adding-external-git-ca-bundle.md → ...r-guides/adding-external-git-ca-bundle.md
diff --git a/...ch/using-porch/install-and-using-porch.md → ...ch/user-guides/install-and-using-porch.md b/...ch/using-porch/install-and-using-porch.md → ...ch/user-guides/install-and-using-porch.md
diff --git a/.../porch/using-porch/usage-porch-kpt-cli.md → ...s/porch/user-guides/porchctl-cli-guide.md b/.../porch/using-porch/usage-porch-kpt-cli.md → ...s/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.
diff --git a/...using-authenticated-private-registries.md → ...using-authenticated-private-registries.md b/...using-authenticated-private-registries.md → ...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