티스토리 뷰

Spring

[SpringBoot] 도커 이미지 빌드 최적화를 위한 Layered Jar

망나니개발자 2026. 9. 1. 10:00

 

 

 

 

1. 도커 이미지 빌드 최적화를 위한 Layered Jar


[ 기존 Fat JAR 방식의 문제와 Layered Jar의 등장 ]

기존 Fat JAR 방식의 문제점

Layered Jar란 스프링 부트 애플리케이션을 위한 Docker 이미지를 만들 수 있도록 도와주는 도구이다. 표준 jar 스펙은 jar 내부에 jar 파일을 가질 수 없다. 하지만 애플리케이션을 개발하다 보면 많은 외부의 프레임워크와 라이브러리를 사용하게 되어 다른 Jar가 필요해진다. 따라서 스프링 부트는 jar 내부에 다른 jar를 가지면서 java -jar로 실행할 수 있는 "fat jar" 형식을 예전부터 지원해 왔다. 이러한 fat jar 내부 구성은 다음과 같다.

 

 

이러한 fat jar를 도커 이미지로 만드는 것은 어렵지 않다. 하지만 fat jar 그대로 도커 이미지로 복사해 사용하면 비효율적인 부분이 많다. 대개 변경되는 것은 사용자 코드인데, 상대적으로 변경이 적은 라이브러리/프레임워크 파일들까지 포함된 단일 jar 파일을 매번 새로운 도커 이미지로 만들어야 하기 때문이다. 따라서 사용자 애플리케이션 클래스와 라이브러리 모음을 분리시켜서, 변경된 사용자 애플리케이션 부분만 Docker 레이어에 갈아 끼우고 나머지는 캐시에서 사용하는 구조를 고안하게 되었다.

 

 

Layered Jar 방식의 등장

앞서 설명하였듯 fat jar 형식은 jar 표준 기술이 아닌 스프링 부트만의 자체적인 포맷이다. 따라서 스프링 부트는 2.3부터 이 jar 내부에 레이어 인덱스 파일을 추가하는 기능을 넣었다. 여러 가지 변천사가 있었지만 지금은 jar 내부 구조를 fat jar와 동일하게 두되, BOOT-INF/layers.idx 라는 인덱스 파일 하나만 추가한다.

이 파일은 우리가 직접 만드는 것은 아니고, Spring Boot Gradle 플러그인의 bootJar 태스크가 만든다. 스프링 부트 2.3 에서는 layered { enabled = true } 로 직접 활성화를 해야 했지만, 2.4 부터는 기본 활성화되어 아무 설정 없이도 기본 4개 레이어로 layers.idx 가 생성되고 MANIFEST 에 Spring-Boot-Layers-Index 가 선언된다. BootJar 태스크는 이 설정을 해석해 BOOT-INF/layers.idx 를 생성한다. 이 파일에는 레이어 목록과 각 레이어에 속하는 경로가 적혀 있고, 목록의 순서가 곧 이미지에 쌓을 순서다. 기본 레이어는 다음과 같다.

  • dependencies: 외부 프레임워크/라이브러리 의존성 모음
  • spring-boot-loader: org/springframework/boot/loader 아래의 모든 코드
  • snapshot-dependencies: 버전에 SNAPSHOT 이 붙은 의존성
  • application: 사용자 애플리케이션 클래스와 리소스 및 프로젝트 의존성 등

 

 

이 구성은 애플리케이션 빌드 시의 변경 빈도에 따라 구분되었다. 라이브러리 코드는 변경이 적으니 레이어를 분리시켜 캐시에서 재사용하게 했다. 반면 애플리케이션 코드는 빌드마다 바뀔 가능성이 크다. 따라서 기존에는 매번 하나의 app.jar를 도커 이미지에 푸시했다면, 이제는 변경이 있는 애플리케이션 부분만 푸시하면 되는 것이다.

 

 

 

[ jarmode에 대하여 ]

jarmode의 등장

스프링 부트가 나눈 레이어를 도커 이미지로 만들려면 결국 dockerfile을 써야 한다. 그런데 Docker의 규칙과 스프링 부트의 jar 방식 사이에 호환되지 않는 부분이 있다.

