[504의 교훈] APISIX 전환으로 겪은 장애, 그리고 우리가 준비하지 못한 것들

1. 장애의 시작: Gateway를 바꾸면 모든 게 나아질 줄 알았다

기존에 Go 기반 자체 Gateway(이하 Go Gateway)를 사용하고 있었다.

필요한 라우팅 로직만 얹어 경량화된 구조였지만, 다음과 같은 한계에 부딪혔다.

 

• 동적 라우팅 관리의 부재
• 인증/권한/로깅 플로우 중복
• 버전 관리가 힘든 직접 코드 관리 구조

 

이러한 요구사항을 해결하기 위해 우리는 Apache APISIX로 전환을 시도했다.

APISIX는 오픈소스 고성능 API Gateway로서 Nginx + Lua 기반, 플러그인 시스템을 제공하며

레이트 리밋, 인증, 서비스 디스커버리, 로깅 등 다양한 기능을 유연하게 다룰 수 있었다.

 

기능만 놓고 보면 “완벽한 선택”이었다.

 

2. 그러나, 우리는 너무 빨랐고 느렸다

전환 초기, APISIX는 문제없이 동작했다.

하지만 PM 시간 이후 배포된 신규 Gateway 버전에서 문제가 발생했고,

이후 우리의 모든 서비스는 순식간에 HTTP 504 Gateway Timeout으로 응답했다.

 

문제가 생기자 팀 내에서는 빠르게 “APISIX 문제가 아닐까?”, “그냥 다시 Go Gateway로 돌리는 게 낫겠다”는 논의가 나왔다.

하지만 나로서는 이 대응이 마냥 옳다고 느껴지지 않았다.

 

원인 파악까지 수 시간이 걸렸다.

문제가 발생했을 땐 이미 다음과 같은 피해가 퍼지고 있었다.

 

• 인증 요청 지연 및 실패
• 일부 API 응답 없음
• 내부 서비스 연쇄 지연
• 고객 항의 및 긴급 회의 연속
• 전환을 추진하고 있었을 뿐, 아직 완전한 전환은 아니었다.
• APISIX는 여전히 안정적으로 운영 중인 모듈도 있었으며,
• 장애의 실질적인 원인을 끝까지 파헤치지 않고 추정으로 결론을 내린 건 아닌가 하는 아쉬움이 남았다.

“이건 Gateway 문제야”라는 단정 아래 돌아간 선택은,

결과적으로 불확실한 상태에서 ‘원래 잘되던 것’으로 회귀한 것일 뿐, 근본적인 해결은 아니었다.

 

 

3. 기술 분석: 문제는 “설정”이 아니라 “설계”였다

APISIX의 설정 자체는 정상이었다.

라우팅 조건도 맞고, 인증 플러그인도 활성화 상태였다.

하지만 다음과 같은 설계적 결함이 복합적으로 작용했다.

 

 

(1) 플러그인 동작 방식에 대한 이해 부족

• APISIX는 버전별로 플러그인 동작 방식이 미묘하게 다름
• PM 이후 적용된 버전에서 특정 조건하에 인증 플러그인이 응답을 대기한 것으로 추정
• Go Gateway에서는 없던 동기화 병목이 APISIX에서 노출됨

 

(2) 테스트 범위의 문제

• 기능 테스트는 모두 통과
• 하지만 운영 트래픽 조건 (동시성, 특정 요청 조합) 은 시뮬레이션되지 않음

(3) Single Point Gateway 구성

• 전환 당시 APISIX만 사용하도록 구조를 일괄 적용
• Fallback 구조 미비 → 문제 발생 시 전체 트래픽 장애로 확대

 

4. 대응: 우리는 무엇을 했고, 무엇을 못했나

 

우리가 한 것

• APISIX를 인증 플로우 일부에만 남김
• 전면 전환 계획 보류, 기술 검토 재실시

 

우리가 못한 것

• 트래픽 Shadowing / A/B 테스트 미적용
• 플러그인별 동작 방식 문서화 부족
• 장애 감지를 위한 실시간 알림 시스템 미비
• “야간 배포”라는 리스크에 대한 명확한 금지 정책 없음

 

5. 회고: 나는 무엇을 놓쳤을까

개발자로서 직접 Gateway 코드를 다룬 건 아니었다.

하지만 지금 생각하면, 아래와 같은 사전 대응을 주도했더라면 어땠을까 아쉬움이 크다.

 

• 전환 전에 서비스별 Gateway 의존도 맵을 만들었다면?
• 설정이 아닌 설계 리뷰 문서를 작성했더라면?
• PM 시간 이후가 아니라 업무 시간대에 배포했다면?

무엇보다도…

“지금까지 문제 없었으니까 괜찮겠지”라는 암묵적 신뢰가 가장 큰 적이었다.

 

 

6. 기술이 아닌 “팀”을 위한 개선안

다음은 우리가 팀 차원에서 가져가야 할 기술 전략이다:

항목	개선 방안
Gateway 구조 전환	Dual Gateway or Canary 전환 방식 적용
배포 프로세스	야간 배포 금지 / Rollback 자동화
플러그인 검증	실제 운영 조건 기반 시나리오 테스트 설계
장애 탐지	응답지연/오류율 기반 알람 시스템 구축
지식 공유	Gateway 내부 구조와 설정 문서화 정례화

 

 

7. 마무리하며

이번 장애는 단순히 APISIX 때문이 아니다.

우리가 준비하지 못했던 과정, 점검하지 않았던 시나리오, 그리고 대응하지 못한 조직 체계의 결과다.

 

기술은 바뀔 수 있다. 하지만 “기술을 바꾸는 방식”은 더 신중해야 한다.

다음에 또 비슷한 전환이 온다면,

이번 경험은 반드시 나와 우리 팀에게 나침반이 되어줄 것이다.

 

8. 이번 이슈에서 배운 점

• 기능이 정상 동작한다고 해서 곧바로 배포해서는 안 된다
  → 트래픽 기반 부하 테스트, 실제 운영 환경과 유사한 staging 테스트 필요
• Gateway와 같은 핵심 인프라 구성요소는 점진적 전환이 중요하다
  → Dual Gateway, Canary Release 전략 필요
• 장애 대응 프로세스와 롤백 플랜을 항상 마련해 두어야 한다
  → 운영팀, 개발팀 간 빠른 협업 체계 필수

“인프라는 바꿀 수 있다. 하지만, 바꾼 인프라가 사용자 경험까지 망쳐서는 안 된다.”