bootBuildImage і buildpacks

1. Роль bootBuildImage у курсі

Якщо ви вивчаєте Spring Boot, дуже легко потрапити в пастку: «упакування — це щось для DevOps, мені б дописати контролер». На практиці упакування — це продовження архітектури. Коли застосунок перестає жити лише в IDE, вам потрібен відтворюваний спосіб перетворити проєкт на артефакт, який можна запускати. А коли артефакт має жити в контейнерному середовищі, важливо, щоб цей перехід не перетворювався на окрему ручну науку для кожного проєкту.

Шари вам уже знайомі: ви вмієте бачити їх у jar і розкладати по каталогах. Тепер логічне запитання інше — хто взагалі використовує цю структуру, коли jar перетворюється на контейнерний образ.

Ідея сьогоднішньої лекції проста: Spring Boot не змушує вас одразу писати Dockerfile «з нуля». Натомість він пропонує платформний підхід: зібрати контейнерний образ через buildpacks, використовуючи вже знайому модель упакування та шари. Ми залишаємося в екосистемі Boot: вивчаємо вхід (bootBuildImage), розуміємо вихід (готовий образ), читаємо логи, але не скочуємося в глибокий Docker-тюнінг, мережеві політики, оркестрацію та інші радощі дорослого життя.

Щоб зафіксувати межу, тримайте просту думку. Ми не вчимося «жити в контейнері». Ми вчимося робити артефакт, зручний для контейнерів, і розуміти, як Boot уміє упакувати його далі.

2. Cloud Native Buildpacks

Коли вперше чуєш слово buildpacks, мозок часто реагує так: «ага, чергова магічна коробка». Але насправді buildpacks — це дуже прагматична ідея: якщо в нас типове застосування (наприклад, Java + jar), то можна описати збирання контейнерного образу як набір повторно використовуваних кроків, а не як унікальний Dockerfile на кожен проєкт.

Уявіть, що Dockerfile — це як рецепт, який ви пишете вручну: «візьми базовий образ», «скопіюй jar», «налаштуй ENTRYPOINT», «додай користувача», «встанови змінні»… Усе це нормально, але це ще й купа місць, де новачок помилиться, а команда потім буде виправляти.

Buildpacks працюють інакше. Вони схожі на «автокухаря» (так, звучить як кухонний гаджет, який ви купили вночі на маркетплейсі): ви приносите йому застосунок, а він за правилами платформи вирішує, як його зібрати. Усередині там є кілька ключових ролей, і корисно знати їх хоча б на рівні понять.

По-перше, є builder image — «збірний образ». У ньому живуть інструменти, які вміють збирати ваш застосунок в образ за правилами buildpacks. По-друге, є buildpacks як набори логіки «як розпізнати проєкт» і «як його зібрати». Для Java це зазвичай означає: зрозуміти, що перед вами jar/gradle/maven, визначити версію Java, покласти залежності й застосунок у шари, налаштувати запуск. По-третє, є run image — мінімальна «бігова доріжка», на якій уже запускається результат. Тобто кінцевий образ зазвичай не тягне за собою весь збірний інструментарій.

Якщо хочеться дуже приземленої схеми, то вона приблизно така:

flowchart TD
    A[Проєкт catalog-service] --> B[bootJar: виконуваний jar]
    B --> C[bootBuildImage]
    C --> D["Збірний образ (buildpacks)"]
    D --> E[Готовий контейнерний образ]

Ключове: buildpacks — це не бібліотека і не dependency в dependencies { ... }. Це механізм упакування, який живе поруч із вашим build-циклом. І Spring Boot як платформа дає вам «кнопку» для цього механізму — bootBuildImage.

3. Задача bootBuildImage

Перед тим як натиснути кнопку, корисно зрозуміти, хто її додав. Задачу bootBuildImage приносить Spring Boot Gradle Plugin — той самий, який уже подарував нам bootRun і bootJar. Тобто це не стороння магія, а логічне продовження історії з упакуванням, лише на наступному рівні.

Перевірити, що задача існує, можна звичним способом — через Gradle:

# Шукаємо задачу в списку всіх доступних задач Gradle
./gradlew tasks --all | grep -n "bootBuildImage"

Або, щоб побачити все більш читабельно, попросити Gradle розповісти про задачу:

# Дивимося опис задачі та основні параметри
./gradlew help --task bootBuildImage

Тепер про важливий побутовий момент, який часто псує студентам настрій: bootBuildImage майже завжди використовує локальний контейнерний runtime, найчастіше Docker. Якщо Docker або Podman не встановлено чи не запущено, задача впаде — і це не тому, що ви поганий програміст, а тому, що збирання образу за визначенням має «кудись» цей образ покласти.

У межах Boot-курсу ми не робимо з цього трагедію. Можна розуміти механіку, читати логи і навіть налаштувати задачу, не перетворюючись на контейнерного інженера. Але якщо хочеться справді виконати команду, переконайтеся, що контейнерний runtime доступний.

