외부 연동에서 마주친 인프라
제휴 연동을 테스트하던 중 인증 API에서 Connection timed out이 발생했습니다. 우리 서버의 NAT IP가 파트너사 허용 목록에서 빠져 있었습니다.
저는 이 프로젝트의 프론트엔드를 맡았습니다. 연동 준비 중에 오가던 IP와 포트 목록이 이 오류와 어떻게 연결되는지 궁금했어요. 마침 사내 인프라 개발자 Scott에게 실제 AWS 구성을 배우고 있어서, 요청이 외부 시스템까지 가는 경로를 함께 정리했습니다. (Scott이 알려주고 저는 옆에서 오...만 하고 있음. 늘 감사함)
#호출 방향에 따라 필요한 IP가 달랐다
파트너사가 우리를 호출할 때는 우리 쪽의 접속 주소가 필요합니다. 반대로 우리가 파트너사 API를 호출할 때는 파트너사가 허용할 우리의 출발지 IP가 필요합니다.
이 글은 AWS의 public NAT gateway와 internet gateway를 거쳐 외부 IPv4 API를 호출하는 구성을 기준으로 설명합니다. 이 경로에서 파트너사가 보는 출발지 IP는 서버의 사설 IP가 아니라 NAT gateway에 연결된 공인 IP입니다. 이를 NAT IP라고 부르겠습니다. AWS의 NAT 통신 경로에서 확인할 수 있습니다.
NAT IP가 바뀌면 우리 내부 변경이 파트너사의 방화벽 정책 변경으로 이어질 수 있습니다. 허용 목록에 붙어 있던 /32도 같은 맥락이에요. IP 하나만 가리키는 프리픽스라, 정확히 이 출발지 IP 하나만 허용한다는 뜻이에요.
#연결은 경로만 있다고 되는 게 아니었다
라우팅 테이블은 목적지까지 어디로 보낼지 정합니다.
Destination Target
10.20.0.0/16 local
0.0.0.0/0 nat-...방화벽은 그 트래픽을 통과시킬지 판단합니다. 그래서 외부 통신이 되려면 둘 다 맞아야 합니다. 목적지까지 갈 경로가 있어야 하고, 그 경로의 트래픽이 허용돼 있어야 해요.
프로젝트에서 오가던 IP와 포트 목록은 서버 이름을 나열한 문서가 아니었습니다. 누가 연결을 시작하고, 어디로 가며, 어느 포트를 사용하는지를 맞추는 문서였어요.
연동 과정에서는 "양방향으로 방화벽을 열어달라"는 표현도 나왔습니다. 두 시스템이 각각 연결을 시작한다는 뜻인지, 하나의 연결에서 요청과 응답을 말하는 것인지 모호했습니다. AWS의 security group은 연결 상태를 추적하는 stateful 방식이라 허용된 요청의 응답도 허용합니다. 반면 network ACL은 stateless 방식이라 응답 방향의 규칙도 필요합니다. AWS의 두 정책 비교처럼, 실제로 어느 정책을 설정하는지부터 확인해야 했어요.
파트너사는 개발용 테스트 환경과 QA 환경도 나뉘어 있었습니다. 호출 대상을 바꿀 때는 호스트뿐 아니라 목적지와 포트, 그 환경의 허용 목록에 등록된 우리 NAT IP까지 함께 확인해야 했어요.
#Connection timed out이면 어디부터 볼까
timeout이라는 문구만으로 원인을 단정할 수는 없습니다. 먼저 TCP 연결 중인지, 연결 뒤 응답을 기다리는 중인지 구분합니다.
TCP 연결을 만드는 단계에서 timeout이 났다면 HTTP 요청 내용보다 앞선 구간부터 확인합니다.
- 목적지: 호출 중인 환경의 호스트와 포트가 맞는지, DNS가 어떤 IP로 해석되는지 확인합니다.
- 우리 경로: 실제 API를 호출하는 서버에서 연결을 확인하고, 라우팅과 출발지 공인 IP, 우리 쪽의 허용 규칙을 봅니다.
- 파트너 경로: 그 출발지 IP가 해당 환경의 허용 목록에 있는지, 목적지 포트에서 연결을 받는지 확인합니다.
노트북에서 연결됐다는 결과만으로 서버의 경로도 정상이라고 볼 수는 없습니다. 출발지가 다르기 때문입니다. AWS의 NAT 연결 점검 문서도 라우팅, security group, network ACL을 함께 확인하도록 안내합니다.
#네트워크 문제는 중복 처리 문제로 이어질 수 있다
timeout은 발생한 단계에 따라 의미가 다릅니다. 요청이 서버에 전달된 뒤 응답을 기다리는 과정에서 timeout이 발생하면, 서버는 이미 요청을 처리했을 수도 있습니다. 호출자는 성공 여부를 알 수 없고, 재시도 과정에서 같은 이벤트가 다시 전달될 수 있습니다. 같은 프로젝트에서 논의했던 이벤트 식별자도 이 관점에서 이해할 수 있었어요.
TCP가 데이터를 안정적으로 전달한다고 해서 비즈니스 로직까지 한 번만 실행되는 것은 아닙니다. 그래서 사용자 식별자와 이벤트 식별자를 구분해야 합니다.
- 가입
hash(u1 + 가입)저장 - 가입 재시도 (timeout 후)
hash(u1 + 가입)버림 · 재시도 걸러짐 - 탈퇴
hash(u1 + 탈퇴)저장 - 재가입
hash(u1 + 가입)버림 · 새 이벤트인데
집계 가입 1 · 탈퇴 1 — 실제 가입 2 · 탈퇴 1 가입 1건 유실
재시도마다 새 식별자를 만드는 게 아니라, 같은 이벤트의 재시도에서는 같은 식별자를 유지해야 합니다. 받는 쪽도 이 식별자로 중복을 판별하고, 중복 확인과 실제 처리를 함께 보호해야 합니다. 식별자만 보내는 것으로 중복 실행이 막히지는 않아요. AWS의 멱등 API 설명도 이 두 작업의 원자성을 다룹니다. 결국 UUID냐 해시냐를 고르기 전에 무엇을 하나의 이벤트로 볼 것인지 정해야 했습니다.
#요청 하나를 끝까지 따라가기
같이 일하는 인프라 개발자분이 실제 AWS 구성을 놓고 하나씩 설명해 주셨는데, 가장 도움이 된 건 개념이 실제 시스템에서 어떻게 이어지는지 보는 과정이었어요.
이제 NAT IP, 방화벽, 환경 변경, timeout 같은 이야기가 각각 따로 보이지 않습니다. 문제가 생기면 코드부터 보기보다 요청이 어디까지 갔는지부터 확인합니다.
프론트엔드에서 시작한 요청도 브라우저에서 끝나지 않습니다. 서버와 네트워크를 지나 외부 시스템까지 이어집니다. 이번에 얻은 건 네트워크 용어 몇 개가 아니라, 그 요청을 끝까지 따라가며 문제 범위를 좁히는 기준이었습니다.
실제 값과 일부 구성은 일반화했습니다.