[Spring Cloud][업그레이드] compatibility verifier를 끌지 compatible-boot-versions로 임시 허용할지 release train 정렬로 끝낼지 어떤 순서로 나누나

Sophie_ 2026. 7. 30. 20:21

IT 리서치 노트

[Spring Cloud][업그레이드] compatibility verifier를 끌지 compatible-boot-versions로 임시 허용할지 release train 정렬로 끝낼지 어떤 순서로 나누나

Spring Boot 4.1 계열로 올리다가 compatibility verifier가 막히면 많은 팀이 바로 enabled=false를 넣고 넘어가고 싶어진다. 하지만 2026년 7월 30일 기준 Spring Cloud와 Spring Boot 공식 문서를 같이 보면 verifier는 Boot 버전과 release train 정렬 상태를 알려 주는 관문이고, Boot는 관리형 의존성 버전을 기본으로 끌고 간다. 이 글은 verifier를 끌지, compatible-boot-versions로 임시 허용할지, release train 정렬로 끝낼지를 어떤 순서로 나눠야 하는지 정리한 것이다.

1. 개요

결론부터 말하면 기본 해법은 release train과 BOM 정렬이다. compatible-boot-versions override는 짧은 검증 창을 여는 임시 장치로, enabled=false는 즉시 장애 완화가 필요한 극히 제한된 우회로 보는 편이 안전하다. verifier는 부팅을 귀찮게 막는 옵션이 아니라 문서상 호환 조합을 벗어났다는 신호다.

또 verifier를 통과했다고 끝이 아니다. Spring Boot가 관리하는 의존성 버전과 Cloud starter 수동 핀이 어긋나면 OpenFeign 같은 후속 starter 층에서 다시 문제가 날 수 있다. 그래서 verifier 대응과 starter 버전 정리를 한 묶음으로 봐야 한다.

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

현장에서 주로 꼬이는 지점은 세 가지다. 첫째, verifier 차단을 곧바로 꺼 버리고 왜 나중에 다른 starter에서 깨졌는지 원인을 잃는다. 둘째, release train은 맞췄는데 build 파일에 남아 있던 수동 버전 핀이 계속 drift를 만든다. 셋째, override와 disable을 둘 다 '임시'라고 적어 두지만 종료 조건이 없어 그대로 고착된다.

Spring Cloud 문서는 verifier를 비활성화하는 속성과 compatible Boot versions override 속성을 둘 다 제공한다. 동시에 Spring Boot 문서는 관리형 의존성은 직접 버전을 적지 않아도 된다고 설명한다. 이 둘을 같이 보면 팀이 져야 할 책임의 크기가 달라진다. 문서에 없는 조합을 열수록 그 뒤 검증 책임은 팀에게 넘어온다.

특히 OpenFeign, Gateway처럼 애플리케이션 표면이 큰 Cloud starter는 부팅만 통과해도 끝났다고 보기 어렵다. verifier는 Boot 조합을 먼저 검사할 뿐이고, 실제 런타임 증상은 starter 계층에서 나중에 드러날 수 있다.

증상: verifier가 막혀서 우선 부팅부터 통과시키고 싶다.
실패: enabled=false를 장기 해법처럼 남겨 둔다.
막힘: release train을 맞췄는데 수동 starter 버전 핀을 안 걷는다.
누락: override와 disable의 만료 조건을 남기지 않는다.

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

실무 순서는 네 단계가 가장 실용적이다. 먼저 release train과 BOM 정렬로 해결 가능한지 본다. 다음으로 검증 창을 잠깐 열어야 한다면 compatible-boot-versions로 범위를 명시한다. 세 번째로 즉시 장애 완화가 아니면 enabled=false를 기본 선택지로 두지 않는다. 마지막으로 부팅이 통과한 뒤에는 OpenFeign·Gateway 같은 실제 starter 동작을 별도 체크리스트로 검증한다.

release train과 BOM 정렬 가능 여부를 먼저 판단한다.
임시 검증 창이면 compatible-boot-versions override 범위를 작게 둔다.
enabled=false는 긴급 상황과 종료 일정이 있을 때만 쓴다.
부팅 후에는 수동 starter 버전 핀과 runtime starter 동작을 다시 본다.

업그레이드 기록에는 build 파일의 버전 필드, 설정 경로, verifier 로그, OpenFeign starter 표를 같이 남겨 두는 편이 좋다. 어떤 메뉴에서 무엇을 클릭했는지보다 어떤 설정을 확인했고 어떤 오류 로그가 사라졌는지, 어떤 비교 표에서 어느 셀을 바꿨는지가 더 중요하다. 문서 화면의 강조 박스, 표, 경로, 필드, 로그 순서를 그대로 따라가며 마지막 smoke test 응답까지 확인하면 회고가 짧아진다.

검증 메모 예시

boot_version=4.1.0
release_train=checked
manual_starter_version=removed
verifier_enabled=true
compatible_boot_versions=4.1.x
post_boot_check=OpenFeign smoke test

이 구조를 잡아 두면 '왜 verifier를 껐지'가 아니라 '왜 이 조합을 잠시 허용했지'로 기록이 바뀐다. 업그레이드는 통과 자체보다 재현 가능한 기준을 남기는 쪽이 중요하다.

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

첫 자료는 Spring Cloud compatibility verification 구간이다. verifier가 무엇을 검증하는지부터 먼저 읽어야 disable과 override 판단이 덜 감정적으로 된다.