Мініперевірка — максимально без «курсу Docker», просто факт, чи працює команда:

# Перевіряємо, чи доступний Docker Engine (без цього образ нікуди не "експортувати")
docker version

Якщо команда відгукується і показує версії клієнта та сервера — зазвичай усе гаразд, можна пробувати bootBuildImage.

4. Запуск bootBuildImage і логи

Коли ви вперше запускаєте bootBuildImage, це часто виглядає як «команда, яка щось довго робить і багато пише». Це нормально: перший запуск зазвичай завантажує builder-образи й кешує шари, тому може зайняти помітний час. Важливіше інше: цей вивід можна читати, і там справді є сенс.

Базова команда така:

# Збираємо контейнерний образ через buildpacks
./gradlew bootBuildImage

Якщо ви хочете більше подробиць, іноді це корисно, щоб не думати «воно зависло?», можна додати --info:

# Додаємо докладний лог, щоб розуміти, на якому кроці збирання ми зараз перебуваємо
./gradlew bootBuildImage --info

Якщо описати процес без зайвих низькорівневих деталей, але чесно, то все відбувається так:

Спочатку Gradle та Boot plugin забезпечують, що у вас є підсумковий артефакт застосунку. Зазвичай це означає, що буде зібрано jar: по суті, bootJar є частиною ланцюжка. Потім Boot передає цей jar у механізм buildpacks. Buildpacks виконують детект — розпізнають, що перед ними Java-застосунок, яким способом він запускається і яка версія Java потрібна, — після чого збирають шари майбутнього образу, упаковують їх і «експортують» готовий образ у локальний контейнерний runtime.

Щоб не губитися в термінології, корисно тримати в голові просту трійку: вхід → обробка → вихід.

вхід:  build/libs/<наш executable jar>
крок:  buildpacks (детект → збирання шарів → упакування)
вихід: container image (у локальному docker images)

Це і є головна вправа на демістифікацію. bootBuildImage — не чарівна кнопка, а зрозумілий pipeline: він бере артефакт, проганяє його через стандартизований механізм упакування і створює образ.

Якщо ви хочете побачити результат очима людини, яка не лізе в деталі buildpacks, можна просто подивитися список образів:

# Перевіряємо, що образ справді з'явився в локальному списку образів
docker images | grep catalog-service

Так, це вже команда Docker, але рівно в мінімально достатньому обсязі: переконатися, що результат справді з'явився.

5. Layered jar і шари образу

Тепер важливо пов’язати те, що ви вже зробили в лекціях 2–3 (layered jar), з тим, що робить bootBuildImage. Інакше виникне відчуття, ніби ми вивчили шари, а потім прийшов bootBuildImage і все зробив по-своєму. Насправді bootBuildImage — це продовження тієї самої ідеї: рідко змінюване відокремлюємо від того, що змінюється часто.

Коли buildpacks збирають образ, вони намагаються розкласти вміст так, щоб під час повторного збирання можна було перевикористати вже готові шари. На практиці це означає приблизно таку логіку:

- залежності, тобто ваші starter-и і все, що приїхало транзитивно, змінюються рідко — отже, їх вигідно тримати окремо;
- код і ресурси застосунку змінюються часто — отже, це окремий шар;
- службові частини, які потрібні для запуску, теж мають бути стабільними і не перезбиратися через правку одного контролера.

Якщо у вас layered jar, у ньому вже є ця «карта шарів» (layers.idx). Інструменти, зокрема buildpacks, можуть використовувати її як підказку: як саме розділити вміст застосунку на частини, які варто кешувати окремо.

Тут важлива не «контейнерна філософія», а дуже практична інженерна вигода. Уявіть, що ви змінили один метод у CourseCatalogController. Без шарів повторне збирання образу може заново перетягувати й укладати купу бібліотек, хоча вони не змінювалися. Із шарами набагато більше шансів, що перезбереться лише application-частина, а шар залежностей буде перевикористано.

Це якби ви збирали рюкзак щодня. Якщо ви щоразу перекладаєте туди ноутбук, зарядний пристрій, документи, аптечку й ще 20 речей, то це довго. А якщо у вас є постійний набір в одному відділенні, і ви змінюєте тільки бутерброд і футболку — процес різко прискорюється. Так, аналогія побутова, але сенс саме такий.

6. Мінімальне налаштування bootBuildImage

За замовчуванням bootBuildImage цілком здатний працювати без конфігурації: ви запускаєте задачу, отримуєте образ. Але в навчальному проєкті корисно зробити одне маленьке налаштування, яке підвищує передбачуваність: задати імʼя образу. Тоді ви не будете щоразу гадати, як він називається і який тег у версії.

У Gradle це зазвичай виглядає так — максимально коротко і зрозуміло:

// build.gradle.kts
import org.springframework.boot.gradle.tasks.bundling.BootBuildImage

tasks.named<BootBuildImage>("bootBuildImage") {
    // Явно задаємо імʼя образу, щоб його легко було знайти в `docker images`
    imageName.set("catalog-service:local")
}

