feat: bound the KCL native (off-heap) memory growth in-process

function-kcl recompiles the whole KCL module on every reconcile. The native
KCL runtime (loaded via dlopen/cgo) accumulates off-heap memory per compile
that Go's GC, GOGC and GOMEMLIMIT cannot bound, so long-lived pods climb to
their memory limit and get OOMKilled mid-render, dropping reconciles
(connection reset / DeadlineExceeded). A true compile cache
(BuildProgram/ExecArtifact) is not reachable through the native C-ABI this
function uses, so this bounds the growth at a process boundary instead, with
two complementary, opt-in mechanisms (both nil-safe and default-off):

* recycle.go — a watchdog samples process RSS (incl. native off-heap memory)
  plus optional reconcile-count / lifetime limits; on threshold it stops
  accepting new reconciles, drains in-flight ones, and exits 0 so the
  orchestrator restarts the pod cleanly between renders instead of OOMKilling
  it during one. Defaults to 85% of the detected cgroup limit.

* rendercache.go — memoises the KCL pipeline output keyed on the exact
  serialized input. A composition function is deterministic over its input, so
  byte-identical reconciles return the cached output without invoking the KCL
  runtime, skipping the recompile and a leak increment. Opt-in via
  FUNCTION_KCL_RENDER_CACHE_SIZE; bounded LRU with optional TTL.

grpc is promoted to a direct dependency for codes/status.

Signed-off-by: Callum MacDonald <callum@stakater.com>

Author: callum-stakater

fn.go

@@ -11,6 +11,8 @@ import (
 
 	"github.com/crossplane/crossplane-runtime/v2/pkg/errors"
 	"github.com/crossplane/crossplane-runtime/v2/pkg/logging"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 	"google.golang.org/protobuf/types/known/structpb"
 	"k8s.io/apimachinery/pkg/runtime"
 	"kcl-lang.io/krm-kcl/pkg/api"
@@ -42,10 +44,20 @@ type Function struct {
 
 	log          logging.Logger
 	dependencies string
+	recycler     *recycler
+	cache        *renderCache
 }
 
 // RunFunction runs the Function.
 func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest) (*fnv1.RunFunctionResponse, error) {
+	// Reject new work while the process is draining for a memory recycle so
+	// Crossplane retries this reconcile elsewhere instead of having it cut off
+	// mid-render. begin() also bounds the recycle drain to in-flight calls.
+	if !f.recycler.begin() {
+		return nil, status.Error(codes.Unavailable, "function-kcl is recycling to release native memory; retry")
+	}
+	defer f.recycler.end()
+
 	log := f.log.WithValues("tag", req.GetMeta().GetTag())
 	log.Debug("Running Function")
 
@@ -189,7 +201,6 @@ func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest)
 		response.Fatal(rsp, err)
 		return rsp, nil
 	}
-	inputBytes, outputBytes := bytes.NewBuffer([]byte{}), bytes.NewBuffer([]byte{})
 	// Convert the function-kcl KCLInput to the KRM-KCL spec and run function pipelines.
 	// Input Example: https://github.com/kcl-lang/krm-kcl/blob/main/examples/mutation/set-annotations/suite/good.yaml
 	in.APIVersion = v1alpha1.KCLRunAPIVersion
@@ -200,16 +211,28 @@ func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest)
 		response.Fatal(rsp, errors.Wrap(err, "cannot marshal input to yaml"))
 		return rsp, nil
 	}
-	inputBytes.Write(kclRunBytes)
-	// Run pipeline to get the result mutated or validated by the KCL source.
-	pipeline := kio.NewPipeline(inputBytes, outputBytes, false)
-
-	if err := pipeline.Execute(); err != nil {
-		response.Fatal(rsp, errors.Wrap(err, "failed to run kcl function pipelines"))
-		return rsp, nil
+	// The KCL render is deterministic over kclRunBytes (source + dependencies +
+	// all params + config). Reuse the previous output for byte-identical inputs
+	// to skip recompiling the module — this avoids both the CPU cost and a native
+	// memory-leak increment on no-op re-syncs. See rendercache.go.
+	var outputData []byte
+	if cached, ok := f.cache.lookup(kclRunBytes); ok {
+		outputData = cached
+		hits, misses := f.cache.stats()
+		log.Debug("render cache hit", "hits", hits, "misses", misses)
+	} else {
+		inputBytes, outputBytes := bytes.NewBuffer(kclRunBytes), bytes.NewBuffer([]byte{})
+		// Run pipeline to get the result mutated or validated by the KCL source.
+		pipeline := kio.NewPipeline(inputBytes, outputBytes, false)
+		if err := pipeline.Execute(); err != nil {
+			response.Fatal(rsp, errors.Wrap(err, "failed to run kcl function pipelines"))
+			return rsp, nil
+		}
+		outputData = outputBytes.Bytes()
+		f.cache.store(kclRunBytes, outputData)
 	}
-	log.Debug(fmt.Sprintf("Pipeline output: %v", outputBytes.String()))
-	data, err := pkgresource.DataResourcesFromYaml(outputBytes.Bytes())
+	log.Debug(fmt.Sprintf("Pipeline output: %v", string(outputData)))
+	data, err := pkgresource.DataResourcesFromYaml(outputData)
 	if err != nil {
 		response.Fatal(rsp, errors.Wrapf(err, "cannot parse data resources from the pipeline output in %T", rsp))
 		return rsp, nil

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/go-logr/logr v1.4.3
 	github.com/google/go-cmp v0.7.0
 	github.com/pkg/errors v0.9.1
+	google.golang.org/grpc v1.78.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v2 v2.4.0
 	k8s.io/apimachinery v0.35.4
@@ -244,7 +245,6 @@ require (
 	google.golang.org/genproto v0.0.0-20260128011058-8636f8732409 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260203192932-546029d2fa20 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20 // indirect
-	google.golang.org/grpc v1.78.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

main.go

@@ -36,7 +36,18 @@ func (c *CLI) Run() error {
 	if err != nil {
 		return err
 	}
-	return function.Serve(&Function{dependencies: dependencies, log: log},
+	// Watchdog that recycles the process before the KCL native memory leak can
+	// OOMKill it mid-reconcile. Configured via FUNCTION_KCL_MAX_* env vars;
+	// no-op when no trigger is enabled.
+	rec := newRecycler(log, recycleConfigFromEnv())
+	rec.run()
+	// Optional render cache: memoise KCL output for byte-identical reconciles to
+	// skip recompilation (CPU + leak). Enabled via FUNCTION_KCL_RENDER_CACHE_SIZE.
+	cache := newRenderCacheFromEnv()
+	if cache.enabled() {
+		log.Info("render cache enabled", "maxEntries", cache.max, "ttl", cache.ttl.String())
+	}
+	return function.Serve(&Function{dependencies: dependencies, log: log, recycler: rec, cache: cache},
 		function.Listen(c.Network, c.Address),
 		function.MTLSCertificates(c.TLSCertsDir),
 		function.Insecure(c.Insecure),