Spring Cloud 문서는 compatibility verifier가 현재 classpath의 Spring Boot 버전을 기준으로 호환성을 검사한다고 설명한다.

즉 verifier는 귀찮은 경고가 아니라 release train과 Boot 조합이 문서 기준에서 벗어났는지 알려 주는 첫 관문이다.

두 번째 자료는 verifier 속성 설명이다. 문서는 enabled=false와 compatible-boot-versions override 경로를 둘 다 적고 있다.

Spring Cloud 문서는 verifier 비활성화와 compatible-boot-versions override 속성을 모두 제공한다.

그래서 질문은 '속성이 있느냐'가 아니라 '언제를 어떤 책임으로 쓰느냐'가 된다. 둘 다 가능하다고 해서 둘 다 같은 수준의 해법은 아니다.

세 번째 자료는 Spring Boot dependency management 설명이다. Boot는 보통 버전을 직접 쓰지 않아도 관리형 의존성 목록으로 함께 올린다고 적고 있다.

Spring Boot 문서는 관리형 의존성 버전을 직접 지정하지 않는 편이 기본이라고 설명한다.

즉 verifier를 넘겼더라도 starter 버전을 직접 박아 두었다면 다른 층에서 다시 어긋날 수 있다. Boot와 Cloud를 같이 올릴 때 수동 버전 핀을 함께 점검해야 하는 이유다.

네 번째 자료는 OpenFeign 문서다. verifier는 Boot 버전 호환을 먼저 보지만, 실제 앱은 이런 starter 계층에서 동작한다는 점을 후속 예시로 볼 수 있다.

OpenFeign 같은 Cloud starter 동작은 verifier 통과 이후에도 실제 관리 버전 조합의 영향을 받는다.

그래서 verifier를 억지로 비활성화해 통과시켜도 starter 조합이 어긋난 채 남을 수 있다. 특히 OpenFeign, Gateway처럼 런타임 표면이 큰 starter는 후속 확인이 필요하다.

다섯 번째 자료는 disable, override, align 세 선택지를 실제 운영 기준으로 나눈 표다. 긴급 우회와 장기 해법을 같은 칸에 두지 않는 것이 핵심이다.

verifier disable, compatible-boot-versions override, release train 정렬을 언제 쓰는지 정리한 표다.

이미 release train과 BOM 정렬 글이 왜 verifier가 막히는지를 다뤘다면, 이번 표는 막힌 뒤 어떤 우회가 어디까지 허용되는지를 더 좁힌 후속편이다.

여섯 번째 자료는 설정 예시다. 임시 override와 임시 disable을 코드 레벨에서 어떻게 구분해 적어 두는지 보면 운영 책임선이 분명해진다.

중요한 점은 둘 다 만료 조건과 재정렬 일정이 같이 있어야 한다는 것이다. 설정 한 줄만 남기면 나중에는 왜 이 예외가 생겼는지 맥락이 사라진다.

마지막 자료는 triage 흐름도다. verifier 차단, 관리 버전 drift, starter 후속 검증을 같은 흐름으로 묶어 두면 업그레이드 회고가 쉬워진다.

verifier 차단 시 release train 정렬, override, disable을 고르는 triage 흐름도다.

또 JDK 26 native owner 추적 글처럼 런타임 증상 추적이 이미 시작된 상태라면, verifier 차단을 억지로 끄는 것보다 관리 버전 정렬부터 끝내는 편이 원인 수를 더 줄인다.

5. 주의사항과 리스크

첫 번째 리스크는 enabled=false를 남겨 두고 이후 런타임 이상을 전부 다른 원인으로 돌리는 것이다. 두 번째 리스크는 compatible-boot-versions override를 실험용으로 열어 놓고 영구 설정처럼 굳히는 것이다. 세 번째 리스크는 Spring Boot 관리 버전 철학을 무시한 채 starter 버전 수동 핀을 계속 쌓는 것이다.

운영 문서에는 최소한 release train 목표 버전, 임시 override 범위, disable 종료 시점, 부팅 후 검증할 starter 목록을 같이 적어 두는 편이 좋다. 그래야 다음 업그레이드 때 같은 우회를 복사하지 않게 된다.

verifier를 끄는 것은 해법이 아니라 책임 이동일 수 있다.
override는 범위와 만료 시점이 함께 있어야 한다.
관리형 의존성 원칙을 벗어났다면 후속 starter 검증이 더 중요해진다.

6. 결론

Spring Cloud compatibility verifier가 막힐 때는 release train 정렬을 기본 해법으로 두고, compatible-boot-versions override는 짧은 검증 창, enabled=false는 긴급 우회로만 다루는 편이 안전하다. 부팅이 통과한 뒤에도 수동 starter 버전 핀과 OpenFeign 같은 후속 starter 동작을 같이 확인해야 업그레이드가 덜 꼬인다.

만약 지금 고민이 release train 정렬 자체보다 verifier를 통과한 뒤에도 OpenFeign starter CI가 왜 깨지는지라면, 후속 글인 OpenFeign starter 버전 핀과 BOM drift 점검 글로 이어 가면 starter smoke test와 dependency tree를 어떤 순서로 다시 봐야 하는지 더 좁게 정리할 수 있다.

기본 해법은 release train과 BOM 정렬이다.
override와 disable은 같은 수준의 선택지가 아니다.
부팅 후 starter 동작 검증까지 마쳐야 업그레이드가 끝난다.