Ці 2–3 рядки дають вам дуже відчутну користь. Тепер після збирання ви очікуєте образ із конкретним імʼям, і його легко знайти та відрізнити від інших.

Якщо хочеться трохи реалістичніше імʼя, можна прив’язати його до версії проєкту. Але тут важливо не перетворювати лекцію на обговорення релізної стратегії. Достатньо розуміти, що в Gradle у проєкту є name і version, і їх можна використовувати.

Наприклад, так:

// build.gradle.kts
import org.springframework.boot.gradle.tasks.bundling.BootBuildImage

tasks.named<BootBuildImage>("bootBuildImage") {
    // Зручно для локальних збірок: тег збігається з версією вашого проєкту
    imageName.set("${project.name}:${project.version}")
}

Ще один нюанс, який корисно знати саме в Java-курсі: образ має містити правильну версію Java. Найчастіше Boot і buildpacks самі визначають це коректно, особливо якщо у вас налаштовано Java toolchain. Але якщо ви раптом побачили, що в процесі збирання вибирається не та версія, існує стандартний механізм buildpacks через змінні середовища. У навчальному форматі достатньо побачити, що такий механізм є:

// build.gradle.kts
import org.springframework.boot.gradle.tasks.bundling.BootBuildImage

tasks.named<BootBuildImage>("bootBuildImage") {
    // Підказуємо buildpacks, яку версію JVM використовувати під час збирання образу
    environment.put("BP_JVM_VERSION", "25")
}

Зверніть увагу на стиль: ми не додали жодної залежності, не чіпали код застосунку, не переписували CatalogServiceApplication. Ми просто налаштували задачу збирання артефакту. Це і є основний платформний підхід Boot: прикладний код залишається прикладним, а упакування — упакуванням.

Якщо після цього запустити:

# Запускаємо збирання образу вже із заданими параметрами з build.gradle.kts
./gradlew bootBuildImage

то ви отримаєте образ з очікуваним імʼям і зможете хоча б перевірити його існування через docker images. Усе інше — запуск, порти, змінні середовища, файлові системи — це вже окремий світ, який ми свідомо не відкриваємо в цій лекції.

7. Типові помилки під час роботи з bootBuildImage

Після гарної теорії майже завжди настає момент «а чому в мене не збирається?». І це нормально: bootBuildImage стоїть на межі між Java-збиранням і контейнерним середовищем, а на межах зазвичай найбільше сюрпризів. Хороша новина в тому, що найчастіші проблеми доволі типові, і їх можна навчитися розпізнавати за симптомами — без паніки та без відчуття «я нічого не розумію».

Помилка № 1: сприймати buildpacks як залежність і намагатися додати їх у dependencies { ... }.
Якщо ви ловили себе на думці «а де стартер spring-boot-starter-buildpacks?», то ви в хорошій компанії — це часта реакція новачка. Buildpacks не живуть на classpath застосунку. Вони живуть у build-процесі, і вхід до них — задача bootBuildImage. Тому правильне місце для налаштування — Gradle task або блок springBoot, а не залежності проєкту.

Помилка № 2: очікувати, що bootBuildImage замінює bootJar.
Іноді здається: «раз я зібрав образ, jar уже не потрібен». Насправді bootBuildImage майже завжди спирається на артефакт застосунку, а jar залишається вашим базовим, переносним і перевірюваним результатом. Навіть якщо ви збираєте образ, розуміння executable jar — це фундамент. Якщо jar не збирається, образ теж не буде «магічно» збиратися.

Помилка № 3: Docker або контейнерний runtime не встановлено чи не запущено, і задача падає.
Це найпоширеніша технічна помилка. З точки зору Boot усе нормально: він чесно намагається зібрати образ. Але йому нікуди його покласти, якщо у вас немає доступного runtime. У межах курсу правильна реакція тут спокійна: або увімкнути чи встановити runtime, якщо ви до цього готові, або сприймати bootBuildImage як оглядовий механізм і фокусуватися на layered jar та розумінні шарів.

Помилка № 4: перший запуск надто довгий, і здається, що все зависло.
Перший запуск часто тягне builder image і кеші, тому може бути помітно повільнішим за наступні. Це не «Boot гальмує», а нормальна ціна за те, що ви вперше створюєте середовище збирання образів. Якщо хочеться трохи більше прозорості, використовуйте ./gradlew bootBuildImage --info і просто спостерігайте, що процес іде кроками, а не висить.

Помилка № 5: намагатися одразу налаштувати все — builder, run image, registry, політики завантаження, проксі, сертифікати…
Це типова інженерна тяга до контролю, і вона хороша. Але зараз, у неправильний час. У навчальному проєкті цінніше отримати робочий базовий варіант і зрозуміти механіку «вхід → buildpacks → вихід». Складні налаштування майже завжди потрібні в конкретному інфраструктурному середовищі та під конкретні вимоги, а без цих вимог вони перетворюються на ворожіння й безсистемне копіювання.