11 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| GraalVM Native Image with Spring Boot 3 — Official Reference | official-doc | https://docs.spring.io/spring-boot/reference/packaging/native-image/introducing-graalvm-native-images.html | raw | high |
|
|
|
2026-05-22 | 2026-05-27 |
GraalVM Native Image with Spring Boot 3 — Official Reference
Layer:
raw/official-docs/— Spring Boot 공식 reference 의 GraalVM Native Image 절 + GraalVM 공식 문서 원문 발췌.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-container-runtime-contract | Group G-D container runtime 대안 3 (GraalVM native-image) 의 baseline 사실 — startup/memory 이점과 reflection/AOT 제약의 공식 출처 |
특정 branch 없이 foundational 조사로 수집한 경우:
- raw/project-notes/ca-skeleton-operational-contract — ca-tmpl 의 cold-start sensitive 워크로드 대응 시 native-image 채택 검토 자료
컨텍스트 / 왜 저장했는지
ca-tmpl feature-container-runtime-contract 에서 GraalVM native-image 는 Group G-D 대안 후보. JIT 기반 Temurin JRE slim 과의 trade-off — 시작 속도와 메모리 사용량은 압도적으로 유리하지만 reflection / dynamic proxy 측면에서 application code 제약이 따른다.
출처 / Source
- 원본 URL: https://docs.spring.io/spring-boot/reference/packaging/native-image/introducing-graalvm-native-images.html
- 보조 URL: https://www.graalvm.org/latest/reference-manual/native-image/
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Team (VMware/Broadcom) + Oracle GraalVM
- 발행일: Spring Boot 3.x reference (current, fetched 2026-05-27)
- 마지막 확인일: 2026-05-27
핵심 인용 / Key quotes (verbatim)
[§Introducing GraalVM Native Images — definition] "GraalVM Native Images provide a new way to deploy and run Java applications. Compared to the Java Virtual Machine, native images can run with a smaller memory footprint and with much faster startup times."
[§Build process] "Unlike traditional applications written for the JVM, GraalVM Native Image applications require ahead-of-time processing in order to create an executable. This ahead-of-time processing involves statically analyzing your application code from its main entry point."
[§Executable nature] "A GraalVM Native Image is a complete, platform-specific executable. You do not need to ship a Java Virtual Machine in order to run a native image."
[§Key differences with JVM — static analysis] "Static analysis of your application is performed at build-time from the
mainentry point. Code that cannot be reached when the native image is created will be removed and won't be part of the executable."
[§Key differences with JVM — dynamic elements] "GraalVM is not directly aware of dynamic elements of your code and must be told about reflection, resources, serialization, and dynamic proxies."
[§Key differences with JVM — class loading] "There is no lazy class loading, everything shipped in the executables will be loaded in memory on startup."
[§Best-suited applications] "They are well suited to applications that are deployed using container images and are especially interesting when combined with "Function as a service" (FaaS) platforms."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| CGN-C1 | GraalVM Native Image 는 JVM 대비 더 작은 memory footprint 와 더 빠른 startup 으로 Java 애플리케이션을 배포/실행하는 방법이다 | [§Introducing GraalVM Native Images — definition] "GraalVM Native Images provide a new way to deploy and run Java applications. Compared to the Java Virtual Machine, native images can run with a smaller memory footprint and with much faster startup times." | official-vendor-doc |
Spring Boot 3.x + GraalVM Native Image | "smaller" 와 "much faster" 의 정량값은 인용에 없음 — 워크로드별 측정 필요 |
| CGN-C2 | Native Image 빌드는 AOT (ahead-of-time) processing 을 필요로 하며, main entry point 에서 정적 분석을 수행하여 executable 을 생성한다 | [§Build process] "Unlike traditional applications written for the JVM, GraalVM Native Image applications require ahead-of-time processing in order to create an executable. This ahead-of-time processing involves statically analyzing your application code from its main entry point." | official-vendor-doc |
Spring Boot AOT processing 흐름 | AOT 처리 시간 / 메모리 비용은 인용 범위 밖 — CI 비용 계산 시 별도 측정 필요 |
| CGN-C3 | Native Image 는 완전한 platform-specific executable 이며 JVM 을 함께 배포할 필요가 없다 | [§Executable nature] "A GraalVM Native Image is a complete, platform-specific executable. You do not need to ship a Java Virtual Machine in order to run a native image." | official-vendor-doc |
container image / standalone binary 배포 | cross-compile 가능 여부 (Linux 호스트에서 Windows 바이너리 빌드 등) 는 인용 범위 밖 |
| CGN-C4 | Native Image 빌드 시 main entry point 에서 도달 불가능한 코드는 build-time 에 제거되어 executable 에 포함되지 않는다 | [§Key differences with JVM — static analysis] "Static analysis of your application is performed at build-time from the main entry point. Code that cannot be reached when the native image is created will be removed and won't be part of the executable." |
official-vendor-doc |
dead code elimination 결과 | dynamic 하게 reachable 한 코드 (reflection 통한 호출) 가 어떻게 처리되는지는 별도 claim CGN-C5 참조 |
| CGN-C5 | GraalVM 은 reflection · resources · serialization · dynamic proxies 같은 dynamic 요소를 직접 인식하지 못하며, 명시적으로 알려주어야 한다 | [§Key differences with JVM — dynamic elements] "GraalVM is not directly aware of dynamic elements of your code and must be told about reflection, resources, serialization, and dynamic proxies." | official-vendor-doc |
reflection-heavy Spring application | "어떻게 알려주는가" 의 구체 메커니즘 (RuntimeHints / reachability-metadata JSON) 은 본 인용에 명시 없음 — 별도 페이지 |
| CGN-C6 | Native Image 는 lazy class loading 이 없으며, executable 에 포함된 모든 것이 startup 시 메모리에 로드된다 | [§Key differences with JVM — class loading] "There is no lazy class loading, everything shipped in the executables will be loaded in memory on startup." | official-vendor-doc |
Native Image runtime model | startup 후 메모리 사용량이 실제로 더 작다는 주장과 모순처럼 보이나, 인용은 단지 "lazy 가 없음" 만 말함 — dead code elimination 으로 최종 RAM 이 작아짐 |
| CGN-C7 | Native Image 는 container image 로 배포되는 application 에 적합하며, FaaS 플랫폼과 결합 시 특히 흥미롭다 | [§Best-suited applications] "They are well suited to applications that are deployed using container images and are especially interesting when combined with "Function as a service" (FaaS) platforms." | official-vendor-doc |
FaaS / scale-to-zero / cold-start sensitive workload | 모든 container 배포에서 Native Image 가 더 낫다는 일반화는 아님 — "well suited" 와 "especially interesting" 의 조건부 표현 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
CGN-C1,CGN-C7: Native Image 의 정성적 benefit (startup, memory, FaaS 적합성)CGN-C2,CGN-C3: AOT 빌드 + standalone executable 의 정의CGN-C4,CGN-C5,CGN-C6: JVM 과의 핵심 차이 3개 (static analysis, dynamic 요소 명시 필요, no lazy class loading)
- 이 자료가 증명하지 않는 것:
- 정량 수치 (startup 단축률, RSS 메모리 절감 %, image 크기) — 인용은 모두 정성 표현
- 빌드 시간 / CI 비용 — Native Image 빌드는 분 단위로 길지만 본 인용에는 명시 없음
- peak throughput 비교 (JIT C2 의 profile-guided 최적화 부재로 인한 영향)
- 특정 Spring starter / 라이브러리의 Native Image 호환성 매트릭스
- RuntimeHints / reachability-metadata JSON 의 작성 방법 (별도 페이지)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 에서 사용하는 라이브러리들의 reachability-metadata 제공 여부 (
META-INF/native-image/...) - Spring Boot Gradle plugin (
org.graalvm.buildtools.native) 의 정확한 빌드 시간 측정 - Native Image 빌드된 ca-tmpl 의 cold-start time / RSS 실측
- Testcontainers + native executable 의 통합 테스트 패턴
- ca-tmpl 에서 사용하는 라이브러리들의 reachability-metadata 제공 여부 (
메모 / Notes (내 프로젝트 해석)
본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
- 적용 시나리오: serverless / FaaS, cold start 가 critical 한 워크로드, scale-to-zero 환경.
- 장점:
- cold start 가 수십 ms 단위 (JIT 대비 10배 이상 단축) — 별도 측정 필요, 본 인용은 정성 표현만.
- RSS 메모리 사용량 30-50% 감소 — 별도 측정 필요.
- container image 크기 축소 (JRE 미포함 시 ~80 MB 대) —
CGN-C3의 결과.
- 단점:
- 빌드 시간이 길어진다 (수 분 이상). CI 비용 증가.
- reflection / dynamic proxy / serialization 사용 시
reachability-metadata또는RuntimeHints등록 필수 —CGN-C5의 직접 결과. - Spring AOT processing 은 일부 starter (특히 oldschool reflection 기반 라이브러리) 와 호환성 검증이 필요.
- 런타임 profiling 기반 최적화 (JIT C2) 가 사라져 peak throughput 은 JIT 대비 낮을 수 있다.
- ca-tmpl 과의 차이: ca-tmpl 은 JIT 기반 Temurin JRE slim +
MaxRAMPercentage=75로 운영 친숙도를 우선. native-image 는 cold start 우선 워크로드 한정 옵션. - testability 영향: 하 — native-image 빌드 후의 동작 검증은 Testcontainers + native test 분리 필요.
- code 복잡도 영향: 상 —
RuntimeHintsRegistrar,@RegisterReflectionForBinding,META-INF/native-image/...메타데이터 관리 부담.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/container-distroless-google-github — 대안 1 Distroless
- raw/official-docs/container-alpine-java-musl-tradeoffs — 대안 2 Alpine + Temurin
- 적용 branch-note:
- canonical contract 섹션:
wiki/projects/ca-skeleton-operational-contract의 container runtime canonical section (예정)
- 대안 그룹: Group G-D — Container runtime 대안 후보군
- 본 source 의 위치: 대안 3 — GraalVM native-image (AOT) + Spring Boot Native