[Spring Cloud][업그레이드] Gateway starter가 Boot 4.1에서 verifier와 BOM 정렬은 맞는데도 CI가 깨질 때 property smoke test와 classpath diff를 어디부터 분리하나

IT 리서치 노트

[Spring Cloud][업그레이드] Gateway starter가 Boot 4.1에서 verifier와 BOM 정렬은 맞는데도 CI가 깨질 때 property smoke test와 classpath diff를 어디부터 분리하나

Spring Boot 4.1과 Spring Cloud 조합으로 올린 뒤 verifier도 통과했고 release train BOM도 맞췄는데, Gateway starter 관련 CI만 계속 깨지는 경우가 있다. 2026년 8월 3일 기준 Spring 공식 문서를 다시 보면, verifier override는 1차 가드레일이고, third-party project는 추가 요구사항을 가질 수 있으며, Spring Cloud는 release train BOM 사용을 권장한다. 이 글은 Gateway starter가 Boot 4.1에서 verifier와 BOM 정렬은 맞는데도 CI가 깨질 때 property smoke test와 classpath diff를 어디부터 분리해야 덜 꼬이는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 verifier와 BOM 정렬이 맞는다는 사실만으로 Gateway starter runtime 조합이 안전하다고 보지 않는 편이 빠르다. dependency tree와 classpath diff를 먼저 저장하고, Gateway property binding과 auto-configuration smoke test를 별도로 돌려야 원인을 더 짧게 자를 수 있다. compatible Boot versions를 다시 만지는 것은 그 다음이다.

즉 이번 문제는 'Boot 4.1이 안 된다'가 아니라 'verifier 통과 뒤에도 Gateway branch가 별도로 깨진다'는 신호일 때가 많다. 직전 Gateway BOM drift 글이 버전 정렬을 다뤘다면, 이번 글은 smoke test와 artifact 저장 순서까지 좁혀 본 후속 정리다.

2. 어디서 실제로 막히는가

현장에서 자주 꼬이는 지점은 세 가지다. 첫째, verifier가 통과했으니 Gateway runtime도 안전하다고 생각한다. 둘째, Spring Cloud BOM과 starter 좌표를 정렬한 뒤에도 CI가 깨지는데 동일한 설정 문제로만 본다. 셋째, OpenFeign나 다른 starter는 통과하니 Gateway도 곧 같은 원인일 것이라고 가정한다.

Spring Cloud verifier 문서는 compatible Boot versions override가 가능하다고 적지만, Spring Boot system requirements 문서는 third-party project가 추가 요구사항을 가질 수 있다고 설명한다. Spring Cloud 프로젝트 페이지는 release train BOM을 권장하고, Spring Boot dependency management 문서는 dependency graph override가 실제 classpath에 영향을 준다고 짚는다. 이 네 문서를 같이 읽으면 verifier 통과 뒤 Gateway CI 실패는 runtime classpath나 property binding 분리 문제일 가능성이 크다.

특히 Gateway는 route locator, filter chain, property binding, reactive stack classpath에 민감하다. 같은 release train 안에서도 OpenFeign와 달리 Gateway 쪽 integration test만 깨질 수 있다. 그런데 dependency tree 파일을 저장하지 않으면 수동 버전 핀이 있었는지, transitive dependency가 어떻게 달라졌는지, property binding이 어느 조합에서만 실패했는지 재현이 늦어진다.

• 증상: verifier는 통과하지만 Gateway integration test만 실패한다.
• 실패: compatible-boot-versions 설정을 다시 바꾸며 시간을 쓴다.
• 막힘: dependency tree와 Gateway property binding 결과를 저장하지 않는다.
• 누락: starter별 smoke test를 별개로 관리하지 않는다.

질문	먼저 볼 곳	실무 판단
verifier 뒤 왜 또 깨질까	dependency tree와 classpath	runtime starter 조합을 먼저 의심한다
Gateway만 왜 다를까	property binding과 route smoke test	starter별 branch로 분리한다
무엇을 남겨야 할까	tree 파일, build import 위치, CI 로그	artifact를 재현 단위로 남긴다

