Operator Overview

layer-operator manages declarative state for your hev layer deployment. It serves a few crucial functions — monitoring for changes to your indexes and managing scaling. It does this through a set of abstractions known as custom resource definitions (CRDs).

The gateway handles the read and write path; the operator handles everything that wants to be expressed as desired state in the cluster: which indexes exist, how worker pools scale, and which stateless functions run against which indexes.

CRDs

The operator reconciles four resource kinds, each documented on its own page:

• Index CRD — one resource per Turbopuffer namespace the gateway should manage.
• InfraRules CRD — cluster-wide compute pools, document cache rules, and shared scaling policy.
• Pipeline CRD — staged work that changes row count.
• Function CRD — stateless user-defined functions that read and write attributes on an index.

Relationship to the gateway

The gateway and the operator are decoupled. The operator reconciles declarative state; the gateway serves the read and write path. Neither sits in the other’s hot path, so the gateway keeps serving even if the operator is restarted or lagging.

The link between them is one-directional and read-only. For some features the gateway reads CRD status — which indexes exist, which worker pools are ready — to inform what it serves. It never writes to the CRDs; declarative state is authored by you and reconciled by the operator, and the gateway is only ever a reader of it.

Scheduling and node pools

The operator is opinionated about where the workers it creates run. It does not schedule Pipeline and Function pods onto general cluster capacity — each compute pool pins to a dedicated, labeled node pool via nodeSelector and tolerations, so CPU and GPU work land on the right nodes and stay isolated from the rest of your cluster. The shipped defaults assume Karpenter and select on the karpenter.sh/nodepool label, but any labeled node pool works.

This is configured once on InfraRules/default, not per workload — see InfraRules for the compute-pool fields and how Pipelines and Functions choose a pool.