Repository navigation
docs: Add a 10,000 m view of kpt and Porch - #4815
Open
SurbhiAgarwal1 wants to merge 1 commit into
Open
SurbhiAgarwal1 wants to merge 1 commit into
SurbhiAgarwal1 wants to merge 1 commit into
Conversation
SurbhiAgarwal1
requested review from
a team
and
a balanced review from Copilot
October 18, 2026 08:50
SurbhiAgarwal1
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
October 18, 2026 08:50
✅ Deploy Preview for kptdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
SurbhiAgarwal1
force-pushed
the
docs/4806-10000m-view-kpt-and-porch
branch
from
October 18, 2026 09:48
e6858db to
8c01e05
Compare
| configuration easy to create and transform, via reusable functions. Because they are expected to be used for in-place | ||
| transformation, the functions need to be idempotent. | ||
|
|
||
| - [**Porch (Package Orchestration)**](https://docs.porch.nephio.org/): A Kubernetes-native control plane ("kpt-as-a-service") that exposes package operations as declarative Kubernetes resources (`PackageRevision`). Porch automates package cloning, server-side function evaluation, GitOps synchronization, and multi-stage lifecycle governance (`Draft` ➔ `Proposed` ➔ `Published`) across enterprise fleets. |
| * **Declarative and Uniform**: Configuration is represented purely as data conforming to the [Kubernetes Resource Model (KRM)](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md), stored directly as serializable YAML/JSON. | ||
| * **Separation of Code and Data**: Instead of embedding programming logic or template directives inside configuration files (such as `{{ if .Values.enabled }}`), configuration files remain clean KRM data. | ||
| * **In-Place Transformation via KRM Functions**: Specialized, containerized programs (KRM functions) read KRM resources from an input stream, mutate or validate them, and output the updated resources in-place. | ||
| * **Git as the Single Source of Truth**: All configurations are versioned, audited, and stored in standard Git repositories, making operations fully inspectable and reproducible. |
| ### 2. Fleet Orchestration (Porch) | ||
| When a development team needs a database instance in their development, staging, or production cluster: | ||
| 1. Porch clones the blueprint from the catalog repository into the team's deployment repository as a `Draft` revision. | ||
| 2. Porch automatically runs specialized mutator functions to inject site-specific configuration (such as namespace, storage classes, network policies, or credentials). |
Add a comprehensive architectural guide providing a high-level (10,000 m) overview of kpt and Porch within the Configuration as Data (CaD) paradigm. - Add guides/10000-m-view.md covering the core CaD principles, client-side kpt CLI capabilities, server-side Porch control plane architecture, Mermaid interaction and lifecycle state diagrams, comparison table, and end-to-end multi-cluster workflows. - Update guides/_index.md to link to the new guide. - Update book/02-concepts/_index.md to introduce Porch under toolchain components and reference the 10,000 m view guide. Closes kptdev#4806 Part of kptdev#4711 Signed-off-by: SurbhiAgarwal <agarwalsurbhi1807@gmail.com>
SurbhiAgarwal1
force-pushed
the
docs/4806-10000m-view-kpt-and-porch
branch
from
October 18, 2026 19:37
8c01e05 to
226c271
Compare
Contributor
Author
|
Hi @efiacor , I have addressed all three suggestions in the latest commit:
All checks are passing and the commit signature is verified. Ready for review! |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds a comprehensive 10,000-meter architectural guide for kpt and Porch to the documentation as requested in #4806.
documentation/content/en/guides/10000-m-view.mddetailing:Draft➔Proposed➔Published).documentation/content/en/guides/_index.mdwith a reference link to the guide.documentation/content/en/book/02-concepts/_index.mdto introduce Porch under toolchain components and reference the 10,000 m view guide.Motivation
While kpt documentation covers the CLI and KRM functions in depth, the relationship between kpt (client-side) and Porch (server-side package orchestration) was not clearly documented at a high level. This 10,000 m view helps users, platform architects, and contributors understand how kpt and Porch fit together across the entire package lifecycle.
Testing
misspell(make verifyindocumentation/).relref) and Mermaid diagram syntax.Closes #4806
Part of #4711