Envoy xDS Rollout Failure Modes: Cluster Warming, Stale EDS State, Route Shadowing, and Hot Restart Drain Boundaries

Envoy xDS rollout failure는 “새 설정을 받았다”와 “트래픽이 실제로 새 설정으로 흐른다” 사이의 경계에서 자주 발생한다. 핵심 위험은 CDS/LDS/RDS/EDS 의존성 때문에 cluster 또는 listener가 warming 상태에 머무르는 경우, EDS가 늦거나 누락되어 기존 endpoint 상태가 계속 사용되는 경우, route match 순서 때문에 의도한 route가 더 넓은 route에 shadowing 되는 경우, 그리고 ho

Summary#

운영적으로는 rollout 성공 여부를 단순히 xDS ACK 또는 control-plane 배포 성공으로 판단하면 부족하다. Envoy admin /config_dump, /clusters, /listeners, /server_info, 통계의 warming/draining 관련 지표, route match 결과, EDS endpoint freshness를 함께 확인해야 한다.

Key Points#

Cluster warming은 CDS 수신만으로 끝나지 않는다.
Envoy cluster는 설정 의존성에 따라 warming 상태가 될 수 있다.
EDS 기반 cluster는 endpoint assignment를 받아야 정상적으로 사용 가능한 상태가 된다.
EDS 응답이 지연되거나 누락되면 cluster가 warming에 머무르고, 그 cluster를 참조하는 route/listener rollout도 지연될 수 있다.
Listener warming은 LDS 단독 문제가 아니라 하위 의존성 문제다.
Listener는 RDS, scoped RDS, cluster, secret/SDS 등 의존 리소스가 준비될 때까지 warming될 수 있다.
새 listener가 warming 중이면 기존 listener가 계속 트래픽을 처리할 수 있다.
이 동작은 안전한 점진 전환에는 유용하지만, 운영자가 “새 LDS가 ACK 되었으므로 트래픽도 새 설정을 탄다”고 오해하면 장애 탐지가 늦어진다.
Stale EDS state는 “장애”라기보다 “마지막 유효 상태 유지”로 나타날 수 있다.
xDS 업데이트 실패, control-plane 지연, EDS resource 누락, 잘못된 resource name, nonce/version 처리 문제 등으로 endpoint 상태가 기대와 다르게 오래 유지될 수 있다.
기존 cluster가 이미 warmed 상태라면 새 EDS가 오지 않아도 이전 endpoint 정보로 계속 라우팅될 가능성이 있다.
반대로 신규 cluster는 EDS를 받지 못해 warming에 머무를 수 있어, 같은 배포에서도 기존 리소스와 신규 리소스의 실패 양상이 다르다.
Route shadowing은 config validation을 통과해도 발생한다.
Envoy HTTP route는 virtual host 선택 후 route list에서 첫 번째로 match되는 route를 사용한다.
넓은 prefix: "/", 느슨한 prefix, broad regex, catch-all route가 더 구체적인 path route보다 앞에 있으면 후속 route가 사실상 도달 불가능해질 수 있다.
Virtual host domain matching도 exact, wildcard, catch-all 우선순위 규칙을 이해하지 못하면 예상과 다른 virtual host가 선택될 수 있다.
이 문제는 xDS ACK, config load 성공, listener ready와 무관하게 “정상 설정이지만 잘못 라우팅”되는 형태로 나타난다.
Hot restart와 listener drain은 원자적 cutover가 아니다.
Envoy hot restart는 새 process와 기존 process가 일정 시간 공존하면서 listener socket handoff와 drain을 수행한다.
기존 downstream connection은 drain 정책, protocol, connection lifetime, drain timeout에 따라 계속 살아 있을 수 있다.
HTTP/2, gRPC, WebSocket, long-lived connection 환경에서는 이전 설정으로 처리되는 트래픽이 rollout 이후에도 관측될 수 있다.
listener update/remove 역시 새 listener warming과 기존 listener drain이 겹치면, 동일 포트에서 서로 다른 설정 세대가 일시적으로 공존할 수 있다.
권장 rollout 관측 포인트
/server_info: Envoy state, hot restart epoch, uptime, version 확인.
/config_dump: 실제 적용된 LDS/CDS/RDS/EDS/SDS snapshot 확인.
/clusters: cluster warming, endpoint health, priority/locality별 endpoint 상태 확인.
/listeners: listener state, draining 여부 확인.
xDS control-plane log: ACK/NACK, nonce, version_info, resource name mismatch 확인.
request-level access log: route name, virtual host, upstream cluster, response flag를 기록해 route shadowing과 stale endpoint 사용을 탐지.

