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
Copy file name to clipboardExpand all lines: docs/content/en/docs/2_concepts/functions.md
+64-3Lines changed: 64 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ description: |
9
9
## What are Functions in Porch?
10
10
11
11
**Functions** in Porch are [KRM (Kubernetes Resource Model) functions](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md) -
12
-
containerized programs that transform or validate Kubernetes resource manifests within a package's files. Functions are
12
+
programs (usually containerized) that transform or validate Kubernetes resource manifests within a package's files. Functions are
13
13
declared in a package's Kptfile and executed by Porch when rendering the package.
14
14
15
15
Functions enable:
@@ -20,9 +20,68 @@ Functions enable:
20
20
21
21
For details on how to declare and configure functions in the Kptfile pipeline, see the [kpt functions documentation](https://kpt.dev/book/04-using-functions/).
22
22
23
+
## Function Configuration
24
+
25
+
Porch uses **FunctionConfig** custom resources to configure how functions execute. These configurations specify which executor type should handle specific function images and provide executor-specific settings.
26
+
27
+
Each FunctionConfig specifies:
28
+
-**Image and prefixes**: The function image name and optional registry prefixes
29
+
-**Executor configurations**: One or more executor types (pod, binary, or go) with associated settings
30
+
-**Version-specific settings**: Different executors and configurations for different image tags
31
+
32
+
Example FunctionConfig:
33
+
34
+
```yaml
35
+
apiVersion: config.porch.kpt.dev/v1alpha1
36
+
kind: FunctionConfig
37
+
metadata:
38
+
name: set-namespace
39
+
namespace: porch-fn-system
40
+
spec:
41
+
image: set-namespace
42
+
prefixes:
43
+
- ""
44
+
- ghcr.io/kptdev/krm-functions-catalog
45
+
podExecutor:
46
+
tags:
47
+
- v0.4.1
48
+
timeToLive: 30m
49
+
binaryExecutor:
50
+
tags:
51
+
- v0.4.2
52
+
path: set-namespace
53
+
goExecutor:
54
+
id: set-namespace
55
+
tags:
56
+
- v0.4
57
+
- v0.4.5
58
+
```
59
+
60
+
Both the function-runner and porch-server components include an embedded FunctionConfig reconciler that watches FunctionConfig resources and populates an internal cache. This cache determines which executor to use for each function invocation.
61
+
23
62
## Function Execution in Porch
24
63
25
-
Porch executes functions through a **function runner** component that calls kpt to orchestrate containerized function execution. The functions run in isolated containers (Kubernetes pods managed by the `function-runner` microservice). Porch passes the package's resources to kpt, which passes the resources on as a [ResourceList](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md#resourcelist) to each function in the pipeline in turn. kpt executes the functions sequentially in the order declared in the Kptfile pipeline and passes the function results back to Porch, which stores them in the PackageRevisionResources's `status.renderStatus` field. Execution is triggered automatically following creation or clone of a package revision, update of a package revision, and when a package revision is proposed.
64
+
Porch executes functions using multiple executor types, determined by FunctionConfig settings.
65
+
66
+
**Pod Executor**: Runs functions in isolated containerized pods (the traditional approach):
67
+
- Functions execute in Kubernetes pods managed by the `function-runner` microservice
68
+
- Configurable with pod templates, resource limits, TTL settings, and maximum parallel executions
69
+
- Suitable for functions requiring container isolation or external dependencies
70
+
71
+
**Binary Executor**: Substitutes specific function image tags with local binary executables:
72
+
- Executes pre-built function binaries directly on the host system
73
+
- Provides improved performance by avoiding container overhead
74
+
- Configured with the file path to the function binary
75
+
76
+
**Go Executor**: Executes certain functions as native Go function calls within the porch-server process:
77
+
- Functions run in-process for maximum efficiency
78
+
- Only available for functions integrated as Go libraries
79
+
- No container or process overhead
80
+
81
+
Regardless of executor type, Porch passes the package's resources to kpt, which passes the resources on as a [ResourceList](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md#resourcelist) to each function in the pipeline in turn.
82
+
kpt executes the functions sequentially in the order declared in the Kptfile pipeline and passes the function results back to Porch, which stores them in the PackageRevisionResources's `status.renderStatus` field.
83
+
Execution is triggered automatically following creation or clone of a package revision, update of a package revision, and when a package revision is proposed.
84
+
kpt passes the function results back to Porch and Porch stores them in the PackageRevisionResources's `status.renderStatus` field.
26
85
27
86
## When Functions Execute
28
87
@@ -77,7 +136,9 @@ enabling iterative development on incomplete packages.
77
136
## Key Points
78
137
79
138
- Functions are standard KRM functions declared in the Kptfile pipeline (see [kpt functions docs](https://kpt.dev/book/04-using-functions/))
80
-
- Porch invokes kpt to execute functions via a function-runner component using containerized execution
139
+
- Function execution behavior is configured using FunctionConfig custom resources that specify executor types (pod, binary, or go)
140
+
- Both function-runner and porch-server include FunctionConfig reconcilers that populate internal caches to determine which executor handles each function
141
+
- Functions can execute via pod containers, local binaries, or in-process Go calls depending on configuration
81
142
- Functions automatically execute during package rendering on Draft package revisions
82
143
- Function results are stored in `status.renderStatus` of the PackageRevisionResources view of a package revision
83
144
- Published packages are immutable - functions don't re-execute after publication
Verify that FunctionConfig resources are deployed:
87
+
88
+
```bash
89
+
kubectl get functionconfigs -n porch-fn-system
90
+
```
91
+
92
+
You should see several pre-configured FunctionConfig resources for common KRM functions:
93
+
94
+
```bash
95
+
NAME SERVER APPLIED FNRUNNER APPLIED
96
+
apply-replacements 1 1
97
+
apply-setters 1 1
98
+
create-setters 1 1
99
+
ensure-name-substring 1 1
100
+
gatekeeper 1 1
101
+
kubeconform 1 1
102
+
search-replace 1 1
103
+
set-annotations 1 1
104
+
set-enforcement-action 1 1
105
+
set-image 1 1
106
+
set-labels 1 1
107
+
set-namespace 1 1
108
+
starlark 1 1
109
+
upsert-resource 1 1
110
+
enable-gcp-services 1 1
111
+
export-terraform 1 1
112
+
generate-folders 1 1
113
+
remove-local-config-resources 1 1
114
+
set-project-id 1 1
115
+
```
116
+
117
+
**About these new resources:**
118
+
119
+
-**FunctionConfig**: Defines how KRM functions are executed (pod, binary, or go executors) and replaces the older ConfigMap-based configuration approach. The function-runner and porch-server both include embedded FunctionConfig reconcilers that populate an internal cache used to determine which executor to use and with what configuration.
120
+
121
+
-**ServiceTemplate**: Defines pod and service templates for pod-based function execution. These templates are referenced by FunctionConfig resources that use the pod executor.
For detailed architecture and process flows, see [Function Evaluation]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md" %}}).
24
24
25
+
### Function Configuration Management
26
+
27
+
Provides declarative configuration of function executors through Kubernetes CRDs:
-**Executor Selection Cache**: Maps function images to executor types and configuration settings
30
+
-**Pod Executor Configuration**: Template overrides, TTL settings, and maximum parallel executions per function
31
+
-**Binary Executor Configuration**: Path mapping for substituting container images with local executables
32
+
-**Go Executor Configuration**: Function ID registration for native go function execution
33
+
-**Image Prefix Matching**: Supports multiple image prefixes and tags per function configuration
34
+
-**Template Customization**: Per-function pod and service template overrides including security context, resources, and environment variables
35
+
36
+
For detailed configuration examples, see [Function Runner Configuration]({{% relref "/docs/5_architecture_and_components/function-runner/function-runner-config.md" %}}). For integration with executor selection, see [Function Runner Interactions]({{% relref "/docs/5_architecture_and_components/function-runner/interactions.md" %}}).
37
+
25
38
### Pod Lifecycle Management
26
39
27
40
Manages function execution pods with caching and garbage collection:
@@ -32,6 +45,7 @@ Manages function execution pods with caching and garbage collection:
32
45
-**TTL-Based Caching**: Reuses pods with configurable expiration and extension on use
33
46
-**Garbage Collection**: Periodic cleanup of expired pods and failed pod handling
34
47
-**Pod Warming**: Pre-creates pods for frequently-used functions
48
+
-**Template Overrides**: Applies FunctionConfig-specified customizations to pod and service templates
35
49
36
50
For detailed architecture and process flows, see [Pod Lifecycle Management]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md" %}}).
37
51
@@ -52,7 +66,20 @@ For detailed architecture and process flows, see [Image and Registry Management]
0 commit comments