Add Porch Book Chapter (#3114)

The chapter has a basic introduction to Package Orchestration
concepts and references the user guides.

porch/docs/porch-roadmap.md

@@ -31,6 +31,10 @@ document outlining future direction and work in different Porch subsystems.
 * Support updating repository registration, for example when `Repository`
   resource is modified to point to a different repository, or even a different
   type of a repository (Git --> OCI).
+* Support read only repositories. Porch will allow package discovery in a read
+  only repository but attempt to create/modify package in read only repository
+  will result in an error. Consider supporting via RBAC so different principals
+  can have different level of access to the same repository.
 * Implement repository cache eviction policy
 * Support `ObjectMeta.GenerateName` for `PackageRevision` creation. Currently
   package names are computed as <repository>-<sha>. Ideally Porch would accept

site/book/08-package-orchestration/00.md

@@ -0,0 +1,62 @@
+In this chapter, we are going to cover _package orchestration_ - management
+of package lifecycle supported by the kpt toolchain.
+
+Package Orchestration encompasses management of the overall lifecycle of the
+configuration package, including:
+
+* management of package repositories
+* discovery of configuration packages and kpt functions
+* creating, modifying, updating, and deleting packages
+* versioning packages
+* WYSIWYG package authoring and customization with _guardrails_
+* evaluation of functions on package data
+* approval flow to publish a change to a configuration package
+* deployment and rollouts
+
+Package Orchestration enables [workflows](/book/02-concepts/02-workflows)
+similar to those supported by the kpt CLI, but makes them available as a
+service and enables creation of WYSIWYG user experiences, similar to the
+proof-of-concept [Backstage plugin](/guides/namespace-provisioning-ui).
+
+## Package Orchestration Concepts
+
+Package Orchestration relies on the already familiar concepts of
+[**Package**](/book/02-concepts/01-packages)
+and [**Function**](/book/02-concepts/03-functions).
+
+Package Orchestrator supports several **lifecycle stages** of packages:
+* ***Draft*** - package is being created or edited. The package contents can be
+  modified but package is not ready to be used (deployed or cloned)
+* ***Proposed*** - author of the package proposed that the package be published
+* ***Published*** - the changes to the package have been approved and the
+  package is ready to be used. Published packages can be deployed or cloned.
+
+A **Repository** containing kpt packages (for example a [git][] repository or
+an [OCI][] container registry) can be registered with the Package Orchestrator
+to enable package discovery or management.
+
+An [OCI][] container registry containing kpt functions can be registered with
+the Package Orchestrator to enable discovery of kpt functions.
+
+A repository containing *packages* can be designated as a
+***deployment repository***. *Published* packages in a deployment repository are
+considered deployment-ready.
+
+<!-- Reference links -->
+[git]: https://git-scm.org/
+[oci]: https://opencontainers.org/
+[config sync]: https://cloud.google.com/anthos-config-management/docs/config-sync-overview
+
+The following image illustrates how Package Orchestration fits into the overall
+configuration management ecosystem. Package Orchestration service enables
+management of packages in registered repositories and enables WYSIWYG UI
+experience of package authoring.
+A separate GitOps deployment mechanism (for example [Config Sync][]) is used to
+deploy published packages to realize the live state from the configuration and
+provides observability of the status of deployed resources.
+
+![Package Orchestration](/static/images/package-orchestration.svg)
+
+Dedicated user guides are available for the use of Porch with
+* the [Backstage UI](/guides/namespace-provisioning-ui)
+* the [kpt cli](/guides/porch-user-guide)

site/book/README.md

@@ -14,6 +14,7 @@ This book is organized as follows:
 - [Chapter 5] guides you through developing custom functions.
 - [Chapter 6] covers how to deploy a package to a Kubernetes cluster.
 - [Chapter 7] covers effective customizations techniques.
+- [Chapter 8] covers package orchestration concepts and support in kpt toolchain.
 
 Let's get started!
 
@@ -24,3 +25,4 @@ Let's get started!
 [chapter 5]: /book/05-developing-functions/
 [chapter 6]: /book/06-deploying-packages/
 [chapter 7]: /book/07-effective-customizations/
+[chapter 8]: /book/08-package-orchestration/

site/guides/namespace-provisioning-cli.md

@@ -329,10 +329,10 @@ Now that we have a basic namespace package in place, let's publish it so that
 other users can consume it.
 
 ```shell
-$cd .. && git add basens && git commit -am "initial pkg"
-$git push origin main
+$ cd .. && git add basens && git commit -am "initial pkg"
+$ git push origin main
 
-$git tag basens/v0 && git push origin basens/v0
+$ git tag basens/v0 && git push origin basens/v0
 ```
 
 So, now the package should be available in the `blueprint` repo. Consumers

site/guides/porch-user-guide.md

@@ -126,7 +126,7 @@ The command `kpt alpha repo unregister` can be used to unregister a repository:
 
 ```sh
 # Unregister a repository
-$ kpt alpha repo unregister deployments
+$ kpt alpha repo unregister deployments --namespace default
 ```
 
 ## Package Discovery And Introspection

site/sidebar.md

@@ -34,6 +34,7 @@
 		- [7.1 Single Value Replacement](book/07-effective-customizations/01-single-value-replacement.md)
 		- [7.2 Limiting Package Changes](book/07-effective-customizations/02-limiting-package-changes.md)
 		- [7.3 Generation](book/07-effective-customizations/03-generation.md)
+	- [8 Package Orchestration](book/08-package-orchestration/)
 - [Reference](reference/)
   - [Annotations](reference/annotations/)
     - [apply-time mutation](reference/annotations/apply-time-mutation/)