Add documentation for FunctionConfig CRD and reconciler (v2)

deployments/function-pods/deployment.yaml

@@ -11,73 +11,80 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+#
+# Sample replacement for the function-runner base templates. Applying this
+# overwrites base-pod-template and base-service-template in porch-fn-system.
+# The function-runner looks these up by name; no extra CLI flags are required.
 ---
 apiVersion: v1
-kind: ConfigMap
+kind: PodTemplate
 metadata:
-  name: kpt-function-eval-pod-template
-  namespace: porch-system
-data:
-  template: |
-    apiVersion: v1
-    kind: Pod
+  name: base-pod-template
+  namespace: porch-fn-system
+template:
+  metadata:
     annotations:
-      cluster-autoscaler.kubernetes.io/safe-to-evict: true
-    spec:
-      initContainers:
-        - name: copy-wrapper-server
-          image: ghcr.io/kptdev/porch-wrapper-server:latest
-          command:
-            - cp
-            - -a
-            - /home/nonroot/wrapper-server/.
-            - /wrapper-server-tools
-          volumeMounts:
-            - name: wrapper-server-tools
-              mountPath: /wrapper-server-tools
-      containers:
-        - name: function
-          image: image-replaced-by-kpt-func-image
-          command:
-            - /wrapper-server-tools/wrapper-server
-          volumeMounts:
-            - name: wrapper-server-tools
-              mountPath: /wrapper-server-tools
-      volumes:
-        - name: wrapper-server-tools
-          emptyDir: {}
-  serviceTemplate: |
-    apiVersion: v1
-    kind: Service
-    spec:
-      ports:
+      cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
+  spec:
+    initContainers:
+      - name: copy-wrapper-server
+        image: ghcr.io/kptdev/porch-wrapper-server:latest
+        command:
+          - cp
+          - -a
+          - /home/nonroot/wrapper-server/.
+          - /wrapper-server-tools
+        volumeMounts:
+          - name: wrapper-server-tools
+            mountPath: /wrapper-server-tools
+        imagePullPolicy: IfNotPresent
+    containers:
+      - name: function
+        image: image-replaced-by-kpt-func-image
+        command:
+          - /wrapper-server-tools/wrapper-server
+        env:
+          - name: OTEL_METRICS_EXPORTER
+            value: prometheus
+          - name: OTEL_TRACES_EXPORTER
+            value: none
+          - name: OTEL_EXPORTER_PROMETHEUS_HOST
+            value: 0.0.0.0
+          - name: OTEL_EXPORTER_PROMETHEUS_PORT
+            value: "9464"
+        ports:
+          - containerPort: 9464
+            name: metrics
+        readinessProbe:
+          exec:
+            command: [ "/wrapper-server-tools/grpc-health-probe", "-addr", "localhost:9446" ]
+        livenessProbe:
+          exec:
+            command: [ "/wrapper-server-tools/grpc-health-probe", "-addr", "localhost:9446" ]
+        volumeMounts:
+          - name: wrapper-server-tools
+            mountPath: /wrapper-server-tools
+        imagePullPolicy: IfNotPresent
+    volumes:
+      - name: wrapper-server-tools
+        emptyDir: {}
+---
+apiVersion: config.porch.kpt.dev/v1alpha1
+kind: ServiceTemplate
+metadata:
+  name: base-service-template
+  namespace: porch-fn-system
+template:
+  spec:
+    ports:
       - port: 9446
         protocol: TCP
         targetPort: 9446