Cautions#

이 초안은 공개 Envoy 문서와 일반적인 운영 패턴을 바탕으로 정리한 failure-mode capsule 초안이다. 특정 조직의 control-plane 구현, ADS/SotW/Delta xDS 사용 여부, Envoy 버전, drain 설정에 따라 세부 동작은 달라질 수 있다.
“Stale EDS”는 단일한 Envoy 공식 에러명이 아니라 운영자가 관측하는 증상 범주다. 실제 원인은 control-plane bug, resource name mismatch, rejected update, network partition, delayed endpoint discovery, endpoint health state 변화 등으로 나누어 확인해야 한다.
Route shadowing은 Envoy가 반드시 경고하거나 거부하는 문제가 아니다. 의도적으로 catch-all route를 앞에 두는 구성도 가능하므로, “shadowing” 여부는 서비스 의도와 route 테스트 결과로 판단해야 한다.
Hot restart drain 중 기존 연결이 얼마나 오래 유지되는지는 drain timeout, parent shutdown time, protocol behavior, client reconnect behavior에 좌우된다. long-lived stream이 많은 환경에서는 별도 실험이 필요하다.
xDS ACK는 “해당 리소스를 Envoy가 수락했다”는 신호이지, 모든 관련 리소스가 warming을 끝내고 모든 트래픽이 새 설정으로 이동했다는 보장은 아니다.

Sources#

https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/init
https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/xds_api
https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/draining
https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/hot_restart
https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/route_matching
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto
https://www.envoyproxy.io/docs/envoy/latest/operations/admin
https://www.envoyproxy.io/docs/envoy/latest/operations/admin#get--server_info

Envoy xDS Rollout Failure Modes: Warming Stalls, NACK Loops, Resource Version Skew, and Draining Semantics
NACK, Nonce, and Control-Plane Drift Failure Modes
JWT Refresh Token Rotation Failure Modes: Reuse Detection, Concurrent Refresh Races, Revocation Propagation, and Multi-Device Session Boundaries

Sagwan Revalidation 2026-07-01T05:29:08Z#

verdict: ok
note: Envoy xDS warming·EDS·route shadowing 설명은 현재도 유효하다.

Sagwan Revalidation 2026-07-02T15:08:47Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현재 관행과 부합함

Sagwan Revalidation 2026-07-04T04:24:56Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현행 practice와 부합함

Sagwan Revalidation 2026-07-05T07:04:40Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 경계 설명은 현재도 유효함

Sagwan Revalidation 2026-07-06T13:01:13Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현재 관행과 부합함

Sagwan Revalidation 2026-07-07T19:04:48Z#

verdict: ok
note: Envoy xDS warming·EDS·route match·drain 경계 설명은 여전히 유효하다.

Sagwan Revalidation 2026-07-09T15:54:03Z#

verdict: ok
note: Envoy xDS warming·EDS·route·drain 동작은 현재도 유효한 운영 지식이다.

Sagwan Revalidation 2026-07-11T08:37:19Z#

verdict: ok
note: 최근 검증 이후 변화 가능성 낮고 Envoy xDS 동작 설명도 여전히 유효함

Sagwan Revalidation 2026-07-13T02:40:56Z#

verdict: ok
note: Envoy xDS warming·EDS·route ordering·drain 동작 설명은 현재도 유효함

Sagwan Revalidation 2026-07-15T00:45:18Z#

verdict: ok
note: xDS warming·EDS stale·route 순서·drain 경계 설명은 현재도 유효함

Sagwan Revalidation 2026-07-17T02:12:03Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현재 practice와 부합함

Sagwan Revalidation 2026-07-19T03:25:57Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현재 practice와 부합함

Sagwan Revalidation 2026-07-21T04:41:24Z#

verdict: ok
note: Envoy xDS warming·EDS·route 순서·drain 설명은 현재도 유효함