Why the vLLM Pod Needs Host IPC

The vLLM pod must be configured with hostIPC: true. This is a hard requirement, not a tuning option, and when it is missing, everything reports healthy and no caching happens.

The Mechanism

The Inferra SDK inside the vLLM pod (pylcf) does not talk to lcfc over the network. It uses POSIX shared memory in the host's /dev/shm: a pair of request/response rings per client (/dev/shm/lcf-<client>-c<n>-req and -resp) plus a shared data pool (/dev/shm/lcf-pool-*). This is what makes the data path fast enough to be worth using — it avoids a copy through the kernel network stack on every block.

Shared-memory objects live in an IPC namespace. By default a Kubernetes pod gets its own, so the vLLM pod and the lcfc daemon see two different, unrelated /dev/shm. The SDK's shm_open then finds nothing:

LCF SDK connect failed; engine stays on local fallback:
(LcfStatus.PeerUnavailable, 'failed to connect to lcfc: SHM error: nix error: ENOENT: No such file or directory')
The engine does not fail — it silently stops caching

The engine does not fail. It falls back to local-only operation and serves traffic normally, with no Inferra acceleration and no error visible in vLLM's own metrics. A deployment can run in this state indefinitely, and the only symptom is that the cache hit rate never rises.

Setting hostIPC: true puts the vLLM pod in the host's IPC namespace, where lcfc created those objects, and the SDK connects.

A volume mounted at /dev/shm undoes this

Many vLLM manifests mount an emptyDir with medium: Memory at /dev/shm to give the engine more shared memory than the container default. With hostIPC: true that mount sits on top of the host's /dev/shm: the pod sees an empty volume instead of the objects lcfc created, and the SDK fails with the same ENOENT and the same silent fallback. A volume mounted at /dev hides it the same way. Remove the mount — with hostIPC: true the pod already uses the host's /dev/shm, which is not bounded by the container default.

What Is Required vs. What Is an Optimization

Two distinct mechanisms are easy to confuse:

Mechanism

Status

If unavailable

SDK shared-memory rings (pylcf ↔ lcfc via host /dev/shm)

Hard requirement. Needs hostIPC: true on the vLLM pod and on lcfc.

The SDK silently falls back to local-only. No caching at all.

UCX mm same-node transport (an intra-node fast path for data movement)

Optimization. Needs hostIPC: true and hostPID: true on lcfc and lcft.

UCX selects another transport. Slower on that path, still correct.

Only the first is a requirement. If a discussion about shared memory ends with "UCX will just pick something else", the two have been conflated.

Both ends need it, and the chart already does its half

hostIPC is not a property of one pod — it is a property of the pair. The rings live in a namespace, and two processes see the same ring only if both are in that namespace:

Workload

Needs

Set by

Why

lcfc

hostIPC: true

The chart, by default

It creates the POSIX SHM rings and the data pool.

The vLLM pod

hostIPC: true

You

It opens them. This is the half the chart cannot set.

That asymmetry is the whole reason this page exists. Everything on the LCF side is already configured; the serving pod is not ours to configure.

Hyperconverged nodes: the shared-memory transport wants hostPID too

Where lcfc and lcft run on the same host — a hyperconverged deployment — UCX can move data between them over its same-node mm transport instead of the network. That path needs two shared namespaces on both daemons:

Workload

hostIPC

hostPID

lcfc

required

required

lcft

required

required

hostIPC shares the shared-memory segments themselves; hostPID is what makes UCX's peer-liveness check meaningful across a pod boundary — without a shared PID namespace it cannot tell whether the peer holding a segment is still alive, and the transport is disabled rather than risked. The chart ships all four of these true by default, so on a normal install there is nothing to do.

It matters when something takes them away. A restrictive PodSecurity profile that forbids hostPID, or a values file that sets lcfc.hostPID: false, disables the mm transport — correctly, and quietly. Check before you deploy into such a cluster:

kubectl -n "$LCF_NAMESPACE" get pod -l app.kubernetes.io/name=lcfc \
-o jsonpath='{range .items[0]}lcfc hostIPC={.spec.hostIPC} hostPID={.spec.hostPID}{"\n"}{end}'
kubectl -n "$LCF_NAMESPACE" get pod -l app=lcft \
-o jsonpath='{range .items[0]}lcft hostIPC={.spec.hostIPC} hostPID={.spec.hostPID}{"\n"}{end}'

Anything other than true on either line means the same-node fast path is off. Correctness is unaffected — this costs throughput on a colocated hop, not data.

Verifying It

kubectl -n REPLACE_WITH_VLLM_NAMESPACE get pod <vllm-pod> \
-o jsonpath='{.spec.hostIPC}{"\n"}'

An empty result or false means the connector cannot reach lcfc. Confirm the rings are visible from inside the pod:

kubectl -n REPLACE_WITH_VLLM_NAMESPACE exec <vllm-pod> -- ls /dev/shm | grep '^lcf-'

Nothing listed, on a cluster whose lcfc pods are running, means the IPC namespace is not shared — or that a volume is mounted over /dev/shm. This lists any such mount; it should not print anything:

kubectl -n REPLACE_WITH_VLLM_NAMESPACE get pod <vllm-pod> \
-o jsonpath='{range .spec.containers[*].volumeMounts[*]}{.mountPath}{"\n"}{end}' \
| grep -xE '/dev(/shm)?/?'
The lcfc side is already configured for this

The chart runs lcfc with hostIPC: true by default, precisely so that SDK clients see the same POSIX SHM namespace. Enabling hostIPC on the vLLM pod is the half you have to do. If the rings are still not visible with both in place, contact Lightbits Support rather than changing lcfc's shared-memory settings.

The pod-spec fragment that sets this, alongside the socket and runtime mounts, is in Connector Environment and Launch Flags.