-      selector:
-        fn.kpt.dev/image: to-be-replaced
-      type: ClusterIP
----
-# Need to lookup and access Configmap containing Function Pod Template
-kind: Role
-apiVersion: rbac.authorization.k8s.io/v1
-metadata:
-  name: porch-fn-runner
-  namespace: porch-system
-rules:
-  - apiGroups: [""]
-    resources: ["configmaps"]
-    verbs: ["get", "list"]
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  name: porch-fn-runner
-  namespace: porch-system
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: Role
-  name: porch-fn-runner
-subjects:
-  - kind: ServiceAccount
-    name: porch-fn-runner
+        name: server
+      - port: 9464
+        protocol: TCP
+        targetPort: 9464
+        name: metrics
+    selector:
+      fn.kpt.dev/image: to-be-replaced
+    type: ClusterIP

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,51 @@ 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 choose an executor for each function image and to supply executor-specific settings.
+A FunctionConfig names the function image and optional registry prefixes, then attaches a pod executor, a binary executor, a Go executor, or any combination of the three.
+Tags on each executor select which image versions use that path.
+
+The default Porch install deploys FunctionConfig objects for common catalog functions into `porch-fn-system`.
+porch-server, function-runner, and porch-controllers each run an embedded reconciler that copies those objects into an in-memory store used at evaluation time.
+
+```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
+```
+
+The spec, status, and matching rules are documented in [Function Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md" %}}).
+
 ## 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 through the Engine's function runtime, which picks one of three executors for each function image based on the matching FunctionConfig: an in-process **Go executor**, a **binary executor** running inside the function-runner, or a **pod executor** running the function image in a dedicated Kubernetes pod (the default for arbitrary images).
+See [Function Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md" %}}) for how executors are selected and configured per image.
+
+Regardless of executor, Porch passes the package's resources to [kpt](https://kpt.dev), which passes them 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 order.
+kpt runs the functions sequentially and returns the results to Porch, which stores them in the PackageRevisionResources `status.renderStatus` field.
+Rendering is triggered automatically after creating or cloning a package revision, after updating a package revision, and when a package revision is proposed.
 
 ## When Functions Execute
 
@@ -77,7 +119,8 @@ 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 is configured with FunctionConfig custom resources that select a pod, binary, or Go executor per image tag
+- porch-server, function-runner, and porch-controllers each reconcile FunctionConfig objects into an in-memory store used at evaluation time
 - 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

docs/content/en/docs/3_getting_started/installing-porch.md

@@ -72,15 +72,30 @@ 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 were deployed into the function-pod namespace (default `porch-fn-system`, configured on the function-runner with `--pod-namespace`).
+
+```bash
+kubectl get functionconfigs -n porch-fn-system
+```
+
+A healthy install shows one FunctionConfig per bundled catalog function (apply-replacements, set-namespace, starlark, kubeconform, and others).
+The `Server Applied`, `FnRunner Applied`, and `Controller Applied` columns are the generations each component has loaded. They should match the resource generation when the spec is in sync.
+
+These FunctionConfig objects tell porch-server, function-runner, and porch-controllers which executor (pod, binary, or Go) to use for each function image.
+See [Function Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md" %}}) for the spec
+and [Pod Templates]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/pod-templates.md" %}}) for the `PodTemplate` and `ServiceTemplate` used by the pod executor.
+
 ## Troubleshooting
 
 ### Pods not starting

docs/content/en/docs/5_architecture_and_components/engine/interactions.md

@@ -151,11 +151,14 @@ the draft. The Task handler has no direct repository access.
 
 ### Function Runtime Integration
 
-The task handler uses function runtimes configured in the engine:
+The task handler uses function runtimes configured in the engine.
+FunctionConfig decides which runtime handles a given image (see [Function Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/components/function-runner-config/function-configuration.md" %}})):
 
-- **Builtin Runtime**: For built-in functions (set-namespace, etc.)
-- **gRPC Runtime**: For external function runner service
-- **Multi-Runtime**: Chains multiple runtimes together
+The **builtin runtime** runs compiled-in Go processors (`apply-replacements`, `set-namespace`, `starlark`) for tags listed on `goExecutor`.
+
+The **gRPC runtime** calls the function-runner for everything else (binary fast path, then pod).
+
+The **multi-runtime** tries builtin first and falls back to gRPC.
 
 The engine configures these runtimes during initialization and passes them to the task handler.
 

docs/content/en/docs/5_architecture_and_components/function-runner/design.md

@@ -165,7 +165,7 @@ Choosing between evaluators depends on deployment requirements and function char
 
 **Considerations:**
 - Requires pre-cached function binaries
-- Limited to functions in configuration file
+- Limited to functions listed on a FunctionConfig `binaryExecutor`
 - No container isolation (functions run in runner process)
 - Manual configuration and binary management needed
 
@@ -194,14 +194,14 @@ Function Runner deploys with **pod evaluator by default** when no evaluators are
 **Configuration method:**
 - Use `--disable-runtimes` flag to disable specific evaluators
 - Pod evaluator: No additional configuration needed
-- Executable evaluator: Requires configuration file mapping images to binaries
+- Executable evaluator: Requires FunctionConfig resources with `binaryExecutor` (and binaries under `--functions`)
 - Multi-evaluator: Automatically used when multiple evaluators enabled
 
 ### Migration Considerations
 
 Switching between evaluator configurations requires:
 - Function Runner restart with new flags
-- Executable evaluator requires configuration file with image-to-binary mappings
+- Executable evaluator requires FunctionConfig `binaryExecutor` entries and binaries under `--functions`
 - Pod evaluator requires Kubernetes cluster access and RBAC permissions
 - No data migration needed (evaluators are stateless)
 
@@ -213,7 +213,7 @@ The evaluator implementations differ fundamentally in execution mechanism and pe
 |--------|---------------|----------------------|
 | **Execution Environment** | Kubernetes pods | Local processes |
 | **Startup Latency** | Variable (pod creation, image pull, cluster speed) | Milliseconds (local process spawn) |
-| **Function Discovery** | Dynamic (any image) | Static (configuration file) |
+| **Function Discovery** | Dynamic (any image) | Static (FunctionConfig binaryExecutor) |
 | **Isolation** | Container isolation | Process isolation |
 | **Resource Management** | Kubernetes limits/quotas | OS process limits |
 | **Kubernetes API Load** | High (pod/service CRUD) | None |
@@ -357,20 +357,20 @@ For detailed explanations of how these differences affect operations, see the in
 
 ### Executable Evaluator Configuration
 
-**Decision**: Use static configuration file mapping images to binary paths.
+**Decision**: Use FunctionConfig custom resources to map images to binary paths, watched by an embedded reconciler.
 
 **Rationale:**
-- Simple and explicit configuration
-- No dynamic discovery complexity
-- Clear mapping between function images and binaries
-- Easy to audit and validate
+- Same CRD configures pod, binary, and Go executors
+- Spec changes apply without restarting the function-runner
+- Prefix and tag matching is shared with the builtin runtime
+- Easy to audit with `kubectl get functionconfigs`
 
 **Alternatives considered:**
+- **Static YAML config file**: Required a process restart and drifted from pod-executor settings
 - **Directory scanning**: Implicit mapping, harder to debug
-- **Database storage**: Unnecessary complexity
 - **Dynamic download**: Security and caching concerns
 
 **Trade-offs:**
-- Requires manual configuration updates
-- No automatic discovery of new binaries
-- Configuration must be kept in sync with available binaries
+- Binaries still have to be present under `--functions` (or an absolute path)
+- Duplicate `spec.image` values on different FunctionConfig objects are ignored
+- Only images listed on `binaryExecutor` take the fast path, everything else falls back to pods

docs/content/en/docs/5_architecture_and_components/function-runner/functionality/_index.md

@@ -14,8 +14,8 @@ The Function Runner provides three core functional areas that work together to e
 
 Executes KRM functions through pluggable evaluator strategies:
 - **Evaluator Interface**: Common contract for all function execution strategies
-- **Pod Evaluator**: Executes functions in Kubernetes pods with wrapper server integration
-- **Executable Evaluator**: Runs pre-cached function binaries locally for fast execution
+- **Pod Evaluator**: Executes functions in Kubernetes pods with wrapper server integration; TTL, parallelism, and template overrides come from FunctionConfig
+- **Executable Evaluator**: Runs local binaries listed on FunctionConfig `binaryExecutor` for fast execution
 - **Multi-Evaluator**: Chains evaluators with fallback logic (exec → pod)
 - **Request Channel Pattern**: Channel-based communication for pod cache coordination
 - **Wrapper Server Integration**: gRPC wrapper injected into function pods for structured execution
@@ -27,11 +27,11 @@ For detailed architecture and process flows, see [Function Evaluation]({{% relre
 Manages function execution pods with caching and garbage collection:
 - **Pod Cache Manager**: Orchestrates pod lifecycle via channel-based communication
 - **Pod Manager**: Handles pod and service CRUD operations
-- **Pod Creation**: Template-based pod creation with init container for wrapper server injection
+- **Pod Creation**: Template-based pod creation from base PodTemplate / ServiceTemplate plus FunctionConfig templateOverrides
 - **Service Management**: ClusterIP service frontends for service mesh compatibility
 - **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
+- **Pod Warming**: Pre-creates pods for FunctionConfig images that declare a podExecutor
 
 For detailed architecture and process flows, see [Pod Lifecycle Management]({{% relref "/docs/5_architecture_and_components/function-runner/functionality/pod-lifecycle-management.md" %}}).