Envoy Overload Management Failure Modes: Resource Monitors, Trigger Thresholds, Action Ordering, and Graceful Degradation Boundaries

Envoy overload manager는 memory pressure 같은 로컬 자원 상태를 주기적으로 읽고, configured trigger threshold에 따라 여러 overload action을 켜서 proxy를 단계적으로 열화시키는 보호 장치다. 핵심은 “과부하가 오면 Envoy가 자동으로 안전해진다”가 아니라, resource monitor 선택, refresh interval, threshold 간격, action별 영향 범위, listener

Summary#

Envoy overload manager는 memory pressure 같은 로컬 자원 상태를 주기적으로 읽고, configured trigger threshold에 따라 여러 overload action을 켜서 proxy를 단계적으로 열화시키는 보호 장치다. 핵심은 “과부하가 오면 Envoy가 자동으로 안전해진다”가 아니라, resource monitor 선택, refresh interval, threshold 간격, action별 영향 범위, listener/connection/request 경계를 운영자가 명시적으로 설계해야 한다는 점이다.

가장 중요한 failure mode는 네 가지다.

모니터가 실제 병목 자원을 대표하지 못하면 overload action은 너무 늦게 또는 너무 자주 발동한다.
trigger threshold가 촘촘하지 않거나 action별 순서가 설계되지 않으면 graceful degradation 대신 갑작스러운 503, connection close, listener accept 중단으로 보일 수 있다.
reduce_timeouts, disable_http_keepalive, stop_accepting_requests, stop_accepting_connections류 action의 경계가 다르기 때문에 어떤 요청·연결·listener가 영향을 받는지 혼동하면 장애 대응이 예측 불가능해진다.
overload manager는 마지막 방어선이지 capacity planning, upstream backpressure, retry/circuit-breaker 설계를 대체하지 않는다.

Key Points#

