목차
수천 개의 API·배치 설정을 코드로 다루는 토스페이먼츠 (2026-01)
원문 정보
- 원문: 수천 개의 API/BATCH 서버를 하나의 설정 체계로 관리하기
- 매체 · 게시일: 토스 기술 블로그 · 2026-01-09
- 저자: 나재은 (토스페이먼츠 서버플랫폼 팀 리더)
- Toss Makers Conference 세션을 바탕으로 재구성된 글입니다. 원문은 토스페이먼츠 ‘레거시 정산 개편기’가 인프라가 아닌 애플리케이션 도메인 쪽 개선을 다룬다고 소개합니다.
- 원문 내용을 바탕으로 재구성한 요약입니다.
50억 원 정산 배치에 숨어 있던 오타
G1HeapRegionSize가 G1HeapRegionSiez로 적혀 끝의 두 글자가 뒤바뀌어 있었습니다. 이 설정을 쓰던 배치가 맡은 정산 규모는 50억 원이었습니다. 비슷한 설정을 2,000개 넘게 관리한다면, 긴 JVM 옵션 문자열 사이에서 이런 실수를 찾아내기는 쉽지 않습니다.
토스페이먼츠 서버플랫폼 팀은 Kubernetes, AWS, 사내 운영 도구를 운영하며 수천 개의 API 서버와 배치 설정을 관리합니다. 대부분 비슷하지만 조금씩 다릅니다. 공통 환경 변수를 추가하거나 Java Heap을 늘릴 때마다 설정을 복사해 고치면, 코드 중복이 버그로 이어지듯 설정 중복도 인프라 장애로 이어질 수 있습니다.
팀이 원한 것은 중복 없이 테스트할 수 있는 설정 체계였습니다. AWS와 IDC가 섞인 하이브리드 환경에서도 수천 대를 한 체계로 제어하려면, 설정 역시 코드 개발처럼 설계해야 한다고 본 것입니다. 정산 배치에서는 개발자의 반복 입력을 선언으로 바꾸고, API 서버에서는 공통 설정과 달라지는 값을 분리하는 작업으로 이어졌습니다.
Groovy 선언으로 배치를 만드는 Job-DSL 어댑터
정산 배치는 작은 설정 오류도 정산 누락이나 금액 오류로 번질 수 있는 곳입니다. 한 달에 다루는 돈을 항공모함 한 척 값에 빗댈 정도입니다. 팀은 이런 환경일수록 인프라가 단순해야 한다고 판단했고, 여러 배치 솔루션을 검토한 끝에 Jenkins를 선택했습니다. 완벽한 도구는 아니어도 토스페이먼츠의 배치 로직을 제어하기에는 충분하고, 학습 곡선도 낮았습니다.
사용 과정은 단순하지 않았습니다. Jenkins는 GitOps 지원이 약해 개발자가 Web UI에 bash script를 매번 입력해야 했습니다. Java가 설치된 위치를 찾기 어려웠고, 장비마다 Java 버전이 조금씩 달랐습니다. Job마다 실행 스크립트까지 다르니 문제가 생길 때마다 서버플랫폼 팀이 실행 흐름을 처음부터 끝까지 점검해야 했습니다.
이 반복 작업을 줄이기 위해 Job-DSL 플러그인을 감싼 어댑터를 만들었습니다. Job-DSL은 Groovy 코드로 Jenkins Job을 정의하는 플러그인입니다. 그대로 쓰려면 Jenkins 내부 구조와 설정 계층을 알아야 하므로, 팀은 빌더 패턴의 선언형 클래스로 개발자가 사용할 인터페이스를 만들었습니다. Jenkins를 잘 몰라도 Groovy 함수를 호출해 필요한 설정을 선언하면 됩니다.
JavaRunBatchJobBuilder가 그 예입니다. Job 이름과 워커 노드 사양부터 파라미터, Git 저장소, phase, JDK 버전, JVM 옵션과 힙 크기, 크론 표현식까지 한곳에서 지정합니다. IDE에서 클래스에 점을 찍으면 자동완성으로 가능한 설정이 나타납니다. 개발자가 배치에 기대하는 설정을 찾고 조합할 수 있게 한 것입니다.
장비 환경에 의존하는 연동도 여기에 포함됩니다. Prometheus JMX agent, async profiler, 스레드 덤프, Pinpoint, Scavenger를 쓰기 위해 개발자가 장비마다 설정을 맞출 필요 없이, 옵션을 선언하면 어느 배치 장비에서든 같은 방식으로 사용할 수 있게 했습니다. Groovy 반복문으로 배치 수십 개를 만들거나 조건문으로 환경별 배치를 정의하는 것도 가능합니다. Java 배치 실행 외에 빌드, 배포, Jenkins Pipeline, Shell 호출을 위한 패턴도 준비했고, 새로운 요구가 나오면 추가했습니다.
선언형으로 바꿔도 실수는 남습니다. 실제로 STAGING 장비에 LIVE 배치를 할당한 일이 있었습니다. 설정을 Groovy 코드로 작성한 덕분에 적용 전에 테스트를 실행할 수 있었고, 이런 업무 규칙 위반을 검증해 잘못된 설정이 운영 환경에 적용되는 것을 막도록 했습니다.
공통 기능을 추가하는 방식도 달라졌습니다. Pinpoint 연동이나 Heap Dump 기능이 새로 필요하면 DevOps가 중앙에서 한 번 연동하고, 개발자는 제공된 옵션으로 켜거나 끕니다. 배치 설정이 개발자와 DevOps 사이의 단일 업무 인터페이스가 된 것입니다. 새로운 인프라 요구도 이 인터페이스를 확장해 적은 비용으로 구현할 수 있게 됐습니다.
필요할 때 늘어나는 배치 전용 노드
설정을 선언하기 쉬워져도 메모리 부족은 남습니다. Jenkins 워커 한 대에서 여러 프로세스가 같은 시간대에 자원을 사용하면, 메모리가 부족해 프로세스가 비정상 종료되는 일이 가끔 있었습니다. 그렇다고 노드마다 프로세스를 하나씩만 실행하기에는 자원이 아까웠습니다.
팀은 배치마다 전용 노드를 주되, 필요한 만큼 늘리고 오래 쓰지 않으면 줄이는 Dynamic Provisioning을 도입했습니다. 배치가 실행되는 동안에는 CPU와 메모리를 독점하게 하고, 사용하지 않는 장비를 계속 유지하는 비용은 자동 종료로 해결했습니다.
배치 실행 요청이 들어왔을 때 사용 가능한 노드가 부족하면 새 노드를 자동으로 프로비저닝합니다. 그 노드에 Jar 파일 등 필요한 자원을 배포한 뒤 배치 프로세스를 실행하고, 오래 사용하지 않은 노드는 종료합니다. 서로 다른 Java 프로세스가 같은 노드의 자원을 경쟁해서 쓰던 방식을 바꾼 것입니다.
새 장비를 준비하는 일에는 배포 경로 정리도 포함됐습니다. 노드만 생겼다고 배치를 실행할 수는 없습니다. Jar 파일을 동적으로 가져올 수 있도록 배치 빌드·배포 경로를 표준화해야 했습니다. 이 작업까지 마친 뒤에는 배치가 한 번에 수십 개씩 병렬로 실행돼도 개발자가 인프라 용량을 신경 쓰지 않아도 됐습니다.
메모리가 더 필요하면 Groovy 코드 한 줄로 사양을 바꿉니다. 각 장비는 기본적으로 한 번 쓰고 버리는 형태로 사용할 수 있어, OS 보안 패치 같은 커널 수준 작업도 적은 비용으로 수행할 수 있게 됐습니다.
겹친 설정을 아래에서 올려다보는 API 서버
API 서버에서도 복사해 붙인 설정이 문제였습니다. 모든 서버에 공통 환경 변수를 넣거나 Java Heap을 늘려 달라는 요구에 YAML을 복사해 대응했는데, 시간이 지날수록 설정은 복잡해지고 실수도 늘었습니다. 실제로 인프라 장애로 이어질 뻔한 상황까지 겪었습니다.
팀은 설정값을 조합 가능한 계층으로 나누고, 이를 하나의 결과로 해석하는 오버레이를 도입했습니다. global, cluster, phase 순서로 놓으면 아래 계층일수록 우선순위가 높고, 위쪽 값은 기본값처럼 동작합니다. 얇은 설정을 여러 장 겹쳐 놓은 뒤 서버가 아래에서 올려다보는 모습입니다. 자기 위치에서 가장 가까운 설정값이 보입니다.
계층은 요구사항에 맞춰 나눴습니다. 원문에서 든 예시입니다.
cluster: Kubernetes 클러스터마다 다른 docker registry URLapp-group: 프론트엔드 애플리케이션이 공통으로 쓰는 npm 주소phase: 개발·스테이징·프로덕션 환경별 설정app: 개별 애플리케이션 설정
이 구분이 고정된 것은 아닙니다. 개발자의 요구에 따라 계층을 더할 수 있습니다. 실제 파일은 각 계층과 1:1로 대응하며, applications 디렉터리 아래에는 서비스별 app 설정을 둡니다. 나머지는 values-global-common.yaml, values-cluster-live-1-common.yaml, values-phase-live-common.yaml처럼 이름 규칙으로 구분했습니다.
phase 파일이 여럿이면 CI/CD가 현재 환경에 맞는 파일을 선택합니다. 배포 과정도 같은 설정을 참조합니다. 덕분에 개발 환경에서는 카나리 배포를 생략하는 동작까지 한곳에서 제어할 수 있게 됐습니다.
긴 JVM_OPTION 안의 중복을 줄이는 템플릿
오버레이는 공통값을 모으는 데 도움이 됐지만, 값 안의 중복까지 해결하지는 못했습니다. JVM_OPTION에서 힙 크기만 바꾸려 해도 긴 문자열 전체를 다시 적어야 했습니다. YAML이 key-value 단위로 값을 구분하기 때문입니다. 이대로라면 힙 크기만 다른 JVM_OPTION이 수백 개 생깁니다.
해법은 문자열에서 달라지는 값을 템플릿 변수로 분리하는 것이었습니다. 공통 계층에 JVM 옵션의 형태를 정의하고, 애플리케이션은 필요한 값만 덮어씁니다.
global 계층에는 JVM_OPTION을 -Xmx{{MAX_HEAP}}m -XX:+UseG1GC로 정의하고 MAX_HEAP을 1024로 둡니다. my-service 계층에서 MAX_HEAP을 2048로 바꾸면 최종 JVM_OPTION은 -Xmx2048m -XX:+UseG1GC가 됩니다.
이 예시에서 my-service가 바꾸는 것은 MAX_HEAP뿐입니다. 나머지 JVM 옵션을 다시 쓰지 않아도 최종 문자열에는 -Xmx2048m이 들어갑니다. 템플릿 자체도 설정이므로 계층별 우선순위를 따릅니다. REGION_SIZE까지 변수로 분리하면, global에 둔 MAX_HEAP 1024와 REGION_SIZE 8을 live phase에서 각각 4096과 16으로 바꿔 최종 JVM_OPTION에 반영할 수 있습니다.
고정된 값만 조합하는 데서 멈추지도 않았습니다. 빌드 과정에서 Python 스크립트를 주입하면 random.randint(10000, 20000)으로 포트를 고르거나 원격 API에서 값을 가져올 수 있습니다. 이렇게 만든 jmx_port_random, my_remote_config 같은 변수는 설정값뿐 아니라 템플릿 변수로도 사용 가능합니다.
배열 안에서 조건에 따라 값을 적용하는 기능도 추가했습니다. onTargetClusterNames에 대상 클러스터를 지정하는 방식입니다. 예를 들어 SPRING_PROFILES_INCLUDE는 live-1, live-2에서 live-pg-aws, live-3, live-4에서 live-pg-dc1을 적용하도록 정의할 수 있습니다.
오버레이와 템플릿이 처음부터 갖춰져 있었던 것은 아닙니다. 단순한 YAML에서 출발해 인프라 변화와 개발자 요구에 맞춰 기능을 추가한 결과입니다. 나재은 리더가 이 설정 체계의 가장 강력한 기능으로 꼽은 것도 ‘진화’입니다. 설정을 일종의 소프트웨어로 다뤘기에, 새로운 요구가 생겼을 때 설정 인프라를 확장할 수 있게 됐습니다.
그 변화가 드러나는 작업이 JDK 버전 변경입니다. 2025년 9월 JDK 25가 출시됐고, 글을 쓰던 시점에는 새 버전을 사용해 볼 수 있게 됐습니다. 토스페이먼츠는 이 설정 체계 덕분에 수백수천 대의 JDK 버전을 순식간에 변경할 수 있다고 설명합니다. Pinpoint 같은 APM을 새로 개발해 수백 대에 바로 적용해야 하는 요구에도 대응할 수 있습니다. 몇 명 안 되는 DevOps 엔지니어가 개발자 수십 명을 지원하는 배경입니다.
원문에 나온 설정 계층과 예시 값
| 항목 | 값 |
|---|---|
| API 설정 계층 순서 | global, cluster, phase (아래로 갈수록 우선순위 높음) |
| 추가 계층 예시 | app-group, app |
| 템플릿 예시 (global) | -Xmx{{MAX_HEAP}}m, MAX_HEAP 1024, REGION_SIZE 8 |
| 템플릿 예시 (live phase) | MAX_HEAP 4096, REGION_SIZE 16 |
| 조건부 설정 예시 | live-1, live-2는 live-pg-aws, live-3, live-4는 live-pg-dc1 |
| 배치 워커 노드 예시 | cpu8, mem16g (동적 프로비저닝) |
| 어댑터 예시 JDK / 힙 | JDK 21 / 4g |
| 오타 사례가 걸려 있던 배치 규모 | 50억 원 규모 정산 |