docs: Update the kpt book with more details about namespaces and RBAC…

… for porch (#3692)

site/book/08-package-orchestration/03-registering-a-repository.md

@@ -8,6 +8,11 @@ using Porch. You will need:
   the `repo` scope for Porch to authenticate with the repository and allow it
   to create commits in the repository.
 
+A repository is a porch representation of either a git repo or an oci registry.
+Package revisions always belong to a single repository. A repository exists in
+a Kubernetes namespace and all package revisions in a repo also belong to
+the same namespace.
+
 Use the `kpt alpha repo register` command to register your repository with
 Porch: The command below uses the repository `deployments.git`.
 Your repository name may be different; please update the command with the

site/book/08-package-orchestration/04-package-authoring.md

@@ -109,6 +109,13 @@ You can find out more about the `upstream` and `upstreamLock` sections of the
 `Kptfile` in an [earlier chapter](/book/03-packages/01-getting-a-package)
 of the book.
 
+> A cloned package must be created in a repository in the same namespace as
+> the source package. Cloning a package with the Package Orchestration Service
+> retains a reference to the upstream package revision in the clone, and
+> cross-namespace references are not allowed. Package revisions in repositories
+> in other namespaces can be cloned using a reference directly to the underlying
+> oci or git repository as described below.
+
 You can also clone a package from a repository that is _not_ registered with
 Porch, for example:
 

site/book/08-package-orchestration/05-package-lifecycle.md

@@ -66,6 +66,10 @@ deployments-8baf4892d6bdeda0f26ef4b1088fddb85c5a2486 rejected
 ?> Refer to the [approve][rpkg-approve] and [reject][rpkg-reject] command
 reference for usage.
 
+> Approving a package revisions requires that the current user has been granted
+> update access to the `approve` subresource of `packagerevisions`. This allows
+> for giving only a limited set of users permission to approve package revisions.
+
 Now, confirm lifecycle stages of the package revisions:
 
 ```sh