Overload Manager

The Overload Manager protects Envoy Proxy instances from resource exhaustion by taking protective actions when memory or connection limits are reached. This prevents OOMKills and cascading failures.

Why Overload Manager?

Envoy manages its own heap memory separate from container limits. Without overload protection:

Envoy’s heap can grow beyond container memory limits
Kubernetes OOMKills the pod abruptly
All connections are dropped immediately
Traffic shifts suddenly to remaining pods, potentially triggering more OOMKills

The Overload Manager monitors resource usage and takes graceful protective actions before limits are reached.

Configuration

Configure the Overload Manager in the Config CRD under spec.envoyProxy.overloadManager:

apiVersion: kubelb.k8c.io/v1alpha1
kind: Config
metadata:
  name: default
  namespace: kubelb
spec:
  envoyProxy:
    overloadManager:
      enabled: true
      maxHeapSizeBytes: 1073741824  # 1GB
      maxActiveDownstreamConnections: 50000

Configuration Fields

Field	Type	Default	Description
`enabled`	bool	`false`	Must be explicitly enabled
`maxHeapSizeBytes`	uint64	-	Memory threshold in bytes that triggers overload actions
`maxActiveDownstreamConnections`	uint64	-	Maximum number of downstream (client) connections

Protective Actions

When thresholds are reached, Envoy takes these protective actions:

Trigger	Action
Heap size approaches `maxHeapSizeBytes`	Returns HTTP 503 to new requests
Heap size approaches `maxHeapSizeBytes`	Sends GOAWAY frames to drain HTTP/2 connections
Connections reach `maxActiveDownstreamConnections`	Rejects new network connections

Best Practices

Set Heap Below Container Limit

Always configure maxHeapSizeBytes below your container’s memory limit to give Envoy room to drain gracefully:

apiVersion: kubelb.k8c.io/v1alpha1
kind: Config
metadata:
  name: default
  namespace: kubelb
spec:
  envoyProxy:
    resources:
      limits:
        memory: 2Gi
    overloadManager:
      enabled: true
      # Set to ~80% of container limit
      maxHeapSizeBytes: 1717986918  # ~1.6GB

Scale Connection Limits with Replicas

Connection limits should account for your expected traffic distributed across replicas:

apiVersion: kubelb.k8c.io/v1alpha1
kind: Config
metadata:
  name: default
  namespace: kubelb
spec:
  envoyProxy:
    replicas: 3
    overloadManager:
      enabled: true
      # 50k per pod = 150k total across 3 replicas
      maxActiveDownstreamConnections: 50000

Sizing Examples

The configuration shape is identical across environments; only the values change:

Memory-constrained: memory limit 512Mi, maxHeapSizeBytes: 402653184 (384MB, ~75% of the limit), maxActiveDownstreamConnections: 10000.
High-traffic: 5 replicas, memory limit 4Gi, maxHeapSizeBytes: 3221225472 (3GB), maxActiveDownstreamConnections: 100000.