dockerfile에서 이미지 레이어를 만드는 단위는 COPY 명령 한 줄이다. COPY 를 네 번 쓰면 레이어가 네 개 생긴다. 따라서 레이어를 넷으로 나누려면, 이미지를 빌드하는 시점에 디스크 위에 각 4계층의 최상위 폴더가 네 개 있어야 한다. 그래서 각 폴더를 한 번씩 COPY 하는 것이다.

dependencies/           <- COPY 한 번 = 이미지 레이어 하나
spring-boot-loader/     <- COPY 한 번
snapshot-dependencies/  <- COPY 한 번
application/            <- COPY 한 번

 

 

그런데 jar는 내부적으로 fat jar 구조이므로, 그냥 jar 압축을 풀면 도커 이미지 레이어와 호환되지 않는 폴더 구조가 나온다.

org/springframework/boot/loader/...
BOOT-INF/classes/...
BOOT-INF/lib/library1.jar
BOOT-INF/lib/lib3-SNAPSHOT.jar
BOOT-INF/layers.idx

 

 

따라서 파일 이름만 봐서는 해당 디렉토리의 어떤 파일이 각각 dependencies 이고, 어떤 것이 snapshot-dependencies 인지 구분할 수 없고, 인덱스를 읽어야 비로소 알 수 있다. 또한 로더 클래스(org/springframework/boot/loader/...)는 jar 스펙상 반드시 jar 루트에 있어야 java -jar 로 실행되는데, 도커 이미지에서는 루트로 존재하지 못한다.

 

 

이 문제를 해결하려면 우리는 layers.idx 를 읽고, 파일을 레이어별로 분류하고, 최상위 폴더로 옮기고, 로더 클래스는 따로 챙겨야 한다. 이는 결국 unzip 과 mv 의 조합일 뿐이지만 매번 직접 짜기 번거롭다. 따라서 스프링 부트는 이 일을 jar 기능인 jarmode로 제공하게 되었다. 

jarmode는 jar를 실행할 때 주는 시스템 프로퍼티로, 부트스트랩 코드가 애플리케이션 구동 대신 완전히 다른 일을 하게 한다. 예를 들면 레이어를 추출하는 일이다. 이 기능은 spring-boot-jarmode-tools jar가 담당하는데, 기본으로 함께 포함된다.

 

 

jarmode의 사용 예시

다음과 같이 jarmode를 속성으로 주고 실행할 수 있다. 그러면 다음과 같이 실행 가능한 명령어들을 알려준다.

mangkyu@mangkyu-5b21 % java -Djarmode=tools -jar my-app.jar
Usage:
  java -Djarmode=tools -jar my-app.jar

Available commands:
  extract      Extract the contents from the jar
  list-layers  List layers from the jar that can be extracted
  help         Help about any command

 

 

그리고 다음과 같이 필요한 명령어를 수행할 수 있다. 예를 들어 레이어 목록을 조회하면 다음과 같은 결과를 얻을 수 있다.

mangkyu@mangkyu-5b21 % java -Djarmode=tools -jar my-app.jar list-layers
dependencies
spring-boot-loader
snapshot-dependencies
application

 

 

jar 파일을 각 레이어로 압축 해제해서 복사하는 dockerfile을 작성할 수 있는 것이다. 다음은 멀티 스테이지 dockerfile로, builder 스테이지가 나중에 필요한 폴더를 추출한다. 그리고 각 COPY 명령은 앞에서 나열한 레이어와 하나씩 대응된다.

# Perform the extraction in a separate builder container
FROM bellsoft/liberica-openjre-debian:25-cds AS builder
WORKDIR /builder

