recipe-external-cache.yaml

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

# Recipe: External Redis L3 — point the MP server at Redis you manage.
#
# Scenario: you already run Redis and do not want the controller to provision
# it. External ownership skips the remote-provider Deployment and Service. The
# pod webhook still injects one PodLocal LMCache MP server per engine Pod, and
# that server connects to the explicit RESP endpoint.
#
# Admission rules for External ownership:
#   * remoteStorage.endpoint is REQUIRED for External ownership and REJECTED
#     for Managed ownership. Redis accepts bare `host:port`.
#     A non-empty port is required; IPv6 literals must be bracketed ([::1]:8200).
#   * If the endpoint resolves to an in-cluster Service in a DIFFERENT namespace
#     than this CR, set `spec.allowCrossNamespace: true` to acknowledge the
#     tenancy boundary. The rule does not fire for external hostnames / IPs.
#   * The controller does NOT probe the endpoint — it trusts the operator.
#
# This recipe ships only the CacheBackend + a matching engine Deployment; the
# Redis itself is assumed to already exist at the endpoint below.
#
# OBSERVABILITY PREREQUISITE: per-replica index entries are reported only when
# the kvevent-subscriber sidecar is auto-attached, which (as for managed
# backends) requires the controller to run with --kvevent-subscriber-image set
# (empty by default). Without it the engine is wired to the external cache (KV
# reuse works) but no KV events / index entries are reported. See docs/quickstart.md.
#
# External backends are EXEMPT from both readiness gates that apply to managed
# backends: the KV-event gate (Ready=True comes from admission accepting the
# endpoint, not from an observed event) AND the functional-probe gate
# (FunctionalProbeOK is never published — the controller does not drive a
# round-trip against a cache it does not manage). The condition will not
# appear in this CR's .status.conditions[] under any circumstances.
apiVersion: inferencecache.io/v1alpha1
kind: CacheBackend
metadata:
  name: external-cache
spec:
  runtime: VLLM
  type: LMCache
  integration:
    role: ReadWrite
  engineSelector:
    matchLabels:
      inferencecache.io/cache-domain: external-demo
  lmCache:
    topology: PodLocal
    chunkSizeTokens: 256
    podLocal:
      server:
        image: docker.io/lmcache/standalone@sha256:b813bf0bb616d1012b6a6edcbd4a44f1576dbbdaa857962e56d48b9f7c127d13
        port: 5555
        l1Capacity: 2Gi
        maxWorkers: 4
        resources:
          requests:
            cpu: "1"
            memory: 3Gi
          limits:
            cpu: "2"
            memory: 4Gi
  observation:
    # Model the engine pods load — keys per-replica index entries when the
    # subscriber sidecar is attached (see the prerequisite note above).
    modelID: Qwen/Qwen2.5-0.5B-Instruct
  remoteStorage:
    provider: Redis
    ownership: External
    # Address of the pre-existing Redis service you manage. Swap for your own.
    endpoint: redis.example.internal:6379
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: external-demo-engine
  labels:
    app: external-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: external-demo
  template:
    metadata:
      labels:
        app: external-demo
        inferencecache.io/cache-domain: external-demo
    spec:
      nodeSelector:
        kubernetes.io/arch: amd64    # arm64 hosts: change to `arm64`
      containers:
        - name: vllm
          image: vllm/vllm-openai-cpu:latest-x86_64   # `:latest-arm64` on Apple Silicon
          imagePullPolicy: IfNotPresent
          command: ["vllm", "serve", "Qwen/Qwen2.5-0.5B-Instruct"]
          args:
            - "--port=8000"
            - "--dtype=bfloat16"
            - "--max-model-len=8192"
            - "--enforce-eager"
            - "--enable-prefix-caching"
            - "--kv-events-config"
            - '{"enable_kv_cache_events":true,"publisher":"zmq","endpoint":"tcp://*:5557","replay_endpoint":"tcp://*:5558","buffer_steps":10000,"topic":"kv-events"}'
          env:
            - name: VLLM_CPU_KVCACHE_SPACE
              value: "4"
          ports:
            - { name: http, containerPort: 8000 }
            - { name: kv-events, containerPort: 5557 }
            - { name: kv-replay, containerPort: 5558 }
          readinessProbe:
            httpGet: { path: /health, port: http }
            initialDelaySeconds: 60
            periodSeconds: 10
            failureThreshold: 120
          resources:
            requests:
              cpu: "500m"
              memory: "6Gi"
          volumeMounts:
            - { name: cache-home, mountPath: /root/.cache/huggingface }
            - { name: shm, mountPath: /dev/shm }
      volumes:
        - name: cache-home
          emptyDir: {}
        - name: shm
          emptyDir:
            medium: Memory
            sizeLimit: 4Gi