3. 실무에서 적용하는 순서

점검 순서는 다섯 단계가 가장 빠르다. 먼저 verifier 설정은 그대로 두고 dependency tree를 저장한다. 다음으로 Spring Cloud release train BOM과 Spring Boot BOM import 위치를 기록한다. 세 번째로 Gateway starter와 관련 transitive dependency에 manual pin이 있는지 찾는다. 네 번째로 Gateway property binding과 route locator smoke test를 별도 잡으로 분리한다. 마지막으로 OpenFeign 같은 다른 starter와 diff를 남기고 CI artifact 경로를 저장한다.

1. verifier는 그대로 두고 dependency tree를 먼저 저장한다.
2. BOM import 위치와 starter 수동 핀을 함께 본다.
3. Gateway 관련 transitive dependency drift를 찾는다.
4. Gateway property와 route smoke test를 분리한다.
5. starter별 diff와 CI artifact 경로를 남긴다.

실제 CI에서는 build.gradle 또는 pom.xml import 블록, dependencyInsight 결과, Gateway appendix에 대응되는 property 조합, 실패 테스트 이름, 재현 명령어를 같은 메모에 두는 편이 좋다. verifier를 다시 손보기 전에 classpath와 property binding을 먼저 자르면, 버전 문자열을 건드리지 않고도 원인을 바로 설명할 수 있는 경우가 많다. 특히 reactive stack과 route predicate/filter 관련 옵션이 바뀔 때 효과가 크다.

upgrade_note:
verifier_passed=true
cloud_bom_aligned=true
gateway_manual_pin_checked=true
dependency_tree_artifact=build/reports/deps/gateway-tree.txt
gateway_property_smoke_test=failed
route_locator_smoke_test=failed
openfeign_smoke_test=passed

이 메모가 있으면 'verifier는 통과한다'와 'Gateway runtime이 안전하다'를 섞지 않게 된다. 다음 업그레이드에서도 classpath와 property 분기부터 다시 시작할 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 Spring Cloud compatibility verifier 문서의 override 설명이다. verifier를 우회하거나 compatible Boot versions를 바꾸는 길은 있지만, 이건 1차 가드레일 조정이지 runtime classpath 보증은 아니다.

Spring Cloud verifier 문서는 compatible Boot versions override가 가능하다고 설명한다.

즉 verifier 통과는 출발점일 뿐이다. 이미 Gateway starter와 BOM drift 글이 여기까지를 다뤘다면, 이번 글은 그 다음 단계인 property smoke test와 classpath diff를 더 좁힌 가지다.

두 번째 자료는 Spring Boot 4.1 system requirements 문서다. 여기서는 third-party project가 추가 요구사항을 가질 수 있다고 적고 있다.

Spring Boot 4.1 문서는 third-party project가 추가 요구사항을 가질 수 있다고 설명한다.

따라서 verifier가 통과했다는 사실만으로 Gateway starter runtime 조합까지 안전하다고 볼 수 없다. starter별 smoke test가 필요한 이유가 바로 여기에 있다.

세 번째 자료는 Spring Cloud 프로젝트 페이지의 BOM 권고다. Spring Cloud는 release train BOM spring-cloud-dependencies 사용을 직접 권장한다.

Spring Cloud는 release train BOM spring-cloud-dependencies 사용을 권장한다.

여기서 중요한 것은 verifier 통과 뒤에도 BOM 정렬과 starter별 classpath가 별도 문제라는 점이다. release train을 맞췄다고 Gateway property binding까지 자동으로 검증되지는 않는다.

네 번째 자료는 Spring Boot dependency management 문서다. BOM 강제와 override가 dependency graph에서 어떤 의미를 가지는지 직접 설명한다.

Spring Boot dependency management 문서는 dependency graph override가 실제 classpath에 영향을 준다고 설명한다.

