Docker: CMD проти ENTRYPOINT

Що роблять CMD і ENTRYPOINT

CMD та ENTRYPOINT — інструкції Dockerfile, які визначають, що саме запускається під час старту контейнера.

На перший погляд вони схожі, але мають різне призначення:

• CMD задає команду або аргументи за замовчуванням;

• ENTRYPOINT визначає основну програму контейнера;

• разом вони дають змогу створити контейнер, який запускає фіксовану програму, але приймає змінні аргументи.

Наприклад, контейнер може завжди запускати певний застосунок, а під час запуску отримувати інше ім’я файлу або режим роботи.

Інструкція CMD

CMD задає команду за замовчуванням, яку буде виконано при старті контейнера.

FROM alpine:3.20

CMD ["echo", "Привіт із контейнера"]

Якщо запустити образ без додаткових аргументів:

docker build -t greeting .
docker run --rm greeting

Результат:

Привіт із контейнера

Але команду, визначену через CMD, легко замінити під час запуску:

docker run --rm greeting echo "Інше повідомлення"

Тепер Docker виконає передану команду замість CMD.

Основні властивості CMD

CMD зручно використовувати, коли:

• контейнер має стандартну команду запуску;

• користувач повинен легко її перевизначати;

• образ може використовуватися для різних сценаріїв.

У Dockerfile може бути кілька інструкцій CMD, але працюватиме лише остання. Тому зазвичай у файлі визначають одну CMD.

Інструкція ENTRYPOINT

ENTRYPOINT задає основну виконувану програму контейнера.

FROM alpine:3.20

ENTRYPOINT ["echo"]

Запуск без аргументів:

docker run --rm greeting

Запуск із аргументом:

docker run --rm greeting "Привіт"

У другому випадку echo залишається точкою входу, а рядок "Привіт" передається їй як аргумент.

Фактично команда буде еквівалентна:

echo Привіт

На відміну від CMD, аргументи після імені образу не замінюють ENTRYPOINT, а додаються до нього.

CMD і ENTRYPOINT разом

Найпоширеніший сценарій — використовувати ENTRYPOINT для програми, а CMD — для аргументів за замовчуванням.

FROM alpine:3.20

ENTRYPOINT ["echo"]
CMD ["Стандартне повідомлення"]

Без аргументів Docker запустить:

echo Стандартне повідомлення

Команда:

docker run --rm greeting

виведе:

Стандартне повідомлення

Якщо передати власний аргумент:

docker run --rm greeting "Повідомлення користувача"

Docker запустить:

echo Повідомлення користувача

У цьому випадку:

• ENTRYPOINT — echo;

• CMD — аргумент "Стандартне повідомлення";

• аргумент із docker run замінює CMD.

Це головна відмінність від використання лише CMD: основна програма залишається незмінною.

Форми запису інструкцій

CMD та ENTRYPOINT підтримують дві форми:

1. exec form;

2. shell form.

Exec form

Exec form записується як JSON-масив:

ENTRYPOINT ["node", "server.js"]
CMD ["--port", "3000"]

Це рекомендований варіант для більшості випадків.

Переваги:

• аргументи передаються без додаткового розбору оболонкою;

• пробіли та спеціальні символи обробляються передбачувано;

• процес програми може бути головним процесом контейнера;

• сигнали, зокрема SIGTERM, коректніше передаються застосунку.

Для exec form важливо використовувати подвійні лапки, оскільки запис має бути коректним JSON:

CMD ["python", "app.py"]

Такий запис не є правильним:

CMD ['python', 'app.py']

Shell form

Shell form виглядає як звичайна команда:

CMD echo "Привіт"

Зазвичай така команда запускається через оболонку, наприклад /bin/sh -c.

Shell form може бути зручною для коротких команд або коли потрібні можливості shell:

CMD echo "$MESSAGE"

Проте вона має важливі нюанси:

• команда запускається через shell;

• змінні середовища та оператори shell можуть оброблятися оболонкою;

• застосунок може не стати процесом із PID 1;

• сигнали можуть передаватися не так, як очікується.

Для довготривалих процесів, вебсерверів і застосунків зазвичай краще використовувати exec form.

Як Docker комбінує інструкції

Розглянемо Dockerfile:

FROM alpine:3.20

ENTRYPOINT ["printf"]
CMD ["%s\n", "Стандартний текст"]

Без додаткових аргументів:

docker run --rm formatter

Виконується приблизно така команда:

printf "%s\n" "Стандартний текст"

Якщо передати аргументи:

docker run --rm formatter "%s\n" "Новий текст"

Docker замінить CMD і сформує:

printf "%s\n" "Новий текст"

Загальне правило для exec form:

ENTRYPOINT + CMD

А аргументи, передані після імені образу, замінюють CMD:

ENTRYPOINT + аргументи docker run

Як перевизначити ENTRYPOINT

Аргументи після імені образу не замінюють ENTRYPOINT. Щоб змінити його, потрібно використати параметр --entrypoint:

docker run --rm --entrypoint sh my-image

Це запустить sh замість програми, визначеної в ENTRYPOINT.

Такий підхід часто використовують для діагностики контейнера:

docker run --rm -it --entrypoint sh my-image

Після запуску можна перевірити файли, змінні середовища або доступність команд усередині образу.

Приклад для Python-застосунку

Припустімо, образ має запускати Python-застосунок. Основний файл завжди один, але порт можна змінювати:

FROM python:3.12-slim

WORKDIR /app

COPY app.py .

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8000"]

Стандартний запуск:

docker run --rm my-python-app

Еквівалентна команда:

python app.py --port 8000

Запуск на іншому порту:

