From aa069784c12492eb5fbb1e201e00ff32300bcd53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B3zes=20L=C3=A1szl=C3=B3=20M=C3=A1t=C3=A9?= Date: Fri, 8 May 2026 14:00:35 +0200 Subject: [PATCH 1/3] copy suggestions from Dosu with some changes Co-authored-by: dosubot --- docs/content/en/docs/2_concepts/functions.md | 67 ++++- .../3_getting_started/installing-porch.md | 39 +++ .../function-runner/functionality/_index.md | 56 +++- .../functionality/function-evaluation.md | 250 ++++++++++++++++-- .../functionality/pod-lifecycle-management.md | 68 ++++- .../function-runner/interactions.md | 232 +++++++++++++--- .../function-runner-config/_index.md | 250 +++++++++++++++++- .../deployments/catalog-deployment.md | 50 ++++ 8 files changed, 928 insertions(+), 84 deletions(-) diff --git a/docs/content/en/docs/2_concepts/functions.md b/docs/content/en/docs/2_concepts/functions.md index b14dd89bd..30efc9a01 100644 --- a/docs/content/en/docs/2_concepts/functions.md +++ b/docs/content/en/docs/2_concepts/functions.md @@ -9,7 +9,7 @@ description: | ## What are Functions in Porch? **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) - -containerized programs that transform or validate Kubernetes resource manifests within a package's files. Functions are +programs (usually containerized) that transform or validate Kubernetes resource manifests within a package's files. Functions are declared in a package's Kptfile and executed by Porch when rendering the package. Functions enable: @@ -20,9 +20,68 @@ Functions enable: 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/). +## Function Configuration + +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. + +Each FunctionConfig specifies: +- **Image and prefixes**: The function image name and optional registry prefixes +- **Executor configurations**: One or more executor types (pod, binary, or go) with associated settings +- **Version-specific settings**: Different executors and configurations for different image tags + +Example FunctionConfig: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: set-namespace + namespace: porch-fn-system +spec: + image: set-namespace + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.4.1 + timeToLive: 30m + binaryExecutor: + tags: + - v0.4.2 + path: set-namespace + goExecutor: + id: set-namespace + tags: + - v0.4 + - v0.4.5 +``` + +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. + ## Function Execution in Porch -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. +Porch executes functions using multiple executor types, determined by FunctionConfig settings. + +**Pod Executor**: Runs functions in isolated containerized pods (the traditional approach): +- Functions execute in Kubernetes pods managed by the `function-runner` microservice +- Configurable with pod templates, resource limits, TTL settings, and maximum parallel executions +- Suitable for functions requiring container isolation or external dependencies + +**Binary Executor**: Substitutes specific function image tags with local binary executables: +- Executes pre-built function binaries directly on the host system +- Provides improved performance by avoiding container overhead +- Configured with the file path to the function binary + +**Go Executor**: Executes certain functions as native Go function calls within the porch-server process: +- Functions run in-process for maximum efficiency +- Only available for functions integrated as Go libraries +- No container or process overhead + +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. +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. +kpt passes the function results back to Porch and Porch stores them in the PackageRevisionResources's `status.renderStatus` field. ## When Functions Execute @@ -77,7 +136,9 @@ enabling iterative development on incomplete packages. ## Key Points - Functions are standard KRM functions declared in the Kptfile pipeline (see [kpt functions docs](https://kpt.dev/book/04-using-functions/)) -- Porch invokes kpt to execute functions via a function-runner component using containerized execution +- Function execution behavior is configured using FunctionConfig custom resources that specify executor types (pod, binary, or go) +- Both function-runner and porch-server include FunctionConfig reconcilers that populate internal caches to determine which executor handles each function +- Functions can execute via pod containers, local binaries, or in-process Go calls depending on configuration - Functions automatically execute during package rendering on Draft package revisions - Function results are stored in `status.renderStatus` of the PackageRevisionResources view of a package revision - Published packages are immutable - functions don't re-execute after publication diff --git a/docs/content/en/docs/3_getting_started/installing-porch.md b/docs/content/en/docs/3_getting_started/installing-porch.md index 53d1597aa..2bb85b6b2 100644 --- a/docs/content/en/docs/3_getting_started/installing-porch.md +++ b/docs/content/en/docs/3_getting_started/installing-porch.md @@ -72,15 +72,54 @@ kubectl api-resources | grep porch You should see Porch API resources: ```bash +functionconfigs config.porch.kpt.dev/v1alpha1 true FunctionConfig packagerevs config.porch.kpt.dev/v1alpha1 true PackageRev packagevariants config.porch.kpt.dev/v1alpha1 true PackageVariant packagevariantsets config.porch.kpt.dev/v1alpha2 true PackageVariantSet repositories config.porch.kpt.dev/v1alpha1 true Repository +servicetemplates config.porch.kpt.dev/v1alpha1 true ServiceTemplate packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision packages porch.kpt.dev/v1alpha1 true PorchPackage ``` +Verify that FunctionConfig resources are deployed: + +```bash +kubectl get functionconfigs -n porch-fn-system +``` + +You should see several pre-configured FunctionConfig resources for common KRM functions: + +```bash +NAME SERVER APPLIED FNRUNNER APPLIED +apply-replacements 1 1 +apply-setters 1 1 +create-setters 1 1 +ensure-name-substring 1 1 +gatekeeper 1 1 +kubeconform 1 1 +search-replace 1 1 +set-annotations 1 1 +set-enforcement-action 1 1 +set-image 1 1 +set-labels 1 1 +set-namespace 1 1 +starlark 1 1 +upsert-resource 1 1 +enable-gcp-services 1 1 +export-terraform 1 1 +generate-folders 1 1 +remove-local-config-resources 1 1 +set-project-id 1 1 +``` + +**About these new resources:** + +- **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. + +- **ServiceTemplate**: Defines pod and service templates for pod-based function execution. These templates are referenced by FunctionConfig resources that use the pod executor. + ## Troubleshooting ### Pods not starting diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md index 7e95b8982..f667f7431 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md @@ -6,7 +6,7 @@ description: | Overview of function runner functionality and detailed documentation pages. --- -The Function Runner provides three core functional areas that work together to execute KRM functions in isolated environments: +The Function Runner provides four core functional areas that work together to execute KRM functions in isolated environments: ## Functional Areas @@ -22,6 +22,19 @@ Executes KRM functions through pluggable evaluator strategies: For detailed architecture and process flows, see [Function Evaluation]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md" %}}). +### Function Configuration Management + +Provides declarative configuration of function executors through Kubernetes CRDs: +- **FunctionConfig Reconciler**: Embedded controller watches FunctionConfig resources and maintains internal cache +- **Executor Selection Cache**: Maps function images to executor types and configuration settings +- **Pod Executor Configuration**: Template overrides, TTL settings, and maximum parallel executions per function +- **Binary Executor Configuration**: Path mapping for substituting container images with local executables +- **Go Executor Configuration**: Function ID registration for native go function execution +- **Image Prefix Matching**: Supports multiple image prefixes and tags per function configuration +- **Template Customization**: Per-function pod and service template overrides including security context, resources, and environment variables + +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" %}}). + ### Pod Lifecycle Management Manages function execution pods with caching and garbage collection: @@ -32,6 +45,7 @@ Manages function execution pods with caching and garbage collection: - **TTL-Based Caching**: Reuses pods with configurable expiration and extension on use - **Garbage Collection**: Periodic cleanup of expired pods and failed pod handling - **Pod Warming**: Pre-creates pods for frequently-used functions +- **Template Overrides**: Applies FunctionConfig-specified customizations to pod and service templates For detailed architecture and process flows, see [Pod Lifecycle Management]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md" %}}). @@ -52,7 +66,20 @@ For detailed architecture and process flows, see [Image and Registry Management] ``` ┌─────────────────────────────────────────────────────────┐ │ Function Runner Service │ -│ │ +│ ┌──────────────────┐ │ +│ │ Function │ │ +│ │ Configuration │ │ +│ │ Management │ │ +│ │ │ │ +│ │ • FunctionConfig │ │ +│ │ Reconciler │ │ +│ │ • Executor Cache │ │ +│ │ • Image Prefix │ │ +│ │ Matching │ │ +│ └──────────────────┘ │ +│ │ │ +│ ┌────────────┴─────────────┐ │ +│ ↓ ↓ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Function │ │ Pod │ │ │ │ Evaluation │ ───> │ Lifecycle │ │ @@ -84,15 +111,18 @@ For detailed architecture and process flows, see [Image and Registry Management] **Integration flow:** 1. **Function Evaluation** receives gRPC request from Task Handler -2. **Multi-Evaluator** tries executable evaluator first (fast path) -3. **If NotFound**, falls back to pod evaluator (container execution) -4. **Pod Lifecycle Management** checks pod cache for existing pod -5. **If cache miss**, creates new pod with wrapper server via Pod Manager -6. **Image & Registry Management** resolves image metadata and authentication -7. **Pod Manager** creates pod with image pull secrets and service frontend -8. **Pod Cache Manager** stores pod with TTL for reuse -9. **Function Evaluation** connects to pod via service and executes function -10. **Wrapper Server** executes function binary and returns structured results -11. **Garbage Collection** periodically removes expired pods from cache - +2. **Function Configuration Management** queries cache for function-specific configuration +3. **Multi-Evaluator** selects appropriate evaluator based on FunctionConfig settings +4. **If binary executor configured**, executes local function binary (fast path) +5. **If go executor configured**, invokes registered native go function +6. **If pod executor configured or no match**, falls back to pod evaluator (container execution) +7. **Pod Lifecycle Management** checks pod cache for existing pod matching configuration +8. **If cache miss**, creates new pod with FunctionConfig template overrides via Pod Manager +9. **Image & Registry Management** resolves image metadata and authentication +10. **Pod Manager** creates pod with image pull secrets and service frontend +11. **Pod Cache Manager** stores pod with FunctionConfig-specified TTL for reuse +12. **Function Evaluation** connects to pod via service and executes function +13. **Wrapper Server** executes function binary and returns structured results +14. **Garbage Collection** periodically removes expired pods based on TTL settings + Each functional area is documented in detail on its own page with architecture diagrams, process flows, and implementation specifics. diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md index 2a66865d5..096dc8fdc 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md @@ -8,7 +8,7 @@ description: | ## Overview -Function evaluation is the core responsibility of the Function Runner - executing KRM (Kubernetes Resource Model) functions through pluggable evaluator strategies. The system uses a strategy pattern where different evaluators handle function execution in different ways (pod-based, executable, or chained), all conforming to a common interface. +Function evaluation is the core responsibility of the Function Runner - executing KRM (Kubernetes Resource Model) functions through pluggable evaluator strategies. The system uses a strategy pattern where different evaluators handle function execution in different ways (pod-based, executable, or chained), all conforming to a common interface. Configuration is managed via FunctionConfig CRDs that define image matching rules and executor-specific settings. ### High-Level Architecture @@ -17,13 +17,22 @@ Function evaluation is the core responsibility of the Function Runner - executin │ Function Evaluation System │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Evaluator │ │ Execution │ │ -│ │ Interface │ ───> │ Strategies │ │ +│ │ FunctionConfig │ │ Execution │ │ +│ │ CRDs │ ───> │ Strategies │ │ │ │ │ │ │ │ -│ │ • Common │ │ • Pod Evaluator │ │ -│ │ Contract │ │ • Exec Evaluator│ │ -│ │ • Pluggable │ │ • Multi Eval │ │ -│ └──────────────────┘ └──────────────────┘ │ +│ │ • Image Match │ │ • Pod Evaluator │ │ +│ │ • Executor Type │ │ • Exec Evaluator│ │ +│ │ • Configuration │ │ • Multi Eval │ │ +│ └────────┬─────────┘ └──────────────────┘ │ +│ │ │ │ +│ ↓ │ │ +│ ┌──────────────────┐ │ │ +│ │ Reconciler │ │ │ +│ │ │ │ │ +│ │ • Watch CRDs │ │ │ +│ │ • Populate │ │ │ +│ │ Cache │ │ │ +│ └────────┬─────────┘ │ │ │ │ │ │ │ └────────┬────────────────┘ │ │ ↓ │ @@ -70,12 +79,14 @@ Three evaluator implementations provide different execution strategies: - Uses wrapper server for gRPC interface - Manages pod cache with TTL-based expiration - Handles service mesh compatibility via ClusterIP services +- Configuration driven by FunctionConfig PodExecutor settings **Executable Evaluator:** - Executes pre-cached function binaries locally -- Configuration file maps images to binary paths +- FunctionConfig CRDs map images to binary paths - Fast execution without pod overhead - Returns NotFoundError for uncached functions +- Configuration driven by FunctionConfig BinaryExecutor settings **Multi-Evaluator:** - Chains multiple evaluators together @@ -85,7 +96,51 @@ Three evaluator implementations provide different execution strategies: ## Pod Evaluator -Executes functions in Kubernetes pods with caching and lifecycle management. +Executes functions in Kubernetes pods with caching and lifecycle management. Pod configuration is now driven by FunctionConfig CRDs. + +### FunctionConfig-Based Pod Configuration + +The pod evaluator uses FunctionConfig CRDs to determine pod execution parameters: + +**Configuration structure:** +- FunctionConfig CRDs define pod execution settings +- PodExecutor section specifies TTL, templates, and resources +- Multiple tags can share pod configuration +- Template overrides customize pod and container specs + +**Pod configuration options:** +- **TimeToLive**: Duration pods remain cached before cleanup +- **TemplateOverrides**: Customize pod and container settings + - ServiceAccountName: Override service account + - SecurityContext: Pod security settings + - Container resources, env, envFrom: Container customizations + - InitContainer resources, env, envFrom: Init container customizations + +**Example FunctionConfig for pod executor:** + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: apply-setters + namespace: porch-fn-system +spec: + image: apply-setters + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.2.2 + timeToLive: 30m + templateOverrides: + container: + resources: + limits: + memory: 512Mi + requests: + memory: 256Mi +``` ### Channel-Based Communication @@ -164,26 +219,44 @@ Executes pre-cached function binaries locally for fast execution. ### Configuration-Based Caching -The executable evaluator uses a configuration file to map images to binaries: +The executable evaluator uses FunctionConfig CRDs to map images to binaries: **Configuration structure:** -- YAML file with functions array -- Each function has name and images list -- Images map to binary in cache directory +- FunctionConfig CRDs define image matching rules +- Each FunctionConfig specifies image name, prefixes, and tags +- BinaryExecutor section maps specific tags to local binary paths +- Embedded reconciler watches FunctionConfigs and populates internal cache **Configuration benefits:** - Explicit control over cached functions - No automatic caching (predictable behavior) -- Simple file-based configuration -- Easy to update without restart +- Dynamic updates via Kubernetes API +- Cache automatically syncs with CRD changes ### Function Cache Lookup **Lookup characteristics:** -- Simple map lookup by image name +- Cache queried with full image reference +- Best matching FunctionConfig entry selected - Fast O(1) operation - NotFoundError triggers fallback in multi-evaluator -- No network or Kubernetes API calls +- No network or Kubernetes API calls during lookup + +### FunctionConfig Reconciler + +The function-runner includes an embedded FunctionConfig reconciler: + +**Reconciler responsibilities:** +- Watches FunctionConfig CRDs in function namespace +- Populates internal cache on FunctionConfig changes +- Maps image references to executor configurations +- Updates status to indicate successful application + +**Cache structure:** +- Map from full image reference to binary path +- Includes image prefix resolution +- Handles multiple tags per function +- Prevents duplicate image registrations ### Local Execution @@ -203,6 +276,27 @@ Binary execution happens in-process: - Millisecond execution times - Predictable performance +**Example FunctionConfig for binary executor:** + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: apply-setters + namespace: porch-fn-system +spec: + image: apply-setters + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + binaryExecutor: + tags: + - v0.2.0 + path: apply-setters +``` + +This configuration maps `apply-setters:v0.2.0` to the local binary at `./functions/apply-setters`. + ## Multi-Evaluator Chains multiple evaluators with fallback logic. @@ -233,6 +327,36 @@ Chains multiple evaluators with fallback logic. - Fallback only makes sense for missing functions - Prevents masking real errors +### Multi-Executor FunctionConfig + +A single FunctionConfig can define multiple executor types for different tags: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: apply-setters + namespace: porch-fn-system +spec: + image: apply-setters + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + binaryExecutor: + tags: + - v0.2.0 + path: apply-setters + podExecutor: + tags: + - v0.2.2 + timeToLive: 30m +``` + +In this example: +- `apply-setters:v0.2.0` executes via binary executor +- `apply-setters:v0.2.2` executes in a pod +- Other tags fall back to pod executor if available + ## Wrapper Server Provides gRPC interface for function execution inside pods. @@ -421,7 +545,7 @@ The evaluation system employs several performance strategies. **Warming strategy:** - Pre-create pods for frequently-used functions -- Configuration file specifies functions and TTLs +- FunctionConfig CRDs specify functions and TTLs - Concurrent pod creation at startup - Reduces first-request latency @@ -460,7 +584,93 @@ The evaluation system employs several performance strategies. - Affects concurrent execution capacity **Performance tuning:** -- Adjust pod TTL for reuse frequency -- Configure cache warming for hot functions +- Adjust pod TTL via FunctionConfig for reuse frequency +- Configure cache warming via FunctionConfig for hot functions - Use executable evaluator for critical path - Monitor pod resource usage + +## FunctionConfig CRD + +The FunctionConfig CRD is the central configuration mechanism for function evaluation in both function-runner and porch-server. + +### CRD Structure + +**Core fields:** +- **image**: Base image name (without prefix or tag) +- **prefixes**: List of registry prefixes to match +- **binaryExecutor**: Configuration for binary execution +- **podExecutor**: Configuration for pod execution +- **goExecutor**: Configuration for native Go execution (porch-server only) + +### Executor Types + +**Binary Executor:** +- Maps specific image tags to local binary executables +- **tags**: List of image tags to handle +- **path**: Absolute or relative path to binary +- Used by function-runner for fast local execution + +**Pod Executor:** +- Runs functions in containers with configurable settings +- **tags**: List of image tags to handle +- **timeToLive**: Duration pods remain cached (default: 30m) +- **templateOverrides**: Customize pod/container specifications +- Used by function-runner for containerized execution + +**Go Executor:** +- Executes functions as native Go calls +- **tags**: List of image tags to handle +- **id**: Registration ID for Go function (defaults to image name) +- Used by porch-server for built-in functions + +### Configuration Reconciliation + +Both function-runner and porch-server embed a FunctionConfig reconciler: + +**Reconciler behavior:** +- Watches FunctionConfig CRDs in the function namespace +- Populates internal cache on create/update/delete +- Maps full image references (with prefix and tag) to executor configurations +- Updates status with observedGeneration for each component + +**Cache lookup during evaluation:** +1. Function requested with image reference +2. Image prefix resolved (if needed) +3. Cache queried with full image reference +4. Best matching FunctionConfig entry selected +5. Executor and configuration determined +6. Fallback to next evaluator on NotFoundError + +**Example: Multi-tag configuration:** + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: set-namespace + namespace: porch-fn-system +spec: + image: set-namespace + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + binaryExecutor: + tags: + - v0.4.2 + path: set-namespace + podExecutor: + tags: + - v0.4.1 + timeToLive: 30m + goExecutor: + id: set-namespace + tags: + - v0.4 + - v0.4.5 +``` + +This configuration supports: +- Binary execution for `set-namespace:v0.4.2` +- Pod execution for `set-namespace:v0.4.1` +- Native Go execution for `set-namespace:v0.4` and `v0.4.5` (porch-server only) +- Automatic prefix resolution for both qualified and unqualified images diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md index 2313aa64b..2dcf3d276 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md @@ -21,11 +21,27 @@ Key design characteristics: - **Single-threaded cache management** eliminates race conditions - **Channel-based communication** provides clean separation between components - **Service mesh compatibility** through ClusterIP services fronting each pod -- **Template-based pod creation** supports ConfigMap-based and inline specifications +- **Template-based pod creation** using PodTemplate resources and ServiceTemplate CRs - **TTL-based lifecycle** with automatic garbage collection - **Failed pod detection** with immediate deletion and cache eviction - **Pod warming** capability for pre-creating pods at startup +## Function Configuration + +Porch uses FunctionConfig custom resources to configure function execution, including pod executor settings and template specifications. Each FunctionConfig defines how a specific KRM function should be executed and can specify configurations for multiple execution methods (pod executor, binary executor, or Go executor). + +The function-runner includes an embedded FunctionConfig reconciler that watches FunctionConfig resources and maintains an internal cache. This cache is used by both the pod cache manager and pod manager to determine execution parameters and pod template configurations for each function. + +**FunctionConfig Components:** + +**Image and Prefixes** - The base function image name and optional registry prefixes for image resolution. + +**Pod Executor Configuration** - Settings specific to pod-based execution including TTL, parallelism limits, queue length preferences, and template overrides. + +**Template Overrides** - Customizations that can be applied to the base pod template, including service account, security context, and container resource specifications. + +**PodTemplates and ServiceTemplates** - Define the actual pod and service templates used for creating function execution pods. These templates are referenced by the pod manager when creating pods. + ## Pod Cache Manager ### Cache Manager Architecture @@ -112,20 +128,36 @@ The Pod Manager handles low-level Kubernetes operations for function pods and th **Image Metadata Operations** - Cache image digests and entrypoints, inspect container images to extract configuration, handle private registry authentication and TLS configuration, manage image pull secrets for function pods. -**Template System** - Load pod templates from ConfigMaps or use inline defaults, load service templates from ConfigMaps or use inline defaults, track template versions to detect changes requiring pod replacement, patch templates with function-specific configuration. +**Template System** - Retrieve or create base pod and service templates from ServiceTemplate CRDs or inline defaults, track template versions to detect changes requiring pod replacement, patch templates with function-specific configuration and template overrides from FunctionConfig. ### Pod Template System The pod manager supports two template sources: ConfigMap-based templates for customization and inline templates as fallback defaults. -**ConfigMap-Based Templates:** +The pod manager retrieves base pod and service templates from PodTemplate resources and ServiceTemplate CRs in the function execution namespace. +If these resources are not found, the pod manager creates them from embedded inline defaults. -When functionPodTemplateName is configured, the pod manager retrieves a ConfigMap containing template and serviceTemplate keys. The ConfigMap's ResourceVersion is used as the template version for tracking changes. When the ConfigMap is updated, existing pods with old template versions are replaced on next use. +The template's `ResourceVersion` is used as the template version for tracking changes. When a template is updated, existing pods with old template versions are replaced on next use. **Inline Templates:** -When no ConfigMap is configured, the pod manager uses hardcoded inline templates with sensible defaults including init container for wrapper-server binary, main container with wrapper-server as entrypoint, EmptyDir volume for tools, readiness probe using grpc-health-probe, and cluster autoscaler safe-to-evict annotation. +When PodTemplate/ServiceTemplate resources are not found, the pod manager creates them from hardcoded inline templates with sensible defaults including init container for wrapper-server binary, main container with wrapper-server as entrypoint, EmptyDir volume for tools, readiness probe using grpc-health-probe, and cluster autoscaler safe-to-evict annotation. +**Template Overrides:** + +FunctionConfig resources can specify template overrides that customize the base templates on a per-function basis. The pod manager applies these overrides when creating pods: + +- **serviceAccountName** - Override the pod's service account +- **securityContext** - Override the pod's security context +- **initContainer** - Override init container resources, env, and envFrom +- **container** - Override main container resources, env, and envFrom + +These overrides are merged with the base template during pod creation, allowing function-specific customization without requiring separate templates for each function. + +**Legacy ConfigMap Approach:** + +Prior to the ServiceTemplate CRD implementation, pod and service templates were stored in ConfigMaps. This approach is deprecated. See [function-runner-pod-templates.md](../relevant_old_docs/function-runner-pod-templates.md) for historical reference. + ### Container Configuration The pod manager patches the function container in the template with function-specific configuration before creating the pod: @@ -223,11 +255,22 @@ Pods include a readiness probe that executes grpc-health-probe to verify the wra ### Pod Warming -Pod warming pre-creates function pods at startup to eliminate cold start latency for frequently used functions. Warming is configured through a YAML file mapping function images to TTLs. +Pod warming pre-creates function pods at startup to eliminate cold start latency for frequently used functions. Warming is configured through FunctionConfig resources that specify pod executor configurations. + +**Warming Process:** + +The pod cache manager iterates through all FunctionConfig resources in the internal cache and pre-creates pods for functions that have pod executor configurations with specified tags. For each function: +- The image is resolved using the configured prefixes or default image prefix +- A pod is created with a fixed name to ensure only one warming pod per function +- Pod creation happens asynchronously with a 1-minute timeout per pod + +{{% alert title="Note" color="primary" %}} +Pod warming is not yet adapted to the FunctionConfig reconciler and may not initialize pods for all functions. +{{% /alert %}} **Concurrent Creation:** -Warming creates all configured pods concurrently to minimize startup time. Each function is processed in a separate goroutine with a 1-minute timeout per pod. Using fixed names ensures only one pod is created per function even if multiple function runner instances start simultaneously. +Warming processes all configured functions concurrently to minimize startup time. Using fixed names ensures only one pod is created per function even if multiple function runner instances start simultaneously. **Startup Optimization:** @@ -249,8 +292,8 @@ Each pod has a reclaim-after annotation containing a Unix timestamp indicating w This approach provides automatic cleanup of unused pods while keeping frequently used pods alive indefinitely through TTL updates on each use. **TTL configuration:** -- Default TTL configured at function runner startup (e.g., 10 minutes) -- Per-function TTL can be specified in cache warming config +- Default TTL configured at function runner startup (e.g., 30 minutes) +- Per-function TTL specified in FunctionConfig pod executor configuration - Dynamic updates through TTL extension on each pod reuse ### GC Scan Process @@ -299,7 +342,7 @@ The cache maintains consistency through multiple validation mechanisms: **Service Validation** - Services are validated to ensure they exist and have active endpoints matching the pod IP. -**Template Version Tracking** - Pod template versions are tracked to detect when templates change, triggering pod replacement on next use. +**Template Version Tracking** - Pod template versions are tracked using ServiceTemplate ResourceVersion to detect when templates change, triggering pod replacement on next use. **Failed Pod Detection** - Failed pods are immediately detected and removed from cache during both validation and garbage collection. @@ -329,7 +372,7 @@ Pod reuse is the primary performance optimization, eliminating pod startup laten ### Cache Warming -Cache warming pre-creates pods at startup for frequently used functions, eliminating cold start latency. Warming is configured through a YAML file and creates all pods concurrently to minimize startup time. +Cache warming pre-creates pods at startup for frequently used functions, eliminating cold start latency. Warming is configured through FunctionConfig resources and creates all pods concurrently to minimize startup time. **Warming benefits:** - First evaluation served from ready pod (<100ms instead of 5-15 seconds) @@ -360,7 +403,8 @@ When multiple pods serve the same function, the cache manager selects the pod wi ### Resource Management -Function pods have resource limits configured via pod template to prevent resource exhaustion. Limits affect concurrent execution capacity and should be tuned based on function requirements and cluster resources. +Function pods have resource limits configured via PodTemplate resources and optionally customized per-function through FunctionConfig template overrides. +Resource limits prevent resource exhaustion and affect concurrent execution capacity. Limits should be tuned based on function requirements and cluster resources. ## Concurrency Model diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/interactions.md b/docs/content/en/docs/5_architecture_and_components/function-runner/interactions.md index 9d746fe6e..11b2cbfe9 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/interactions.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/interactions.md @@ -8,33 +8,137 @@ description: | ## Overview -The Function Runner is a **separate gRPC service** that interacts with multiple systems: the Task Handler (via gRPC), Kubernetes API (for pod management), container registries (for image metadata), and wrapper servers (for function execution). It operates independently from the Porch server, enabling isolated function execution. +The Function Runner is a **separate gRPC service** that interacts with multiple systems: the Task Handler (via gRPC), Kubernetes API (for pod management and FunctionConfig CRDs), container registries (for image metadata), and wrapper servers (for function execution). It operates independently from the Porch server, enabling isolated function execution. + +The Function Runner includes an **embedded FunctionConfig reconciler** that watches FunctionConfig CRDs and populates an internal cache. This cache determines which executor (pod, binary, or Go) to use for each function image. ### High-Level Architecture ``` -┌─────────────────────────────────────────────────────────┐ -│ Function Runner Service │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────┐ │ -│ │ Task Handler │ ───> │ gRPC │ ───> │ Eval │ │ -│ │ (in Porch) │ │ Server │ │uators│ │ -│ └──────────────┘ └──────────────┘ └──────┘ │ -│ ↑ │ │ │ -│ │ ↓ ↓ │ -│ │ ┌──────────────┐ ┌──────┐ │ -│ └──────────────│ Kubernetes │ │Image │ │ -│ │ API │ │Cache │ │ -│ └──────────────┘ └──────┘ │ -│ │ │ │ -│ ↓ ↓ │ -│ ┌──────────────┐ ┌─────────┐ │ -│ │ Function Pods│ │Registry │ │ -│ │ + Services │ │ APIs │ │ -│ └──────────────┘ └─────────┘ │ -└─────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ Function Runner Service │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ +│ │ Task Handler │ ───> │ gRPC │ ───> │ Evaluators │ │ +│ │ (in Porch) │ │ Server │ │ │ │ +│ └──────────────┘ └──────────────┘ └────────────┘ │ +│ ↑ │ │ │ +│ │ ↓ ↓ │ +│ │ ┌───────────────┐ ┌──────────┐ │ +│ │ │ FunctionConfig│ │ Executor │ │ +│ │ │ Reconciler │ ──> │ Cache │ │ +│ │ └───────────────┘ └──────────┘ │ +│ │ │ │ │ +│ │ ↓ ↓ │ +│ │ ┌──────────────┐ ┌─────────┐ │ +│ └──────────────│ Kubernetes │ │ Image │ │ +│ │ API │ │ Cache │ │ +│ └──────────────┘ └─────────┘ │ +│ │ │ │ +│ ↓ ↓ │ +│ ┌──────────────┐ ┌──────────┐ │ +│ │ Function Pods│ │ Registry │ │ +│ │ + Services │ │ APIs │ │ +│ └──────────────┘ └──────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────┘ +``` + +External Resources: +- FunctionConfig CRDs (define executor configurations) +- ServiceTemplate CRDs (define pod/service templates) + +## FunctionConfig Reconciler and Cache + +The Function Runner includes an embedded reconciler that watches FunctionConfig CRDs and maintains an internal cache of executor configurations. + +### Reconciliation Flow + +``` +FunctionConfig CRD + ↓ + Watch Event + ↓ + Reconciler + ↓ + Parse Spec + ↓ + ┌────┴────┬──────────┬──────────┐ + ↓ ↓ ↓ ↓ +Pod Binary Go Update +Config Config Config Status + ↓ ↓ ↓ ↓ +Pod Binary Go Return +Cache Cache Cache + ↓ ↓ ↓ + └────┬────┴──────────┘ + ↓ + Ready for + Evaluation ``` +**Reconciler responsibilities:** +- Watch FunctionConfig resources across all namespaces +- Parse executor configurations (pod, binary, Go) +- Populate executor-specific caches +- Update FunctionConfig status with observed generation +- Handle configuration errors and report via status + +**Cache structure:** +- **Pod executor cache**: Maps image names (with tags/prefixes) to `PodExecutorConfig` (TTL, parallelism, template overrides) +- **Binary executor cache**: Maps image names (with tags) to local binary paths +- **Go executor cache**: Maps image names (with tags) to in-process Go function processors + +### Executor Selection Logic + +When evaluating a function, the executor selection follows this pattern: + +``` +EvaluateFunction Request + ↓ + Extract Image Name + ↓ + Query Executor Cache + ↓ + ┌────┴────┬──────────┬──────────┐ + ↓ ↓ ↓ ↓ +Go Binary Pod Not Found +Match Match Match Error + ↓ ↓ ↓ ↓ +Go Binary Pod Fallback +Exec Exec Exec to Next +``` + +**Selection characteristics:** +- Image name extracted from request (including registry prefix and tag) +- Cache lookup considers full image reference with version +- Single function image can have multiple executors for different versions + - Example: `apply-replacements:v0.1.0` → binary executor + - Example: `apply-replacements:v0.2.0` → pod executor +- First matching executor is used +- NotFoundError triggers fallback to next evaluator in chain + +### Configuration Mapping + +FunctionConfig resources map to internal cache entries: + +**PodExecutor → Pod Cache:** +- `spec.image` + `spec.prefixes[]` + `spec.podExecutor.tags[]` → full image references +- `spec.podExecutor.timeToLive` → pod TTL before garbage collection +- `spec.podExecutor.maxParallelExecutions` → concurrent pod limit per function +- `spec.podExecutor.preferredMaxQueueLength` → waitlist length before scaling +- `spec.podExecutor.templateOverrides` → pod/container customizations + +**BinaryExecutor → Binary Cache:** +- `spec.image` + `spec.binaryExecutor.tags[]` → image references +- `spec.binaryExecutor.path` → absolute or relative binary path +- Path resolution: absolute if starts with `/`, else relative to `--functions` dir + +**GoExecutor → Go Cache:** +- `spec.image` + `spec.goExecutor.tags[]` → image references +- `spec.goExecutor.id` → internal function registration ID (defaults to `spec.image`) +- Registered Go functions: `apply-replacements`, `set-namespace`, `starlark` + ## Task Handler Integration The Function Runner integrates with the Task Handler through the gRPC Runtime: @@ -111,7 +215,7 @@ Both Porch and Function Runner must agree on message size limits: ## Evaluator Execution Patterns -The Function Runner uses different execution patterns based on evaluator type: +The Function Runner uses different execution patterns based on evaluator type. Executor selection is determined by the FunctionConfig cache, which maps function images (with prefixes and tags) to executor configurations. ### Pod-Based Execution @@ -140,6 +244,7 @@ Pod Pod Pod ``` **Execution pattern:** +- Pod executor configuration comes from FunctionConfig resources - Pod cache checked for existing pod (reuse if available) - Pod selection uses round-robin among pods with minimum waitlist length - Cache miss triggers pod creation with wrapper server @@ -148,6 +253,20 @@ Pod Pod Pod - Wrapper server executes function binary and returns results - Multiple evaluations can execute in parallel on the same pod +**Configuration from FunctionConfig:** +- `podExecutor.timeToLive`: How long pods remain cached before garbage collection +- `podExecutor.maxParallelExecutions`: Maximum concurrent pods per function +- `podExecutor.preferredMaxQueueLength`: Waitlist length before scaling up +- `podExecutor.templateOverrides`: Pod/container customizations (resources, env, security) +- `podExecutor.tags[]`: Image tags this configuration applies to + +**Template system:** +- ServiceTemplate CRDs define pod and service templates +- Base templates: `base-pod-template` and `base-service-template` in function runner namespace +- Inline templates as fallback if CRDs not found +- Template overrides from FunctionConfig merged with base templates +- Template version tracked via `resourceVersion` for pod replacement on changes + **For detailed pod lifecycle, see [Pod Lifecycle Management]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md" %}}).** ### Executable-Based Execution @@ -157,7 +276,7 @@ gRPC Request ↓ Executable Evaluator ↓ - Lookup in Config + Lookup in Cache ↓ Found? ──No──> Return NotFoundError │ @@ -169,11 +288,55 @@ gRPC Request ``` **Execution pattern:** -- Configuration file maps images to binary paths +- Binary executor configuration comes from FunctionConfig resources +- Cache maps image names (with tags) to local binary paths - Fast O(1) lookup by image name - Direct process execution with ResourceList input - NotFoundError triggers fallback in multi-evaluator +**Configuration from FunctionConfig:** +- `binaryExecutor.tags[]`: Image tags mapped to this binary +- `binaryExecutor.path`: Binary path (absolute or relative to `--functions` dir) +- Multiple tags can map to same binary (e.g., `v0.1.0`, `v0.1`, specific digest) + +**For detailed function evaluation, see [Function Evaluation]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md" %}}).** + +### Go-Based Execution + +``` +gRPC Request + ↓ + Go Evaluator (in porch-server) + ↓ + Lookup in Cache + ↓ + Found? ──No──> Return NotFoundError + │ + Yes + ↓ + Call Go Function Processor + ↓ + Return Response +``` + +**Execution pattern:** +- Go executor provides highest performance by avoiding process/container overhead +- Functions executed as native Go function calls within porch-server process +- Cache maps image names to `ResourceListProcessor` implementations +- Direct in-process execution with ResourceList input +- NotFoundError triggers fallback to next evaluator (typically gRPC runtime) + +**Configuration from FunctionConfig:** +- `goExecutor.tags[]`: Image tags mapped to this Go function +- `goExecutor.id`: Internal registration ID (defaults to `spec.image`) +- Registered functions: `apply-replacements`, `set-namespace`, `starlark` + +**Benefits:** +- No container startup overhead +- No gRPC network calls +- Fastest possible execution for compatible functions +- Lower resource usage compared to pod-based execution + **For detailed function evaluation, see [Function Evaluation]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md" %}}).** ## Kubernetes API Integration @@ -189,22 +352,26 @@ Pod Evaluator ↓ ┌──────┴──────┬──────────┬─────────┐ ↓ ↓ ↓ ↓ -Pod Ops Service Ops ConfigMap Secrets +Pod Ops Service Ops CRs Secrets ↓ ↓ ↓ ↓ -Create/Get Create/Get Template Auth -Delete Delete Retrieval Config +Create/Get Create/Get Function Auth +Delete Delete Config Config ``` **Resource operations:** - **Pods**: Create from template, get status, list by label, delete - **Services**: Create ClusterIP frontend, get endpoints, delete -- **ConfigMaps**: Retrieve pod/service templates for customization +- **FunctionConfig CRs**: Watch for configuration changes +- **ServiceTemplate CRs**: Base pod and service templates +- **PodTemplate resources**: Base pod specifications - **Secrets**: Access registry authentication and TLS certificates **Template system:** -- ConfigMap-based templates for organization-specific customization -- Inline templates as fallback defaults -- Template version tracking for pod replacement on changes +- ServiceTemplate CRs define base pod and service templates +- PodTemplate resources provide base pod specifications +- Inline templates as fallback if CRs/resources not found +- FunctionConfig provides per-function template overrides +- Template version tracked for pod replacement on changes **For detailed pod management, see [Pod Lifecycle Management]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md" %}}).** @@ -336,6 +503,7 @@ The Function Runner follows standard integration patterns: - Pod and service lifecycle management - Image metadata caching - Registry authentication +- FunctionConfig reconciliation and caching **Task Handler responsibilities:** - Render pipeline orchestration @@ -354,6 +522,7 @@ The Function Runner follows standard integration patterns: - No persistent state between requests - Pod cache is ephemeral (TTL-based) - Image cache is in-memory only +- Executor configuration cache populated from FunctionConfig CRs - Evaluators are stateless **Benefits:** @@ -368,6 +537,7 @@ The Function Runner follows standard integration patterns: - Garbage collection runs periodically - TTL updates are asynchronous patches - Cache warming at startup is concurrent +- FunctionConfig reconciliation is event-driven **Synchronous patterns:** - Function execution is synchronous (blocks until complete) diff --git a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md index 89a7c7c0d..00d0eefa0 100644 --- a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md +++ b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md @@ -11,6 +11,238 @@ KPT functions and KRM functions are synonymous terms referring to the same conta The Function Runner executes KRM functions in a secure, isolated environment. +## Function Configuration via FunctionConfig CRD + +FunctionConfig CRDs provide declarative configuration for KRM function execution. This is the primary method for configuring functions and replaces the previous ConfigMap-based approach. + +The function-runner includes an embedded reconciler that: +- Watches FunctionConfig resources in the configured namespace +- Maintains an internal cache of function configurations +- Uses the cached configuration to determine executor selection and execution parameters + +### FunctionConfig Resource Structure + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: + namespace: porch-fn-system +spec: + # Base function image name (without registry prefix or tag) + image: + + # Optional: List of registry prefixes that should be matched + # Empty string or omitted uses the default prefix + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + + # Optional: Configuration for pod-based execution + podExecutor: + tags: + - v1.0.0 + timeToLive: 30m + maxParallelExecutions: 2 + preferredMaxQueueLength: 1 + templateOverrides: + serviceAccountName: custom-sa + securityContext: + runAsUser: 1000 + initContainer: + resources: + limits: + memory: "256Mi" + container: + resources: + limits: + memory: "512Mi" + + # Optional: Configuration for binary executable substitution + binaryExecutor: + tags: + - v1.0.0 + path: /path/to/binary # Absolute or relative to functions directory + + # Optional: Configuration for native Go execution + goExecutor: + tags: + - v1.0 + id: custom-function-id # Optional: defaults to spec.image +``` + +### Configuration Fields + +#### spec.image +The base function image name without registry prefix or tag. This is matched against function references to determine which configuration to apply. + +#### spec.prefixes +List of registry prefixes that should be matched for this function. An empty string matches the default registry prefix. If omitted, only exact image matches are considered. + +#### spec.podExecutor +Configuration for running functions as Kubernetes pods: +- **tags**: List of image tags this configuration applies to +- **timeToLive**: Duration pods live before garbage collection (default: 30m) +- **maxParallelExecutions**: Maximum number of concurrent pods for this function +- **preferredMaxQueueLength**: Maximum waitlist length per pod +- **templateOverrides**: Customizations to apply to the pod template + +#### spec.binaryExecutor +Configuration for substituting function execution with a local binary: +- **tags**: List of image tags that should use the binary +- **path**: Absolute path or relative path to the functions directory + +#### spec.goExecutor +Configuration for native Go function execution within the porch-server: +- **tags**: List of image tags that should use native execution +- **id**: Function identifier for registration (defaults to spec.image if omitted) + +### Template Overrides + +The `templateOverrides` structure allows customization of pod execution: + +```yaml +templateOverrides: + # Service account for the function pod + serviceAccountName: function-sa + + # Pod security context + securityContext: + runAsUser: 1000 + runAsGroup: 1000 + fsGroup: 1000 + + # Init container customizations + initContainer: + resources: + limits: + memory: "256Mi" + cpu: "500m" + requests: + memory: "128Mi" + cpu: "250m" + env: + - name: CUSTOM_VAR + value: "value" + envFrom: + - secretRef: + name: function-secret + + # Main container customizations + container: + resources: + limits: + memory: "512Mi" + cpu: "1000m" + requests: + memory: "256Mi" + cpu: "500m" + env: + - name: CUSTOM_VAR + value: "value" + envFrom: + - configMapRef: + name: function-config +``` + +### Example FunctionConfig Resources + +Basic pod executor configuration: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: set-namespace + namespace: porch-fn-system +spec: + image: set-namespace + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.4.1 + timeToLive: 30m +``` + +Multi-executor configuration: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: starlark + namespace: porch-fn-system +spec: + image: starlark + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.4.3 + timeToLive: 30m + binaryExecutor: + tags: + - v0.5.2 + path: starlark + goExecutor: + id: starlark + tags: + - v0.5 + - v0.5.5 +``` + +Configuration with resource limits: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: gatekeeper + namespace: porch-fn-system +spec: + image: gatekeeper + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.2.1 + timeToLive: 30m + maxParallelExecutions: 3 + preferredMaxQueueLength: 2 + templateOverrides: + container: + resources: + limits: + memory: "1Gi" + cpu: "1000m" + requests: + memory: "512Mi" + cpu: "500m" +``` + +### RBAC Requirements + +The function-runner requires permissions to watch FunctionConfig resources: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: function-runner + namespace: porch-fn-system +rules: + - apiGroups: ["config.porch.kpt.dev"] + resources: ["functionconfigs"] + verbs: ["get", "list", "watch"] + - apiGroups: ["config.porch.kpt.dev"] + resources: ["functionconfigs/status"] + verbs: ["get", "update", "patch"] +``` + ## Configuration Options ### Command Line Arguments @@ -27,23 +259,28 @@ args: ```bash args: - --functions=./functions # Path to cached functions (default: ./functions) -- --config=./config.yaml # Path to exec runtime config file (default: ./config.yaml) ``` +{{% alert title="Note" color="primary" %}} +The `--config` flag for exec runtime configuration is deprecated. Use FunctionConfig CRDs instead. +{{% /alert %}} + #### Pod Runtime Arguments ```bash args: -- --pod-cache-config=/pod-cache-config/pod-cache-config.yaml # Pod cache config file path - --warm-up-pod-cache=true # Warm up pod cache on startup (default: true) - --pod-namespace=porch-fn-system # Namespace for KRM function pods (default: porch-fn-system) - --pod-ttl=30m # Pod TTL before GC (default: 30m) - --scan-interval=1m # GC scan interval (default: 1m) -- --function-pod-template= # ConfigMap with pod specification - --max-request-body-size=6291456 # Max gRPC message size in bytes (default: 6MB) - --max-waitlist-length # Maximum waitlist length per pod - --max-parallel-pods-per-function # Maximum parallel pods per function ``` +{{% alert title="Note" color="primary" %}} +The `--pod-cache-config` and `--function-pod-template` flags are deprecated. Use FunctionConfig CRDs to configure pod execution settings and template customizations. +{{% /alert %}} + #### Private Registry Arguments ```bash args: @@ -84,9 +321,10 @@ The exec runtime runs functions as local executables: ```bash args: - --functions=./functions # Directory containing cached function executables -- --config=./config.yaml # Configuration file for exec runtime ``` +Configure function-to-binary mappings using FunctionConfig resources with `binaryExecutor` specification. + ### Pod Runtime The pod runtime runs functions as Kubernetes pods: @@ -99,6 +337,8 @@ args: - --warm-up-pod-cache=true # Pre-deploy common function pods ``` +Configure pod execution settings, resource limits, and template customizations using FunctionConfig resources with `podExecutor` specification. + ### Disabling Runtimes To disable specific runtimes: @@ -198,4 +438,4 @@ spec: For advanced configuration options: - [Pod Templates]({{% relref "pod-templates" %}}) - Customize function pod specifications - [Private Registries]({{% relref "private-registries-config" %}}) - Configure private registry access -{{% /alert %}} \ No newline at end of file +{{% /alert %}} diff --git a/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md b/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md index 2913eb500..d11f02eff 100644 --- a/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md +++ b/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md @@ -87,6 +87,11 @@ kpt live init porch kpt live apply porch ``` +The catalog package includes: +- FunctionConfig and ServiceTemplate CRDs for configuring KRM function execution +- Multiple pre-configured FunctionConfig resources for common KRM functions (apply-replacements, set-namespace, starlark, etc.) +- Pod and service templates for pod-based function execution + ## Verification ### Check Pod Status @@ -114,6 +119,32 @@ Confirm Porch CRDs are registered: kubectl api-resources | grep porch ``` +### Check FunctionConfig Resources + +Verify FunctionConfig resources are deployed: + +```bash +kubectl get functionconfigs -n porch-fn-system +``` + +You should see several pre-configured function configurations for common KRM functions such as: +- `apply-replacements` +- `set-namespace` +- `starlark` +- `apply-setters` +- `set-labels` + +These FunctionConfig resources define how KRM functions are executed (using pod, binary, or go executors) and streamline function configuration compared to the older ConfigMap-based approach. + +### Check ServiceTemplate Resources + +Verify ServiceTemplate CRDs are available: + +```bash +kubectl get crd servicetemplates.config.porch.kpt.dev +``` + +ServiceTemplate resources define pod and service templates for pod-based function execution. ## Troubleshooting @@ -130,8 +161,27 @@ kubectl logs -n porch-system -l app=porch-server kubectl get crd | grep porch ``` +**FunctionConfig resources not applied:** + +Ensure FunctionConfig resources are created in the `porch-fn-system` namespace: +```bash +kubectl get functionconfigs -n porch-fn-system +``` + +Check if the FunctionConfig reconciler is running in function-runner and porch-server pods: +```bash +kubectl logs -n porch-system -l app=function-runner | grep -i functionconfig +kubectl logs -n porch-system -l app=porch-server | grep -i functionconfig +``` + +View FunctionConfig status to see which components have applied the configuration: +```bash +kubectl get functionconfigs -n porch-fn-system -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status}{"\n"}{end}' +``` + ### Getting Help For additional support: - Check the [Porch GitHub issues](https://github.com/nephio-project/porch/issues) - Join the [Nephio community](https://nephio.org/community/) +- See [FunctionConfig documentation]({{% relref "../configurations/components/function-runner-config" %}}) for customizing function execution From b91a94cd898db029139accc0b3aa329b11506333 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B3zes=20L=C3=A1szl=C3=B3=20M=C3=A1t=C3=A9?= Date: Fri, 8 May 2026 14:12:06 +0200 Subject: [PATCH 2/3] fix ref --- .../function-runner/functionality/_index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md index f667f7431..88ef84b5c 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md @@ -33,7 +33,9 @@ Provides declarative configuration of function executors through Kubernetes CRDs - **Image Prefix Matching**: Supports multiple image prefixes and tags per function configuration - **Template Customization**: Per-function pod and service template overrides including security context, resources, and environment variables -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" %}}). +For detailed configuration examples, see [Function Runner Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md" %}}). + +For integration with executor selection, see [Function Runner Interactions]({{% relref "/docs/5_architecture_and_components/function-runner/interactions.md" %}}). ### Pod Lifecycle Management From e0cfc0d06e34751ebcd869e63a43dffa67bf8da9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=B3zes=20L=C3=A1szl=C3=B3=20M=C3=A1t=C3=A9?= Date: Tue, 12 May 2026 11:52:06 +0200 Subject: [PATCH 3/3] address some review comments --- docs/content/en/docs/2_concepts/functions.md | 14 +- .../functionality/function-evaluation.md | 42 +--- .../functionality/pod-lifecycle-management.md | 8 +- .../function-runner-config/_index.md | 233 +---------------- .../function-configuration.md | 238 ++++++++++++++++++ .../function-runner-config/pod-templates.md | 6 +- .../deployments/catalog-deployment.md | 20 +- 7 files changed, 268 insertions(+), 293 deletions(-) create mode 100644 docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md diff --git a/docs/content/en/docs/2_concepts/functions.md b/docs/content/en/docs/2_concepts/functions.md index 30efc9a01..e51e28a81 100644 --- a/docs/content/en/docs/2_concepts/functions.md +++ b/docs/content/en/docs/2_concepts/functions.md @@ -22,9 +22,10 @@ For details on how to declare and configure functions in the Kptfile pipeline, s ## Function Configuration -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. +Porch uses **FunctionConfig** custom resources to configure how functions execute. +These configurations determine which executor type should handle the given function images and provide executor-specific settings. -Each FunctionConfig specifies: +Each FunctionConfig defines: - **Image and prefixes**: The function image name and optional registry prefixes - **Executor configurations**: One or more executor types (pod, binary, or go) with associated settings - **Version-specific settings**: Different executors and configurations for different image tags @@ -57,7 +58,8 @@ spec: - v0.4.5 ``` -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. +Most Porch components include an embedded reconciler that watches FunctionConfig resources and populates the component's own internal cache. +This cache determines which executor to use for each function invocation. ## Function Execution in Porch @@ -78,9 +80,9 @@ Porch executes functions using multiple executor types, determined by FunctionCo - Only available for functions integrated as Go libraries - No container or process overhead -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. +Regardless of executor type, Porch passes the package's resources to [kpt](https://kpt.dev), 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. +Pipeline execution is triggered automatically following creation or clone of a package revision, update of a package revision, and when a package revision is proposed. kpt passes the function results back to Porch and Porch stores them in the PackageRevisionResources's `status.renderStatus` field. ## When Functions Execute @@ -137,7 +139,7 @@ enabling iterative development on incomplete packages. - Functions are standard KRM functions declared in the Kptfile pipeline (see [kpt functions docs](https://kpt.dev/book/04-using-functions/)) - Function execution behavior is configured using FunctionConfig custom resources that specify executor types (pod, binary, or go) -- Both function-runner and porch-server include FunctionConfig reconcilers that populate internal caches to determine which executor handles each function +- Most Porch components include an embedded FunctionConfig reconciler that populates internal caches to determine which executor handles each function - Functions can execute via pod containers, local binaries, or in-process Go calls depending on configuration - Functions automatically execute during package rendering on Draft package revisions - Function results are stored in `status.renderStatus` of the PackageRevisionResources view of a package revision diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md index 096dc8fdc..10d4ced30 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/function-evaluation.md @@ -589,43 +589,7 @@ The evaluation system employs several performance strategies. - Use executable evaluator for critical path - Monitor pod resource usage -## FunctionConfig CRD - -The FunctionConfig CRD is the central configuration mechanism for function evaluation in both function-runner and porch-server. - -### CRD Structure - -**Core fields:** -- **image**: Base image name (without prefix or tag) -- **prefixes**: List of registry prefixes to match -- **binaryExecutor**: Configuration for binary execution -- **podExecutor**: Configuration for pod execution -- **goExecutor**: Configuration for native Go execution (porch-server only) - -### Executor Types - -**Binary Executor:** -- Maps specific image tags to local binary executables -- **tags**: List of image tags to handle -- **path**: Absolute or relative path to binary -- Used by function-runner for fast local execution - -**Pod Executor:** -- Runs functions in containers with configurable settings -- **tags**: List of image tags to handle -- **timeToLive**: Duration pods remain cached (default: 30m) -- **templateOverrides**: Customize pod/container specifications -- Used by function-runner for containerized execution - -**Go Executor:** -- Executes functions as native Go calls -- **tags**: List of image tags to handle -- **id**: Registration ID for Go function (defaults to image name) -- Used by porch-server for built-in functions - -### Configuration Reconciliation - -Both function-runner and porch-server embed a FunctionConfig reconciler: +## Configuration Reconciliation **Reconciler behavior:** - Watches FunctionConfig CRDs in the function namespace @@ -669,8 +633,8 @@ spec: - v0.4.5 ``` -This configuration supports: +This example configuration supports: - Binary execution for `set-namespace:v0.4.2` - Pod execution for `set-namespace:v0.4.1` -- Native Go execution for `set-namespace:v0.4` and `v0.4.5` (porch-server only) +- Native Go execution for `set-namespace:v0.4` and `v0.4.5` - Automatic prefix resolution for both qualified and unqualified images diff --git a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md index 2dcf3d276..48c770ba0 100644 --- a/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md +++ b/docs/content/en/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md @@ -128,13 +128,13 @@ The Pod Manager handles low-level Kubernetes operations for function pods and th **Image Metadata Operations** - Cache image digests and entrypoints, inspect container images to extract configuration, handle private registry authentication and TLS configuration, manage image pull secrets for function pods. -**Template System** - Retrieve or create base pod and service templates from ServiceTemplate CRDs or inline defaults, track template versions to detect changes requiring pod replacement, patch templates with function-specific configuration and template overrides from FunctionConfig. +**Template System** - Retrieve or create base pod and service templates from ServiceTemplate custom resources or inline defaults, track template versions to detect changes requiring pod replacement, patch templates with function-specific configuration and template overrides from FunctionConfig. ### Pod Template System The pod manager supports two template sources: ConfigMap-based templates for customization and inline templates as fallback defaults. -The pod manager retrieves base pod and service templates from PodTemplate resources and ServiceTemplate CRs in the function execution namespace. +The pod manager retrieves base pod and service templates from PodTemplate resources and ServiceTemplate resources in the function execution namespace. If these resources are not found, the pod manager creates them from embedded inline defaults. The template's `ResourceVersion` is used as the template version for tracking changes. When a template is updated, existing pods with old template versions are replaced on next use. @@ -154,10 +154,6 @@ FunctionConfig resources can specify template overrides that customize the base These overrides are merged with the base template during pod creation, allowing function-specific customization without requiring separate templates for each function. -**Legacy ConfigMap Approach:** - -Prior to the ServiceTemplate CRD implementation, pod and service templates were stored in ConfigMaps. This approach is deprecated. See [function-runner-pod-templates.md](../relevant_old_docs/function-runner-pod-templates.md) for historical reference. - ### Container Configuration The pod manager patches the function container in the template with function-specific configuration before creating the pod: diff --git a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md index 00d0eefa0..f9f25a354 100644 --- a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md +++ b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/_index.md @@ -11,238 +11,6 @@ KPT functions and KRM functions are synonymous terms referring to the same conta The Function Runner executes KRM functions in a secure, isolated environment. -## Function Configuration via FunctionConfig CRD - -FunctionConfig CRDs provide declarative configuration for KRM function execution. This is the primary method for configuring functions and replaces the previous ConfigMap-based approach. - -The function-runner includes an embedded reconciler that: -- Watches FunctionConfig resources in the configured namespace -- Maintains an internal cache of function configurations -- Uses the cached configuration to determine executor selection and execution parameters - -### FunctionConfig Resource Structure - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: FunctionConfig -metadata: - name: - namespace: porch-fn-system -spec: - # Base function image name (without registry prefix or tag) - image: - - # Optional: List of registry prefixes that should be matched - # Empty string or omitted uses the default prefix - prefixes: - - "" - - ghcr.io/kptdev/krm-functions-catalog - - # Optional: Configuration for pod-based execution - podExecutor: - tags: - - v1.0.0 - timeToLive: 30m - maxParallelExecutions: 2 - preferredMaxQueueLength: 1 - templateOverrides: - serviceAccountName: custom-sa - securityContext: - runAsUser: 1000 - initContainer: - resources: - limits: - memory: "256Mi" - container: - resources: - limits: - memory: "512Mi" - - # Optional: Configuration for binary executable substitution - binaryExecutor: - tags: - - v1.0.0 - path: /path/to/binary # Absolute or relative to functions directory - - # Optional: Configuration for native Go execution - goExecutor: - tags: - - v1.0 - id: custom-function-id # Optional: defaults to spec.image -``` - -### Configuration Fields - -#### spec.image -The base function image name without registry prefix or tag. This is matched against function references to determine which configuration to apply. - -#### spec.prefixes -List of registry prefixes that should be matched for this function. An empty string matches the default registry prefix. If omitted, only exact image matches are considered. - -#### spec.podExecutor -Configuration for running functions as Kubernetes pods: -- **tags**: List of image tags this configuration applies to -- **timeToLive**: Duration pods live before garbage collection (default: 30m) -- **maxParallelExecutions**: Maximum number of concurrent pods for this function -- **preferredMaxQueueLength**: Maximum waitlist length per pod -- **templateOverrides**: Customizations to apply to the pod template - -#### spec.binaryExecutor -Configuration for substituting function execution with a local binary: -- **tags**: List of image tags that should use the binary -- **path**: Absolute path or relative path to the functions directory - -#### spec.goExecutor -Configuration for native Go function execution within the porch-server: -- **tags**: List of image tags that should use native execution -- **id**: Function identifier for registration (defaults to spec.image if omitted) - -### Template Overrides - -The `templateOverrides` structure allows customization of pod execution: - -```yaml -templateOverrides: - # Service account for the function pod - serviceAccountName: function-sa - - # Pod security context - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - - # Init container customizations - initContainer: - resources: - limits: - memory: "256Mi" - cpu: "500m" - requests: - memory: "128Mi" - cpu: "250m" - env: - - name: CUSTOM_VAR - value: "value" - envFrom: - - secretRef: - name: function-secret - - # Main container customizations - container: - resources: - limits: - memory: "512Mi" - cpu: "1000m" - requests: - memory: "256Mi" - cpu: "500m" - env: - - name: CUSTOM_VAR - value: "value" - envFrom: - - configMapRef: - name: function-config -``` - -### Example FunctionConfig Resources - -Basic pod executor configuration: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: FunctionConfig -metadata: - name: set-namespace - namespace: porch-fn-system -spec: - image: set-namespace - prefixes: - - "" - - ghcr.io/kptdev/krm-functions-catalog - podExecutor: - tags: - - v0.4.1 - timeToLive: 30m -``` - -Multi-executor configuration: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: FunctionConfig -metadata: - name: starlark - namespace: porch-fn-system -spec: - image: starlark - prefixes: - - "" - - ghcr.io/kptdev/krm-functions-catalog - podExecutor: - tags: - - v0.4.3 - timeToLive: 30m - binaryExecutor: - tags: - - v0.5.2 - path: starlark - goExecutor: - id: starlark - tags: - - v0.5 - - v0.5.5 -``` - -Configuration with resource limits: - -```yaml -apiVersion: config.porch.kpt.dev/v1alpha1 -kind: FunctionConfig -metadata: - name: gatekeeper - namespace: porch-fn-system -spec: - image: gatekeeper - prefixes: - - "" - - ghcr.io/kptdev/krm-functions-catalog - podExecutor: - tags: - - v0.2.1 - timeToLive: 30m - maxParallelExecutions: 3 - preferredMaxQueueLength: 2 - templateOverrides: - container: - resources: - limits: - memory: "1Gi" - cpu: "1000m" - requests: - memory: "512Mi" - cpu: "500m" -``` - -### RBAC Requirements - -The function-runner requires permissions to watch FunctionConfig resources: - -```yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: function-runner - namespace: porch-fn-system -rules: - - apiGroups: ["config.porch.kpt.dev"] - resources: ["functionconfigs"] - verbs: ["get", "list", "watch"] - - apiGroups: ["config.porch.kpt.dev"] - resources: ["functionconfigs/status"] - verbs: ["get", "update", "patch"] -``` - ## Configuration Options ### Command Line Arguments @@ -437,5 +205,6 @@ spec: {{% alert title="Note" color="primary" %}} For advanced configuration options: - [Pod Templates]({{% relref "pod-templates" %}}) - Customize function pod specifications +- [Function Configuration]({{% relref "function-configuration" %}}) - Customize function evaluation settings - [Private Registries]({{% relref "private-registries-config" %}}) - Configure private registry access {{% /alert %}} diff --git a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md new file mode 100644 index 000000000..0cff23e1a --- /dev/null +++ b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md @@ -0,0 +1,238 @@ +--- +title: "Function Configuration" +type: docs +weight: 2 +description: "Customize function evaluation using FunctionConfig resources" +--- + +## Overview + +FunctionConfig CRs provide declarative configuration for KRM function execution. This is the primary method for configuring functions and replaces the previous ConfigMap-based approach. + +The function-runner includes an embedded reconciler that: +- Watches FunctionConfig resources in the configured namespace +- Maintains an internal cache of function configurations +- Uses the cached configuration to determine executor selection and execution parameters + +## FunctionConfig Resource Structure + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: + namespace: porch-fn-system +spec: + # Base function image name (without registry prefix or tag) + image: + + # Optional: List of registry prefixes that should be matched + # Empty string or omitted uses the default prefix + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + + # Optional: Configuration for pod-based execution + podExecutor: + tags: + - v1.0.0 + timeToLive: 30m + maxParallelExecutions: 2 + preferredMaxQueueLength: 1 + templateOverrides: + serviceAccountName: custom-sa + securityContext: + runAsUser: 1000 + initContainer: + resources: + limits: + memory: "256Mi" + container: + resources: + limits: + memory: "512Mi" + + # Optional: Configuration for binary executable substitution + binaryExecutor: + tags: + - v1.0.0 + path: /path/to/binary # Absolute or relative to functions directory + + # Optional: Configuration for native Go execution + goExecutor: + tags: + - v1.0 + id: custom-function-id # Optional: defaults to spec.image +``` + +## Configuration Fields + +### spec.image +The base function image name without registry prefix or tag. This is matched against function references to determine which configuration to apply. + +### spec.prefixes +List of registry prefixes that should be matched for this function. An empty string matches the default registry prefix. If omitted, only exact image matches are considered. + +### spec.podExecutor +Configuration for running functions as Kubernetes pods: +- **tags**: List of image tags this configuration applies to +- **timeToLive**: Duration pods live before garbage collection (default: 30m) +- **maxParallelExecutions**: Maximum number of concurrent pods for this function +- **preferredMaxQueueLength**: Maximum waitlist length per pod +- **templateOverrides**: Customizations to apply to the pod template + +### spec.binaryExecutor +Configuration for substituting function execution with a local binary in the function-runner pod: +- **tags**: List of image tags that should use the binary +- **path**: Absolute path or relative path to the functions directory + +### spec.goExecutor +Configuration for native Go function execution within the porch-server: +- **tags**: List of image tags that should use native execution +- **id**: Function identifier for registration (defaults to spec.image if omitted) + +## Template Overrides + +The `templateOverrides` structure allows customization of pod execution: + +```yaml +templateOverrides: + # Service account for the function pod + serviceAccountName: function-sa + + # Pod security context + securityContext: + runAsUser: 1000 + runAsGroup: 1000 + fsGroup: 1000 + + # Init container customizations + initContainer: + resources: + limits: + memory: "256Mi" + cpu: "500m" + requests: + memory: "128Mi" + cpu: "250m" + env: + - name: CUSTOM_VAR + value: "value" + envFrom: + - secretRef: + name: function-secret + + # Main container customizations + container: + resources: + limits: + memory: "512Mi" + cpu: "1000m" + requests: + memory: "256Mi" + cpu: "500m" + env: + - name: CUSTOM_VAR + value: "value" + envFrom: + - configMapRef: + name: function-config +``` + +## Example FunctionConfig Resources + +Basic pod executor configuration: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: set-namespace + namespace: porch-fn-system +spec: + image: set-namespace + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.4.1 + timeToLive: 30m +``` + +Multi-executor configuration: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: starlark + namespace: porch-fn-system +spec: + image: starlark + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.4.3 + timeToLive: 30m + binaryExecutor: + tags: + - v0.5.2 + path: starlark + goExecutor: + id: starlark + tags: + - v0.5 + - v0.5.5 +``` + +Configuration with resource limits: + +```yaml +apiVersion: config.porch.kpt.dev/v1alpha1 +kind: FunctionConfig +metadata: + name: gatekeeper + namespace: porch-fn-system +spec: + image: gatekeeper + prefixes: + - "" + - ghcr.io/kptdev/krm-functions-catalog + podExecutor: + tags: + - v0.2.1 + timeToLive: 30m + maxParallelExecutions: 3 + preferredMaxQueueLength: 2 + templateOverrides: + container: + resources: + limits: + memory: "1Gi" + cpu: "1000m" + requests: + memory: "512Mi" + cpu: "500m" +``` + +## RBAC Requirements + +The function-runner requires permissions to watch FunctionConfig resources: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: function-runner + namespace: porch-fn-system +rules: + - apiGroups: ["config.porch.kpt.dev"] + resources: ["functionconfigs"] + verbs: ["get", "list", "watch"] + - apiGroups: ["config.porch.kpt.dev"] + resources: ["functionconfigs/status"] + verbs: ["get", "update", "patch"] +``` diff --git a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/pod-templates.md b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/pod-templates.md index 53f04ef11..b581d9578 100644 --- a/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/pod-templates.md +++ b/docs/content/en/docs/6_configuration_and_deployments/configurations/components/function-runner-config/pod-templates.md @@ -2,10 +2,12 @@ title: "Pod Templates" type: docs weight: 2 -description: "Customize function evaluator pod specifications using ConfigMap templates" +description: "Customize function evaluator pod specifications using PodTemplates" --- -The Function Runner supports customizing the pod specifications used for KRM function evaluation through ConfigMap-based templates. This allows you to configure resource limits, security contexts, node selectors, tolerations, and other pod-level settings for function execution pods. +The Function Runner supports customizing the pod specifications used for KRM function evaluation through PodTemplates. This allows you to configure resource limits, security contexts, node selectors, tolerations, and other pod-level settings for function execution pods. + + ## Overview diff --git a/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md b/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md index d11f02eff..ee5220eb3 100644 --- a/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md +++ b/docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md @@ -88,8 +88,7 @@ kpt live apply porch ``` The catalog package includes: -- FunctionConfig and ServiceTemplate CRDs for configuring KRM function execution -- Multiple pre-configured FunctionConfig resources for common KRM functions (apply-replacements, set-namespace, starlark, etc.) +- Multiple pre-configured [FunctionConfig]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md" %}}) resources for common KRM functions (apply-replacements, set-namespace, starlark, etc.) - Pod and service templates for pod-based function execution ## Verification @@ -128,11 +127,17 @@ kubectl get functionconfigs -n porch-fn-system ``` You should see several pre-configured function configurations for common KRM functions such as: -- `apply-replacements` -- `set-namespace` -- `starlark` -- `apply-setters` -- `set-labels` +``` +NAME SERVER APPLIED FNRUNNER APPLIED CONTROLLER APPLIED +apply-replacements 1 1 1 +apply-setters 1 1 1 +create-setters 1 1 1 +enable-gcp-services 1 1 1 +ensure-name-substring 1 1 1 +export-terraform 1 1 1 +gatekeeper 1 1 1 +... +``` These FunctionConfig resources define how KRM functions are executed (using pod, binary, or go executors) and streamline function configuration compared to the older ConfigMap-based approach. @@ -184,4 +189,3 @@ kubectl get functionconfigs -n porch-fn-system -o jsonpath='{range .items[*]}{.m For additional support: - Check the [Porch GitHub issues](https://github.com/nephio-project/porch/issues) - Join the [Nephio community](https://nephio.org/community/) -- See [FunctionConfig documentation]({{% relref "../configurations/components/function-runner-config" %}}) for customizing function execution