Operations

VectorStore CRD

A VectorStore is the gateway’s upstream connection. It names the store kind, endpoint, credential Secret, and the inbound auth policy the gateway applies to client requests. An install may define more than one VectorStore; each Index.spec.backend.storeRef selects which store serves that upstream namespace.

apiVersion: hevlayer.com/v1alpha1
kind: VectorStore
metadata:
  name: turbopuffer-default
  namespace: layer
spec:
  kind: turbopuffer
  default: true
  endpoint:
    url: https://aws-us-east-1.turbopuffer.com
    region: aws-us-east-1
  turbopuffer:
    orgId: org_123
  credential:
    secretRef:
      name: layer
      key: turbopuffer-api-key
  inboundAuth:
    mode: deriveFromStore

Standalone config

Why this exists: the open layer (CE) runs standalone — Docker, Compose, or a bare binary — with no Kubernetes control plane available. Config-derived resolution gives those deployments the exact same VectorStore vocabulary as a cluster install: one schema, two entry points, so a standalone config file promotes to a CR (and back) without rewrites.

Standalone and compose runs do not need Kubernetes to resolve VectorStores. Set LAYER_STORE_FILE to a YAML or JSON file containing the same resource shape as the CR:

apiVersion: hevlayer.com/v1alpha1
kind: VectorStore
metadata:
  name: turbopuffer-default
spec:
  kind: turbopuffer
  default: true
  endpoint:
    url: https://api.turbopuffer.com
    region: aws-us-east-1
  credential:
    secretRef:
      name: layer
      key: turbopuffer-api-key
  inboundAuth:
    mode: deriveFromStore

For this example, set LAYER_SECRET_LAYER_TURBOPUFFER_API_KEY=tpuf_... before starting the gateway. The env var name is LAYER_SECRET_ plus the Secret name and key uppercased, with punctuation replaced by underscores.

For more than one store, use a Kubernetes-style list:

apiVersion: v1
kind: List
items:
  - apiVersion: hevlayer.com/v1alpha1
    kind: VectorStore
    metadata:
      name: turbopuffer-default
    spec:
      kind: turbopuffer
      default: true
      endpoint:
        url: https://api.turbopuffer.com
        region: aws-us-east-1
      credential:
        secretRef:
          name: layer
          key: turbopuffer-api-key
      inboundAuth:
        mode: deriveFromStore

The standalone file mirrors the CR schema. Kubernetes installs read credential.secretRef from the cluster; standalone runs resolve the same secretRef from env. Inline LAYER_STORE_JSON accepts the same resource shape for short-lived local runs. If neither variable is set, the gateway uses a single default turbopuffer store and derives inbound auth from the request bearer.

Connection

Field	Purpose
`kind`	The backend engine. `turbopuffer` today. `pinecone` is reserved by the schema but rejected by the operator until implemented.
`default`	Marks the store used when an `Index` omits `spec.backend.storeRef`. A single store is treated as the default.
`endpoint.url`	Upstream API base URL.
`endpoint.region`	Operator-visible region label for this store.
`turbopuffer.orgId`	Optional turbopuffer organization id for dashboard deep links and support orientation. It is not used for auth or routing.
`credential.secretRef`	Secret key in the same namespace as the `VectorStore`. The credential is never stored in the CRD.

Routing

The gateway builds one upstream client per VectorStore in the namespace. Requests whose namespace has an Index with spec.backend.storeRef use that store; other namespaces use the default store. Two Index objects cannot resolve to the same upstream namespace.

Inbound auth

inboundAuth.mode controls what bearer token the gateway accepts:

Mode	Behavior
`deriveFromStore`	Default. The gateway accepts the default store’s credential as the inbound bearer. This is the single-tenant BYOC shape.
`keys`	The gateway accepts the listed independent key Secrets and enforces their `read`, `write`, and `admin` scopes.
`open`	No inbound auth. Use only for explicitly open environments.

Under deriveFromStore, clients set Authorization: Bearer <store key> when calling the gateway. Operator-managed workers and KEDA use the same Secret through LAYER_GATEWAY_API_KEY.

Under keys, each key points at a Secret in the same namespace:

spec:
  inboundAuth:
    mode: keys
    keys:
      - name: shop-rw
        scopes: [read, write]
        secretRef:
          name: layer
          key: layer-inbound-shop-rw-api-key

read covers GET/HEAD routes and read-shaped POST routes such as query, batch fetch, scans, and metrics proxy queries. write covers namespace writes and worker queue claim/complete routes. admin covers Pipeline and Function create/delete/control routes and also satisfies read and write.

In every mode the gateway also accepts a minted ApiKey token whose vectorstore.<name> entitlement names this store, enforcing that entitlement’s scopes and namespace globs.

Status

The operator sets status.reachable and a Ready condition after validating the Secret references and probing GET /v1/namespaces on the store endpoint.