# This points to the built jar file in the target folder
# Adjust this to 'build/libs/*.jar' if you're using Gradle
ARG JAR_FILE=target/*.jar

# Copy the jar file to the working directory and rename it to application.jar
COPY ${JAR_FILE} application.jar

# Extract the jar file using an efficient layout
RUN java -Djarmode=tools -jar application.jar extract --layers --destination extracted

# This is the runtime container
FROM bellsoft/liberica-openjre-debian:25-cds
WORKDIR /application

# Copy the extracted jar contents from the builder container into the working directory in the runtime container
# Every copy step creates a new docker layer
# This allows docker to only pull the changes it really needs
COPY --from=builder /builder/extracted/dependencies/ ./
COPY --from=builder /builder/extracted/spring-boot-loader/ ./
COPY --from=builder /builder/extracted/snapshot-dependencies/ ./
COPY --from=builder /builder/extracted/application/ ./

# Start the application jar - this is not the uber jar used by the builder
ENTRYPOINT ["java", "-jar", "application.jar"]

 

 

참고로 과거에는 jarmode=layertools로 제공이 되었는데, 해당 모드는 Boot 3.3 에서 deprecated 되고 4.1.0(2026-06-10 GA)에서 제거되었다. 

다만 tools는 layertools의 이름만 바꾼 것이 아니라, 추출 결과의 구조 자체가 다르다. layertools는 실제로 mv 명령어로 재배치만 한 것이므로, 각 레이어 안에 BOOT-INF/lib/, BOOT-INF/classes/ 같은 원래 경로를 그대로 유지했다. 그래서 COPY로 겹쳐 쌓으면 원래 fat jar 구조가 복원되었고, 내부에 jar 파일이 없기 때문에 JarLauncher를 직접 지목해 실행해야 했다.

 

 

반면 tools는 의존성을 lib/ 아래로 평탄화하고, application 레이어에는 클래스 파일 대신 새로 만든 얇은 jar를 넣는다. 이 얇은 jar에는 애플리케이션 코드와 lib/를 가리키는 참조만 들어 있어서, 합쳐진 결과를 평범한 java -jar로 실행할 수 있다. 레이어로 나뉘지 않고 앱이름/앱이름.jar와 앱이름/lib/ 한 벌만 만들어지도록 한 것은, 이 레이아웃이 CDS와 AOT 캐시에 유리하기 때문이다.

 

 

--layer 옵션을 주면 추출 결과를 레이어별 폴더로 나눠 담을 수 있다. 또한 --launcher 옵션도 존재한다. 이 옵션을 주고 사용하면 이의 layertools와 완전히 동일한 구조로 추출이 가능하다.

 

 

[ Layered Jar의 동작 방식 ]

전반적인 Layered Jar의 동작 방식을 빌드 시점부터 따라가보자.

먼저 Spring Boot 2.4부터 레이어링이 기본으로 켜져 있어서, 계층을 커스터마이징 할 것이 아니라면 build.gradle.kts 에 layered { } 를 선언하는 등의 추가적인 작업이 필요 없다. BootJar 태스크가 기본 네 개 레이어를 알아서 만든다.

그 결과 산출물 jar 안에 BOOT-INF/layers.idx 가 들어간다. 인덱스 파일의 위치는 매니페스트의 Spring-Boot-Layers-Index 에 적히고, jarmode 는 이 값을 보고 인덱스를 찾는다. 앞에서 본 것처럼 jar의 파일 구조 자체는 평범한 fat jar 그대로이고, 늘어난 것은 이 인덱스 파일 하나뿐이다.

이미지를 빌드할 때는 builder 스테이지가 jarmode=tools extract --layers --launcher 로 jar를 푼다. --layers 가 인덱스를 읽어 레이어별 폴더로 나누고, --launcher 가 엔트리를 원본 경로 그대로 꺼낸다. 그다음 폴더마다 COPY 를 한 줄씩 쓴다. COPY 한 줄이 이미지 레이어 하나이므로 네 줄이면 레이어가 넷이 된다.

그렇게 이미지 레이어가 만들어진다. 아래일수록 덜 바뀌는 것이 깔리고, 맨 위 application 만 배포마다 새로 만들어진다.

  • dependencies 172.3MB — 버전을 올리기 전까지 그대로다
  • spring-boot-loader 0.6MB — 부트 버전을 올릴 때만 바뀐다
  • snapshot-dependencies 0MB — 스냅샷 의존성을 쓰지 않아 비어 있다
  • application 1.8MB — 배포마다 새로 생성된다

 

 

프로젝트 의존성, 즉 멀티모듈 산출물은 기본적으로 application 레이어에 들어간다. 그래서 배포마다 새로 올라가는 것은 이 1.8MB뿐이고, 172.3MB짜리 dependencies 는 캐시에서 그대로 재사용된다. fat jar를 통째로 넣던 방식과 갈리는 지점이 여기다.

 

 

 

 

참고 자료

 

 

 

 

 

댓글
공지사항
최근에 올라온 글
최근에 달린 댓글
Total
Today
Yesterday
링크
TAG more
«   2026/11   »
일 월 화 수 목 금 토
1 2 3 4 5 6 7
8 9 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30
글 보관함