그래서 Gateway만 깨질 때는 단순히 버전 문자열이 아니라 dependency graph diff를 저장해야 한다. runtime classpath가 달라지면 property binding과 auto-config도 따라 흔들린다.

이슈를 빨리 자르려면 verifier 문제, BOM 문제, classpath 문제, property smoke test 문제를 한 표에서 분리해야 한다. 같은 CI 실패도 읽는 순서가 다르다.

Gateway starter CI 실패를 verifier, BOM, classpath, property smoke test로 나누는 triage 표다.

같은 업그레이드 가지의 OpenFeign starter 후속 글과 같이 보면, 같은 release train에서도 starter별 smoke test를 अलग개로 남겨야 한다는 점이 더 선명해진다.

실제 운영 메모는 verifier 설정과 dependency tree, smoke test 결과를 같은 레코드에 묶어 두는 편이 좋다. 무엇을 다시 실행해야 하는지도 한 눈에 보여야 한다.

Gateway starter 업그레이드 메모에 남길 dependency tree와 smoke test 예시다.

이 정도만 남겨도 다음 release train 업그레이드에서 재현이 훨씬 빨라진다. classpath와 property test를 한 문장으로 뭉개지 않는 것이 핵심이다.

5. 주의사항과 리스크

첫 번째 리스크는 verifier 통과를 runtime starter 호환성의 최종 신호로 오해하는 것이다. 두 번째 리스크는 release train BOM과 starter 수동 핀을 별개로 보지 않아 classpath drift를 놓치는 것이다. 세 번째 리스크는 Gateway property binding과 route smoke test를 별도 잡으로 남기지 않아 같은 실패를 계속 통합 테스트에서만 보게 되는 것이다.

운영 전에 확인할 때는 최소한 Boot 버전, Cloud BOM 버전, verifier 설정, manual pin 유무, dependency tree artifact, Gateway smoke test 결과를 같은 표에 두는 편이 좋다. 그래야 재발 때 diff 기준점이 남는다.

• verifier 통과와 runtime 호환성은 같은 신호가 아니다.
• release train BOM과 classpath drift를 함께 본다.
• Gateway는 property smoke test를 starter별로 분리한다.

6. 결론

Gateway starter가 Boot 4.1에서 verifier와 BOM 정렬은 맞는데도 CI가 깨질 때는 compatible Boot versions를 다시 만지는 것보다 dependency tree와 property smoke test를 먼저 분리하는 편이 빠르다. classpath diff와 Gateway binding 결과를 artifact로 남기면 release train 업그레이드 회고도 훨씬 짧아진다.

• dependency tree와 classpath diff를 먼저 저장한다.
• Gateway property smoke test를 별도 잡으로 분리한다.
• starter별 diff를 artifact로 남긴다.

같은 가지의 앞단에는 Gateway starter와 BOM drift 글, OpenFeign starter 후속 글, verifier override 분기 글, release train과 Boot 조합 글이 있다. 그 위에 이번 property/classpath 분기를 얹으면 verifier 이후 CI 대응 경로가 더 구체적으로 닫힌다.

그리고 verifier와 BOM 정렬 뒤에 route 정의 소스와 transitive dependency mismatch를 어디까지 다시 기록해야 할지 더 좁혀 보고 싶다면, 방금 이어 쓴 Gateway route source와 transitive mismatch 후속 글을 같이 보면 좋다. 이 글이 property smoke test와 classpath diff를 나누는 앞단이라면, 318번 글은 그 다음에 route source branch와 classpath branch를 실제 메모 단위로 분리하는 단계다.

7. 참고 링크

1. https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/common-abstractions.html
2. https://docs.spring.io/spring-boot/system-requirements.html
3. https://spring.io/projects/spring-cloud/
4. https://docs.spring.io/spring-boot/gradle-plugin/managing-dependencies.html
5. https://docs.spring.io/spring-cloud-gateway/reference/appendix.html