Как передать внутрь образа переменные при сборке?

Способы передачи переменных внутрь Docker-образа при сборке

При сборке Docker-образов существует несколько методов передачи переменных внутрь образа, каждый из которых решает разные задачи и имеет свои особенности. Рассмотрим основные подходы.

. ARG и ENV инструкции в Dockerfile

Основной механизм передачи переменных при сборке — использование инструкций ARG (build-time переменные) и ENV (runtime переменные).

ARG (Arguments)

Переменные времени сборки, доступные только на этапе docker build. Не сохраняются в итоговом образе (если не копируются в ENV).

# Определение ARG с default значением
ARG NODE_VERSION=18
FROM node:${NODE_VERSION}-alpine

# ARG без значения по умолчанию
ARG BUILD_NUMBER
RUN echo "Build number: ${BUILD_NUMBER}"

# Многострочное определение
ARG APP_NAME \
    APP_VERSION=1.0.0

ENV (Environment)

Переменные окружения, которые сохраняются в образе и доступны во время выполнения контейнера.

FROM alpine:latest
ENV APP_PORT=8080 \
    NODE_ENV=production

Комбинирование ARG и ENV

Часто используется для передачи значений сборки в runtime переменные:

ARG VERSION=latest
ENV APP_VERSION=${VERSION}

2. Передача переменных при вызове docker build

Переменные ARG можно передавать во время сборки через флаг --build-arg:

# Базовый вариант
docker build --build-arg NODE_VERSION=16 -t myapp .

# Несколько переменных
docker build \
  --build-arg APP_VERSION=2.1.0 \
  --build-arg BUILD_DATE=$(date -I) \
  -t myapp:v2 .

# Использование переменных из текущего окружения
docker build --build-arg GITHUB_TOKEN=$GITHUB_TOKEN -t myapp .

3. Файлы .env и --env-file

Для управления множеством переменных удобно использовать файлы окружения:

# Файл build.env
NODE_VERSION=18
APP_NAME=myapp
BUILD_MODE=production

# Передача файла при сборке
docker build --build-arg-file build.env -t myapp .

4. Использование docker-compose build

В Docker Compose переменные можно задавать в файле docker-compose.yml:

version: '3.8'
services:
  app:
    build:
      context: .
      args:
        - NODE_VERSION=16
        - APP_ENV=${APP_ENV:-production}
    environment:
      - DB_HOST=${DB_HOST}

5. Многоступенчатые сборки (Multi-stage builds)

В сложных сценариях можно передавать переменные между стадиями сборки:

# Первая стадия - сборка
ARG NPM_TOKEN
FROM node:18 as builder
WORKDIR /app
COPY package*.json .
RUN npm ci

# Вторая стадия - финальный образ
FROM nginx:alpine
ARG APP_VERSION
ENV VERSION=${APP_VERSION}
COPY --from=builder /app/dist /usr/share/nginx/html

6. Продвинутые техники

Динамическое создание файлов конфигурации

ARG API_URL
RUN echo "API_URL=${API_URL}" > /app/.env

Условные инструкции на основе ARG

ARG TARGET_ENV=production

RUN if [ "$TARGET_ENV" = "development" ]; then \
      npm install --only=development; \
    else \
      npm ci --only=production; \
    fi

7. Best Practices и рекомендации

1. Безопасность: Никогда не передавайте секреты через ARG, используйте docker build --secret или сторонние решения (HashiCorp Vault, AWS Secrets Manager)
2. Кэширование: Изменение значений ARG инвалидирует кэш Docker
3. Совместимость: ARG должны быть объявлены до первого использования
4. Документация: Документируйте используемые переменные в комментариях к Dockerfile

# Требуемые build-args:
#   APP_VERSION - версия приложения (default: latest)
#   BUILD_MODE - режим сборки (dev/prod)
ARG APP_VERSION=latest
ARG BUILD_MODE=production

8. Пример полного workflow

# 1. Создаем файл с переменными
cat > .build-args << EOF
APP_VERSION=2.3.1
BUILD_DATE=2024-01-15
NODE_ENV=production
EOF

# 2. Собираем образ с передачей переменных
docker build \
  $(cat .build-args | xargs printf '--build-arg %s\n') \
  -t myapp:latest \
  .

# 3. Проверяем переменные в контейнере
docker run --rm myapp:latest env | grep -E "APP|BUILD|NODE"

Выбор конкретного метода зависит от требований к безопасности, сложности сборки и инфраструктуры CI/CD. Для простых случаев достаточно ARG, для сложных production-сборок рекомендуется комбинировать несколько подходов с использованием секретов и внешних систем управления конфигурацией.