117 lines
11 KiB
Markdown
117 lines
11 KiB
Markdown
---
|
|
title: "GraalVM Native Image with Spring Boot 3 — Official Reference"
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-boot/reference/packaging/native-image/introducing-graalvm-native-images.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-skeleton, container, runtime, graalvm, native-image, spring-boot, aot, official-doc, branch:feature-container-runtime-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-container-runtime-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 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 `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."
|
|
|
|
> [§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 의 통합 테스트 패턴
|
|
|
|
## 메모 / 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:
|
|
- [[raw/branch-notes/feature-container-runtime-contract]]
|
|
- 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
|