docker run --rm my-python-app --port 9000

Еквівалент:

python app.py --port 9000

У цьому прикладі користувач може змінювати параметри застосунку, але не змінює саму програму запуску.

Що відбувається з CMD у shell form

Комбінація shell form може поводитися не так, як очікується.

Наприклад:

ENTRYPOINT ["echo"]
CMD hello

Тут CMD hello має shell form. Docker не обов’язково передасть hello як звичайний аргумент до exec-form ENTRYPOINT так, як це відбувається для JSON-масиву. Змішування форм ускладнює передбачення фактичної команди.

Тому для комбінації ENTRYPOINT і CMD краще використовувати exec form в обох інструкціях:

ENTRYPOINT ["my-app"]
CMD ["--config", "/app/config.yml"]

Процес PID 1 і сигнали

Перший процес у контейнері має PID 1. Саме він відповідає за обробку сигналів і завершення процесів.

Якщо застосунок запускається безпосередньо через exec form:

ENTRYPOINT ["./server"]

він зазвичай є головним процесом контейнера та може коректно обробити сигнал завершення.

Якщо ж запуск відбувається через shell:

ENTRYPOINT ./server

між Docker і застосунком може з’явитися оболонка. Вона не завжди передає сигнали дочірньому процесу так, як потрібно. Це може призвести до затримок під час зупинки контейнера або некоректного завершення застосунку.

Для production-контейнерів рекомендовано:

• використовувати exec form;

• не запускати основний процес через зайвий shell без потреби;

• переконатися, що застосунок коректно обробляє сигнали завершення.

Коли використовувати CMD

Використовуйте CMD, якщо:

• команда є лише значенням за замовчуванням;

• користувач повинен повністю замінювати команду;

• образ призначений для різних завдань;

• потрібно передати стандартні параметри програмі.

Приклад:

FROM alpine:3.20

CMD ["sh"]

Такий образ за замовчуванням запускає shell, але користувач може виконати будь-яку іншу команду:

docker run --rm alpine-image ls -la

Коли використовувати ENTRYPOINT

Використовуйте ENTRYPOINT, якщо:

• контейнер має виконувати конкретну програму;

• образ працює як виконуваний інструмент;

• основна команда не повинна випадково замінюватися;

• аргументи користувача потрібно передавати цій програмі.

Приклад:

FROM alpine:3.20

ENTRYPOINT ["grep"]

Тепер контейнер поводиться подібно до команди grep:

docker run --rm grep-image "error" /logs/app.log

Усі аргументи передаються до grep.

Типові помилки

Використання shell form без потреби

ENTRYPOINT npm start

Такий запис запускає команду через shell. Для основного процесу краще використовувати форму, яка безпосередньо запускає програму:

ENTRYPOINT ["npm", "start"]

Спроба замінити ENTRYPOINT звичайними аргументами

Команда:

docker run --rm my-image sh

не замінює ENTRYPOINT. Вона передає sh як аргумент до наявної точки входу.

Для повної заміни використовуйте:

docker run --rm --entrypoint sh my-image

Передавання всієї команди одним рядком

Не варто без потреби писати:

ENTRYPOINT ["python app.py --port 8000"]

Docker спробує знайти виконуваний файл із назвою python app.py --port 8000.

Правильний варіант:

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8000"]

Використання одинарних лапок в exec form

Exec form використовує JSON-синтаксис, тому потрібні подвійні лапки:

CMD ["node", "server.js"]

Визначення кількох CMD

У Dockerfile може бути кілька інструкцій CMD, але активною буде лише остання. Попередні значення не об’єднуються.

Погано:

CMD ["echo", "Перший запуск"]
CMD ["echo", "Другий запуск"]

У результаті спрацює лише друга інструкція.

Дублювання параметрів

Якщо параметр уже визначено в ENTRYPOINT, не варто без потреби повторювати його в CMD:

ENTRYPOINT ["my-app", "--config", "/app/config.yml"]
CMD ["--config", "/app/config.yml"]

Це може призвести до дублювання аргументів. Краще розділити постійні параметри та параметри за замовчуванням:

ENTRYPOINT ["my-app", "--config", "/app/config.yml"]
CMD ["--verbose"]

Практичне правило вибору

Можна користуватися простим правилом:

• потрібна команда за замовчуванням, яку легко замінити — використовуйте CMD;

• потрібна фіксована програма з аргументами користувача — використовуйте ENTRYPOINT;

• потрібна фіксована програма зі стандартними аргументами — використовуйте ENTRYPOINT разом із CMD;

• для production-застосунків переважно використовуйте exec form.

Типова структура:

FROM base-image

WORKDIR /app

COPY . .

ENTRYPOINT ["my-application"]
CMD ["--environment", "production"]

Така конфігурація означає:

• my-application є основною програмою;

• --environment production — параметри за замовчуванням;

• аргументи docker run можуть замінити ці параметри;

• --entrypoint може повністю замінити основну програму для діагностики.

Підсумок

CMD і ENTRYPOINT обидві впливають на запуск контейнера, але виконують різні ролі:

• CMD задає команду або аргументи за замовчуванням;

• ENTRYPOINT задає основну програму контейнера;

• аргументи після імені образу замінюють CMD;

• параметр --entrypoint замінює ENTRYPOINT;

• поєднання ENTRYPOINT і CMD підходить для фіксованої програми зі змінними параметрами;

• exec form зазвичай безпечніша та передбачуваніша для основних процесів контейнера.

У більшості прикладних образів доречно почати з такого шаблону:

ENTRYPOINT ["my-app"]
CMD ["--port", "8000"]

Він чітко розділяє основну програму та її параметри за замовчуванням.