cachebackend-events-only.yaml

# SPDX-FileCopyrightText: 2026 The inference-cache Authors
#
# SPDX-License-Identifier: Apache-2.0

# An events-only (tier-1 routing) CacheBackend. This is the lighter,
# routing-only integration: cache-aware routing is wired, but NO KV-offload
# connector is loaded into the engine and NO backend server is provisioned.
#
# Set spec.integration.mode: EventsOnly to select it. Compared to the default
# Offload mode (see cachebackend-lmcache.yaml), the controller here:
#   - provisions NO remote-storage Deployment or Service, and leaves
#     connector/remote-storage status empty (there is no server address), and
#   - injects NO KV-offload connector or MP server into the engine Pod
#     container.
# The mutating Pod webhook appends the kvevent-subscriber sidecar to matched
# engine pods — but only when the controller runs with --kvevent-subscriber-image
# set (empty by default; see the readiness note below) and observation.modelID
# is present; otherwise it skips the append fail-open. Once appended, LookupRoute
# and status.indexParticipation behave exactly like a managed backend — only the
# offload tier is absent. (In this mode the subscriber forwards evictions instead
# of suppressing them: there is no L2 tier holding the block after the engine
# drops it, so a removed block genuinely means the prefix is gone.)
#
# WHY use it: this is the supported integration for hybrid-attention models
# that cannot take a vLLM KV connector — Qwen3.6/Next gated-DeltaNet,
# Mamba/Jamba, KDA, Falcon-H, Granite-hybrid, and similar. vLLM disables its
# hybrid KV-cache manager the moment any KV connector is loaded (KV-spec
# unification then fails at init), so they cannot take the tier-2 connector;
# but their KV events coexist fine with the hybrid manager, so routing still
# works. It is also a lighter deployment for routing-only users who do not want
# an offload tier at all.
#
# Like a managed backend, an events-only backend is gated on the first KV event:
# it sits Ready=False/AwaitingFirstKVEvent until the auto-attached
# kvevent-subscriber reports an event (requires the controller to run with
# --kvevent-subscriber-image set; empty by default), then flips to
# Ready=True/KVEventsObserved. Connector and remote-storage status stay empty.
#
# EventsOnly takes precedence over host-tier/offload configuration. Omit
# spec.lmCache and spec.remoteStorage: no LMCache host tier is configured, and
# admission rejects a remote provider because no connector would dial it.
# There is no backend workload to scale in this mode.
apiVersion: inferencecache.io/v1alpha1
kind: CacheBackend
metadata:
  labels:
    app.kubernetes.io/name: inference-cache
  name: cachebackend-events-only
spec:
  runtime: VLLM
  type: LMCache
  integration:
    # Routing-only: no KV connector, no provisioned server.
    mode: EventsOnly
  engineSelector:
    matchLabels:
      inferencecache.io/cache-domain: vllm-events-only
  observation:
    # Served model identifier the matched engine pods are loaded with. Plumbed
    # to the auto-attached kvevent-subscriber sidecar's --model-id so the index
    # keys per-replica entries by model. A hybrid-attention model is the
    # canonical events-only use case.
    modelID: Qwen/Qwen3-Next-80B-A3B-Instruct
  # No remoteStorage: events-only has no shared cache tier.