You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Cut down amount of config-as-data elaboration in theory.md
- add descriptions to Hugo header elements in each doc
to improve presentation in rendered site
- copy rewrites of old config-as-data content back to
the copies in relevant relevant_old_docs documents
so as not to lose them
- other minor tweaks from offline review comments
Copy file name to clipboardExpand all lines: content/en/docs/neo-porch/2_concepts/_index.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,4 +4,6 @@ type: docs
4
4
weight: 1
5
5
---
6
6
7
-
The Concepts section helps you learn about the abstractions Porch uses to store and orchestrate your kpt packages, with high-level descriptions of the repository management, package orchestration, and package revision lifecycle management use cases.
7
+
The Concepts section helps you learn about the abstractions Porch uses to store and orchestrate your kpt packages, with
8
+
high-level descriptions of the repository management, package orchestration, and package revision lifecycle management
@@ -56,8 +58,8 @@ resources required for basic package authoring and lifeycle management, includin
56
58
*`PackageRevision` - represents the *metadata* of the package revision stored in a repository.
57
59
*`PackageRevisionResources` - represents the *file contents* of the package revision.
58
60
{{% alert color="primary" %}}
59
-
Note that each package revision is represented by a *pair* of resources, each presenting a different view
60
-
(or [representation][differingrepresentations])
61
+
Note that each package revision is represented by both a `PackageRevision` and a `PackageRevisionResources` - each presents
62
+
a different view (or [representation](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#differing-representations))
61
63
of the same underlying package revision.
62
64
{{% /alert %}}
63
65
* A `Repository`[custom resource][crds], which supports repository registration.
@@ -81,12 +83,12 @@ The **Porch server** itself includes the following key components:
81
83
82
84
#### Function Runner
83
85
84
-
The **Function Runner** is a separate microservice responsible for evaluating [KRM functions][functions]. It exposes
85
-
a [GRPC](https://grpc.io/) endpoint which enables evaluating a specified kpt function on a provided configuration package.
86
+
The **Function Runner** is a separate microservice responsible for evaluating [KRM functions][functions]. It exposes a
87
+
[GRPC](https://grpc.io/) endpoint which enables evaluating a specified kpt function on a provided configuration package.
86
88
87
-
GRPC was chosen for the function runner service because the [benefits of an API server](#porch-server) that prompted its use
88
-
for the Porch server do not apply in this case. The function runner is an internal microservice, an implementation detail not exposed
89
-
to external callers, which makes GRPC perfectly suitable.
89
+
GRPC was chosen for the function runner service because the [benefits of an API server](#porch-server) that prompted its
90
+
use for the Porch server do not apply in this case. The function runner is an internal microservice, an implementation
91
+
detail not exposed to external callers, which makes GRPC perfectly suitable.
90
92
91
93
The function runner maintains a cache of functions to support low-latency function evaluation. It achieves this through
92
94
two mechanisms available to it for evaluation of a function:
@@ -102,40 +104,17 @@ two mechanisms available to it for evaluation of a function:
102
104
it can be re-used quickly as a cache hit. After a pre-configured period of disuse (default 30 minutes), the function
103
105
runner terminates the function pod and its service, to recreate them from the start on the next invocation of that function.
104
106
105
-
#### CaD Library
107
+
#### CaD (kpt) Operations
106
108
107
-
The [kpt](https://kpt.dev/) CLI already implements the fundamental package manipulation algorithms in order to provide its command line user experience:
108
-
109
-
*[kpt pkg init](https://kpt.dev/reference/cli/pkg/init/) - create a bare-bones, valid, kpt package.
110
-
*[kpt pkg get](https://kpt.dev/reference/cli/pkg/get/) - create a downstream package by cloning an upstream package;
111
-
set up the upstream reference of the downstream package.
112
-
*[kpt pkg update](https://kpt.dev/reference/cli/pkg/update/) - update the downstream package with changes from new
113
-
version of upstream, 3-way merge.
114
-
*[kpt fn eval](https://kpt.dev/reference/cli/fn/eval/) - evaluate a KRM function on a package.
115
-
*[kpt fn render](https://kpt.dev/reference/cli/fn/render/) - render the package by executing the function pipeline of
116
-
the package and its nested packages.
117
-
*[kpt fn source](https://kpt.dev/reference/cli/fn/source/) and [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/) -
118
-
read package from local disk as a `ResourceList` and write package represented as `ResourcesList` into local disk.
109
+
The [kpt](https://kpt.dev/) CLI already implements the fundamental package manipulation algorithms (explained
110
+
[in kpt documentation](https://kpt.dev/book/03-packages/)) in order to provide its command line user experience.
119
111
120
112
The same set of primitive operations form the foundational building blocks of the package orchestration service. Further,
121
113
Porch combines these blocks into higher-level operations (for example, Porch renders packages automatically on changes;
122
114
future versions will support bulk operations such as upgrade of multiple packages, etc.).
123
115
124
-
A longer-term goal is to refactor kpt and Porch to extract the package manipulation operations into a reusable CaD Library, which will consumed by both the kpt CLI and Porch to allow them equal reuse of the same operations:
125
-
* create a valid empty package (init).
126
-
* clone a package and add upstream pointers (get).
127
-
* perform 3-way merge (upgrade).
128
-
* render - core package rendering algorithm using a pluggable function evaluator to support:
129
-
* function evaluation via Docker (as used by kpt CLI).
130
-
* function evaluation via an RPC to a service or appropriate function sandbox.
131
-
* high-performance evaluation of trusted, built-in, functions without sandbox.
132
-
* heal configuration (restore comments after lossy transformation).
133
-
134
-
This approach will allow leveraging the investment already made into the high-quality package manipulation operations, maintain functional parity between the kpt CLI and Porch, and allow dependencies to be abstracted away which differ between CLI and Porch (most notably the dependency on Docker for function evaluation and on the local file system for package rendering).
0 commit comments