Overload manager의 기본 모델은 “resource monitor → pressure value → trigger → action”이다.
Envoy overload manager는 하나 이상의 resource monitor를 설정하고, 각 monitor가 보고하는 resource pressure를 기반으로 overload action을 활성화한다.
action은 보통 특정 resource의 threshold trigger 또는 scaled trigger에 묶인다.
따라서 failure 분석의 출발점은 “어떤 자원을 보고 있는가”와 “그 자원이 실제 장애 원인을 얼마나 잘 대표하는가”다.
fixed_heap monitor는 단순하지만 container memory 현실을 완전히 반영하지 않을 수 있다.
fixed_heap resource monitor는 Envoy heap 사용량을 고정 heap limit 대비 pressure로 계산하는 방식이다.
장점은 예측 가능하고 설정이 단순하다는 점이다.
하지만 container cgroup limit, non-heap memory, kernel/socket buffer, mmap, shared library, sidecar 전체 RSS 같은 요소를 그대로 대표한다고 보기 어렵다.
failure mode: heap 기준으로는 아직 여유가 있어 overload action이 늦게 켜지지만, 실제 container memory limit에는 먼저 도달해 OOMKill이 발생할 수 있다.
cgroup_memory monitor는 container 환경에 더 맞지만 배포 환경 의존성이 크다.
cgroup 기반 monitor는 cgroup memory 사용량과 limit을 바탕으로 memory pressure를 산출하는 용도다.
Kubernetes나 containerized Envoy에서는 fixed heap보다 실제 memory limit에 가까운 신호를 줄 수 있다.
다만 cgroup v1/v2, runtime, host mount, 권한, limit 설정 방식에 따라 기대와 다르게 동작할 수 있다.
failure mode: cgroup 경로 또는 limit 인식이 잘못되면 pressure가 0에 가깝거나 과도하게 높게 계산되어 action이 무력화되거나 상시 발동할 수 있다.
injected_resource monitor는 테스트와 통제된 주입에는 유용하지만 production signal로 오해하면 위험하다.
injected resource monitor는 외부에서 resource pressure 값을 주입하는 형태로 overload behavior를 테스트하거나 제어하는 데 쓸 수 있다.
이는 실제 memory/CPU/socket 상태를 자동 측정하는 monitor가 아니다.
failure mode: 테스트용 injected pressure 설정이 production에 남아 있거나, 외부 control loop가 잘못된 값을 주입하면 Envoy가 실제 과부하가 아닌데도 요청을 거부하거나 연결을 닫을 수 있다.
refresh_interval은 빠른 보호와 noise/churn 사이의 절충점이다.
overload manager는 resource monitor를 주기적으로 refresh한다.
refresh interval이 너무 길면 memory spike나 connection surge에 늦게 반응한다.
너무 짧으면 일시적 pressure 변화에 action이 자주 켜지고 꺼져 keepalive disable, timeout 축소, request rejection 같은 동작이 불안정하게 보일 수 있다.
운영적으로는 Envoy heap/RSS 증가 속도, autoscaling 반응 시간, client retry behavior, upstream timeout budget과 함께 조정해야 한다.
threshold trigger는 on/off 스위치이고, scaled trigger는 점진적 감쇠에 가깝다.
threshold trigger는 pressure가 특정 값을 넘으면 action을 활성화한다.
scaled trigger는 scaling threshold와 saturation threshold 사이에서 0~1 범위의 scale 값을 만든다.
reduce_timeouts 같은 action은 scaled trigger와 결합할 때 “갑자기 timeout을 줄이는” 대신 pressure가 높아질수록 timeout budget을 점진적으로 줄이는 설계가 가능하다.
failure mode: 모든 action을 같은 threshold에 묶으면 graceful degradation 단계가 사라지고, 특정 pressure 지점에서 여러 보호 동작이 동시에 터진다.
action ordering은 Envoy의 암묵적 우선순위에 맡기기보다 threshold 계층으로 설계해야 한다.
overload action들은 각자의 trigger 조건이 만족되면 활성화된다.
운영자가 기대하는 순서, 예를 들어 “먼저 timeout 축소 → keepalive 비활성화 → 신규 요청 거부 → 신규 connection accept 중단” 같은 단계는 action별 threshold를 다르게 설정해 만들어야 한다.
failure mode: disable_http_keepalive, stop_accepting_requests, stop_accepting_connections를 같은 pressure threshold에 두면, client 입장에서는 연결 재사용 감소, 503, 연결 실패가 동시에 발생해 원인 파악이 어려워진다.
reduce_timeouts는 기존 capacity를 지키기 위한 조기 포기 장치이지, 처리량을 늘리는 장치가 아니다.
이 action은 overload pressure에 따라 configured timeout을 줄여 long-running request가 Envoy 자원을 오래 점유하지 않도록 돕는다.
적절히 쓰면 tail-latency request가 memory/connection/stream 자원을 오래 붙잡는 상황을 완화할 수 있다.
failure mode: timeout 축소가 client retry와 결합되면 upstream 시도 횟수 또는 downstream 재요청이 늘어 전체 부하가 증가할 수 있다.
특히 retry budget, route timeout, per-try timeout, gRPC deadline과 함께 검토해야 한다.
disable_http_keepalive는 신규 connection pressure를 늘릴 수 있는 양면적 action이다.
keepalive를 끄면 기존 HTTP 연결 재사용을 줄이고 client가 연결을 오래 붙잡지 않도록 유도할 수 있다.
하지만 client가 즉시 새 connection을 만들면 TLS handshake, listener accept, socket, CPU 사용량이 늘 수 있다.
failure mode: memory pressure를 줄이려 keepalive를 비활성화했는데, 대규모 client fleet이 reconnect storm을 만들면 CPU와 listener backlog 문제가 커질 수 있다.
stop_accepting_requests와 connection-level action은 영향 경계가 다르다.
request-level 거부는 Envoy가 연결을 받아도 특정 시점 이후 요청 처리 자체를 제한하는 형태로 나타난다.
connection/listener accept 중단 계열 action은 신규 downstream connection 유입을 더 앞단에서 막는 성격이 강하다.
failure mode: HTTP/2나 HTTP/3처럼 하나의 connection에 여러 stream/request가 multiplex되는 경우, “신규 연결 차단”과 “신규 요청 거부”의 효과가 다르게 나타난다.
따라서 protocol별로 overload action의 사용자 체감이 다를 수 있다.
listener disable/stop accepting 계열은 최후 단계로 두는 것이 일반적으로 안전하다.
신규 요청이나 신규 connection을 막는 action은 Envoy 자신을 보호하는 데 효과적이지만, 외부에서는 즉시 availability 저하로 보인다.
readiness probe, load balancer outlier/ejection, Kubernetes endpoint removal, upstream retry policy와 맞물리면 traffic이 다른 Envoy instance로 급격히 이동할 수 있다.
failure mode: 한 Envoy가 overload action으로 유입을 막자 같은 pool의 다른 Envoy로 부하가 이동하고, 연쇄 overload가 발생한다.
graceful degradation boundary는 “기존 요청 보존”과 “새 작업 차단” 사이에서 정해야 한다.
좋은 overload 설계는 이미 처리 중인 짧은 요청은 가능한 한 끝내고, 자원을 오래 점유할 가능성이 큰 새 작업·긴 작업·idle keepalive부터 줄이는 방향이다.
하지만 Envoy action만으로 business priority, idempotency, tenant별 중요도, request cost를 완전히 알 수는 없다.
중요 API와 bulk/low-priority API를 같은 listener/route/timeout 정책으로 묶으면 overload 시 모두 같은 방식으로 열화된다.
관측 지표 없이 threshold를 정하면 overload manager는 “블랙박스 거부기”가 된다.
최소한 resource pressure, overload action active state, downstream connection/request rejection, timeout, 503, reset, memory/RSS/heap, listener accept 상태를 함께 봐야 한다.
action이 발동한 시점과 client retry 증가, upstream latency, pod OOMKill, autoscaler event를 시간축으로 맞춰야 한다.
운영 runbook에는 “어떤 threshold에서 어떤 user-visible behavior가 발생하는가”가 명시되어야 한다.

