Adding Porch documentation to the docs.nephio.org (#144)

This pr adds the markdown documentation of Porch to docs.nephio.org . 
Open issues are collected in
[here](nephio-project/nephio#744 (comment)).

Fixes nephio-project/nephio#744

---------

Signed-off-by: Gergely Csatari <[email protected]>
Signed-off-by: Schweier Dominika <[email protected]>
Co-authored-by: Liam Fallon <[email protected]>
Co-authored-by: Schweier Dominika <[email protected]>

.linkspector.yml

@@ -10,6 +10,7 @@ aliveStatusCodes:
 ignorePatterns:
   - pattern: "^http://localhost.*$"
   - pattern: "^http://HOSTNAME:PORT.*$"
+  - pattern: "172\\.18\\.255\\.200"
 replacementPatterns:
   - pattern: ".md#.*$"
     replacement: ".md"

content/en/docs/porch/_index.md

@@ -0,0 +1,24 @@
+---
+title: "Porch documentation"
+type: docs
+weight: 6
+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.
+
+Short for Package Orchestration.
+
+## Porch in the Nephio architecture, history and outlook
+
+Porch is a key component of the Nephio architecture and was originally developed in the
+[kpt](https://github.com/kptdev/kpt) project. When kpt was donated to the [CNCF](https://www.cncf.io/projects/kpt/) it
+was decided that Porch would not be part of the kpt project and the code was donated to Nephio.
+
+Porch is now mainteined by the Nephio community and it is a stable part of the Nephio R3 architecture. However there is
+an active disucssion about the future of the project. It is possible that the current Porch component will be replaced in the Nephio
+architecture with a different codebase implementing the same concepts but not in a backward compatible way. Potential
+candidates such as [pkgserver](https://docs.pkgserver.dev/) are being discussed in the Nephio community. 

content/en/docs/porch/config-as-data.md

@@ -0,0 +1,158 @@
+---
+title: "Configuration as Data"
+type: docs
+weight: 1
+description: 
+---
+
+## Why
+
+This document provides background context for Package Orchestration, which is further elaborated in a dedicated
+[document](package-orchestration.md).
+
+## Configuration as Data
+
+*Configuration as Data* is an approach to management of configuration (incl.
+configuration of infrastructure, policy, services, applications, etc.) which:
+
+* makes configuration data the source of truth, stored separately from the live
+  state
+* uses a uniform, serializable data model to represent configuration
+* separates code that acts on the configuration from the data and from packages
+  / bundles of the data
+* abstracts configuration file structure and storage from operations that act
+  upon the configuration data; clients manipulating configuration data don’t
+  need to directly interact with storage (git, container images)
+
+![CaD Overview](/static/images/porch/CaD-Overview.svg)
+
+## Key Principles
+
+A system based on CaD *should* observe the following key principles:
+
+* secrets should be stored separately, in a secret-focused storage system
+  ([example](https://cloud.google.com/secret-manager))
+* stores a versioned history of configuration changes by change sets to bundles
+  of related configuration data
+* relies on uniformity and consistency of the configuration format, including
+  type metadata, to enable pattern-based operations on the configuration data,
+  along the lines of duck typing
+* separates schemas for the configuration data from the data, and relies on
+  schema information for strongly typed operations and to disambiguate data
+  structures and other variations within the model
+* decouples abstractions of configuration from collections of configuration data
+* represents abstractions of configuration generators as data with schemas, like
+  other configuration data
+* finds, filters / queries / selects, and/or validates configuration data that
+  can be operated on by given code (functions)
+* finds and/or filters / queries / selects code (functions) that can operate on
+  resource types contained within a body of configuration data
+* *actuation* (reconciliation of configuration data with live state) is separate
+  from transformation of configuration data, and is driven by the declarative
+  data model
+* transformations, particularly value propagation, are preferable to wholesale
+  configuration generation except when the expansion is dramatic (say, >10x)
+* transformation input generation should usually be decoupled from propagation
+* deployment context inputs should be taken from well defined “provider context”
+  objects
+* identifiers and references should be declarative
+* live state should be linked back to sources of truth (configuration)
+
+## KRM CaD
+
+Our implementation of the Configuration as Data approach (
+[kpt](https://kpt.dev),
+[Config Sync](https://cloud.google.com/anthos-config-management/docs/config-sync-overview),
+and [Package Orchestration](https://github.com/nephio-project/porch))
+build on the foundation of
+[Kubernetes Resource Model](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md)
+(KRM).
+
+{{% alert title="Note" color="primary" %}}
+
+Even though KRM is not a requirement of Config as Data (just like
+Python or Go templates or Jinja are not specifically requirements for
+[IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)), the choice of
+another foundational config representation format would necessitate
+implementing adapters for all types of infrastructure and applications
+configured, including Kubernetes, CRDs, GCP resources and more. Likewise, choice
+of another configuration format would require redesign of a number of the
+configuration management mechanisms that have already been designed for KRM,
+such as 3-way merge, structural merge patch, schema descriptions, resource
+metadata, references, status conventions, etc.
+
+{{% /alert %}}
+
+
+**KRM CaD** is therefore a specific approach to implementing *Configuration as Data* which:
+
+* uses [KRM](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md)
+  as the configuration serialization data model
+* uses [Kptfile](https://kpt.dev/reference/schema/kptfile/) to store package metadata
+* uses [ResourceList](https://kpt.dev/reference/schema/resource-list/) as a serialized package wire-format
+* uses a function `ResourceList → ResultList` (`kpt` function) as the foundational, composable unit of
+  package-manipulation code (note that other forms of code can manipulate packages as well, i.e. UIs, custom algorithms
+  not necessarily packaged and used as kpt functions)
+
+and provides the following basic functionality:
+
+* load a serialized package from a repository (as `ResourceList`) (examples of repository may be one or more of: local
+  HDD, Git repository, OCI, Cloud Storage, etc.)
+* save a serialized package (as `ResourceList`) to a package repository
+* evaluate a function on a serialized package (`ResourceList`)
+* [render](https://kpt.dev/book/04-using-functions/01-declarative-function-execution) a package (evaluate functions
+  declared within the package itself)
+* create a new (empty) package
+* fork (or clone) an existing package from one package repository (called upstream) to another (called downstream)
+* delete a package from a repository
+* associate a version with the package; guarantee immutability of packages with an assigned version
+* incorporate changes from the new version of an upstream package into a new version of a downstream package
+* revert to a prior version of a package
+
+## Value
+
+The Config as Data approach enables some key value which is available in other
+configuration management approaches to a lesser extent or is not available
+at all.
+
+*CaD* approach enables:
+
+* simplified authoring of configuration using a variety of methods and sources
+* WYSIWYG interaction with configuration using a simple data serialization formation rather than a code-like format
+* layering of interoperable interface surfaces (notably GUI) over declarative configuration mechanisms rather than
+  forcing choices between exclusive alternatives (exclusively UI/CLI or IaC initially followed by exclusively
+  UI/CLI or exclusively IaC)
+* the ability to apply UX techniques to simplify configuration authoring and viewing
+* compared to imperative tools (e.g., UI, CLI) that directly modify the live state via APIs, CaD enables versioning,
+  undo, audits of configuration history, review/approval, pre-deployment preview, validation, safety checks,
+  constraint-based policy enforcement, and disaster recovery
+* bulk changes to configuration data in their sources of truth
+* injection of configuration to address horizontal concerns
+* merging of multiple sources of truth
+* state export to reusable blueprints without manual templatization
+* cooperative editing of configuration by humans and automation, such as for security remediation (which is usually
+  implemented against live-state APIs)
+* reusability of configuration transformation code across multiple bodies of configuration data containing the same
+  resource types, amortizing the effort of writing, testing, documenting the code
+* combination of independent configuration transformations
+* implementation of config transformations using the languages of choice, including both programming and scripting
+  approaches
+* reducing the frequency of changes to existing transformation code
+* separation of roles between developer and non-developer configuration users
+* defragmenting the configuration transformation ecosystem
+* admission control and invariant enforcement on sources of truth
+* maintaining variants of configuration blueprints without one-size-fits-all full struct-constructor-style
+  parameterization and without manually constructing and maintaining patches
+* drift detection and remediation for most of the desired state via continuous reconciliation using apply and/or for
+  specific attributes via targeted mutation of the sources of truth
+
+## Related Articles
+
+For more information about Configuration as Data and Kubernetes Resource Model,
+visit the following links:
+
+* [Rationale for kpt](https://kpt.dev/guides/rationale)
+* [Understanding Configuration as Data](https://cloud.google.com/blog/products/containers-kubernetes/understanding-configuration-as-data-in-kubernetes)
+  blog post.
+* [Kubernetes Resource Model](https://cloud.google.com/blog/topics/developers-practitioners/build-platform-krm-part-1-whats-platform)
+  blog post series

content/en/docs/porch/contribturos-guide/_index.md

@@ -0,0 +1,113 @@
+---
+title: "Porch Contributor Guide"
+type: docs
+weight: 7
+description:
+---
+
+## Changing Porch API
+
+If you change the API resources, in `api/porch/.../*.go`, update the generated code by running:
+
+```sh
+make generate
+```
+
+## Components
+
+Porch comprises of several software components:
+
+* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch extension apiserver
+* [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of Porch `Repository` and `PackageRevision` custom resources.
+* [apiserver](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST handlers, Porch `main` function
+* [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - operations on package contents
+* [func](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API
+* [repository](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package
+* [git](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository.
+* [oci](https://github.com/nephio-project/porch/tree/main/pkg/oci): Integration with OCI repository.
+* [cache](https://github.com/nephio-project/porch/tree/main/pkg/cache): Package caching.
+* [controllers](https://github.com/nephio-project/porch/tree/main/controllers): `Repository` CRD. No controller;
+  Porch apiserver watches these resources for changes as repositories are (un-)registered.
+* [test](https://github.com/nephio-project/porch/tree/main/test): Test Git Server for Porch e2e testing, and
+  [e2e](https://github.com/nephio-project/porch/tree/main/test/e2e) tests.
+
+## Running Porch
+
+See dedicated documentation on running Porch:
+
+* [locally](../running-porch/running-locally.md)
+* [on GKE](../running-porch/running-on-GKE.md)
+
+## Build the Container Images
+
+Build Docker images of Porch components:
+
+```sh
+# Build Images
+make build-images
+
+# Push Images to Docker Registry
+make push-images
+
+# Supported make variables:
+# IMAGE_TAG      - image tag, i.e. 'latest' (defaults to 'latest')
+# GCP_PROJECT_ID - GCP project hosting gcr.io repository (will translate to gcr.io/${GCP_PROJECT_ID})
+# IMAGE_REPO     - overwrites the default image repository
+
+# Example:
+IMAGE_TAG=$(git rev-parse --short HEAD) make push-images
+```
+
+## Running Locally
+
+Follow the [Running Porch Locally](../running-porch/running-locally.md) guide to run Porch locally.
+
+## Debugging
+
+To debug Porch, run Porch locally [running-locally.md](../running-porch/running-locally.md), exit porch server running
+in the shell, and launch Porch under the debugger. VSCode debug session is pre-configured in
+[launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json).
+
+Update the launch arguments to your needs.
+
+## Code Pointers
+
+Some useful code pointers:
+
+* Porch REST API handlers in [registry/porch](https://github.com/nephio-project/porch/tree/main/pkg/registry/porch),
+  for example [packagerevision.go](https://github.com/nephio-project/porch/tree/main/pkg/registry/porch/packagerevision.go)
+* Background task handling cache updates in [background.go](https://github.com/nephio-project/porch/tree/main/pkg/registry/porch/background.go)
+* Git repository integration in [pkg/git](https://github.com/nephio-project/porch/tree/main/pkg/git)
+* OCI repository integration in [pkg/oci](https://github.com/nephio-project/porch/tree/main/pkg/oci)
+* CaD Engine in [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine)
+* e2e tests in [e2e](https://github.com/nephio-project/porch/tree/main/test/e2e). See below more on testing.
+
+## Running Tests
+
+All tests can be run using `make test`. Individual tests can be run using `go test`.
+End-to-End tests assume that Porch instance is running and `KUBECONFIG` is configured
+with the instance. The tests will automatically detect whether they are running against
+Porch running on local machien or k8s cluster and will start Git server appropriately,
+then run test suite against the Porch instance.
+
+## Makefile Targets
+
+* `make generate`: generate code based on Porch API definitions (runs k8s code generators)
+* `make tidy`: tidies all Porch modules
+* `make fmt`: formats golang sources
+* `make build-images`: builds Porch Docker images
+* `make push-images`: builds and pushes Porch Docker images
+* `make deployment-config`: customizes configuration which installs Porch
+   in k8s cluster with correct image names, annotations, service accounts.
+   The deployment-ready configuration is copied into `./.build/deploy`
+* `make deploy`: deploys Porch in the k8s cluster configured with current kubectl context
+* `make push-and-deploy`: builds, pushes Porch Docker images, creates deployment configuration, and deploys Porch
+* `make` or `make all`: builds and runs Porch [locally](../running-porch/running-locally.md)
+* `make test`: runs tests
+
+## VSCode
+
+[VSCode](https://code.visualstudio.com/) works really well for editing and debugging.
+Because Porch is comprises of multiple go modules, there is a pre-configured
+multi-folder workspace in [porch.code-workspace](https://github.com/nephio-project/porch/blob/main/porch.code-workspace).
+Open it in VSCode (File / Open Workspace from File) to use Workspace Folders.