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 vector store the gateway fronts, which indexes exist, how worker pools scale, and which stateless functions run against which indexes.

CRDs

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

• VectorStore CRD — the upstream store endpoint, credential reference, and gateway inbound auth policy.
• 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, such as which indexes exist and 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 applies the compute pool chosen by each Pipeline and Function. A pool can set container resources, nodeSelector, and tolerations, so operators can pin CPU, storage-heavy CPU, and GPU work to the right node capacity.

Helm installs cpu, cpu-large, and gpu pools by default. The stock pools select the chart-rendered Karpenter worker pools: layer.hev.dev/node-role=worker-cpu for CPU and layer.hev.dev/node-role=worker-gpu for GPU. The GPU pool also requests nvidia.com/gpu: "1" and carries the standard NVIDIA toleration.

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.