Cautions#

이 초안은 공개 Envoy 문서와 API reference 기반의 private capsule 초안이며, 특정 조직의 production 장애 사례를 검증한 것이 아니다.
Envoy overload manager의 action 이름, 세부 동작, 기본값, extension availability는 Envoy 버전에 따라 달라질 수 있다. 실제 적용 전 사용 중인 Envoy 버전의 generated API docs를 확인해야 한다.
fixed_heap, cgroup_memory, injected_resource monitor 중 어느 것이 “정답”인지는 배포 형태에 따라 다르다. bare metal, VM, Kubernetes sidecar, gateway deployment에서 pressure signal의 의미가 달라질 수 있다.
공개 문서만으로는 특정 threshold 값, 예를 들어 0.85 또는 0.95가 보편적으로 안전하다고 일반화할 수 없다. threshold는 load test와 failure injection으로 검증해야 한다.
disable_http_keepalive는 항상 부하를 줄인다고 단정할 수 없다. client reconnect behavior에 따라 connection churn과 CPU 부하를 키울 수 있다.
reduce_timeouts는 overload 상황의 자원 점유 시간을 줄일 수 있지만, retry policy가 공격적이면 더 많은 재시도와 upstream 부하를 유발할 수 있다.
listener/request 차단 action은 Envoy instance를 보호하지만, load balancer가 traffic을 다른 instance로 옮기면 cluster-wide cascading overload가 생길 수 있다.
graceful degradation은 Envoy overload manager만으로 완성되지 않는다. route priority, retry budget, circuit breaker, admission control, autoscaling, load shedding policy가 함께 설계되어야 한다.

Sources#

https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/overload_manager/overload_manager
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/overload/v3/overload.proto
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/resource_monitors/fixed_heap/v3/fixed_heap.proto
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/resource_monitors/cgroup_memory/v3/cgroup_memory.proto
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/resource_monitors/injected_resource/v3/injected_resource.proto

Sagwan Revalidation 2026-07-25T08:14:25Z#

verdict: ok
note: 핵심 모델과 fixed_heap 한계, action 경계 설명은 현재도 유효함

Sagwan Revalidation 2026-07-27T13:04:42Z#

verdict: ok
note: 최근 변경 징후 없고 Envoy overload manager 개념·주의점이 여전히 유효함

Sagwan Revalidation 2026-07-29T17:32:50Z#

verdict: ok
note: Envoy 과부하 관리자 모델과 주요 action 경계 설명은 여전히 유효함

Sagwan Revalidation 2026-08-01T03:35:31Z#

verdict: ok
note: Envoy overload manager 모델과 주요 action 설명이 여전히 유효함