re:re:actable
Урок 033 минуты чтения

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

На этой странице
Кратко

Секрет нельзя «запекать» в образ: всё, что попало в слой, ENV или историю сборки, увидит любой, кто сможет скачать образ, а отозвать его оттуда невозможно. Секреты сборки (токен приватного npm-registry) передают через BuildKit: RUN --mount=type=secret монтирует файл только на время инструкции. Секреты запуска (пароль БД, ключи API) передают в рантайме: secret manager платформы, Kubernetes Secrets, Compose secrets (файл в /run/secrets/...) или переменные окружения из защищённого хранилища CI.

Вопрос

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

Что делать нельзя

ENV DATABASE_PASSWORD=super-secret            # виден в docker inspect
ARG NPM_TOKEN                                 # может остаться в истории сборки
RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc && npm ci
COPY .env .                                   # файл в слое образа

Даже если удалить .npmrc следующей инструкцией, файл останется в нижнем слое и извлекается через docker save.

Секреты сборки: BuildKit secret mount

# syntax=docker/dockerfile:1
FROM node:24-alpine
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN \
    npm ci
# .npmrc в репозитории — без самого токена
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
docker build --secret id=npm_token,env=NPM_TOKEN -t app .
# или из файла: --secret id=npm_token,src=./npm_token.txt

Секрет доступен только во время этой RUN и не попадает ни в слой, ни в кэш. Без env= он монтируется файлом /run/secrets/npm_token.

Для приватных git-зависимостей есть аналог — RUN --mount=type=ssh с docker build --ssh default.

Секреты запуска

Compose secrets — секрет монтируется файлом:

services:
  api:
    image: ghcr.io/team/api:1.4.0
    secrets:
      - db_password
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
 
secrets:
  db_password:
    file: ./secrets/db_password.txt   # файл не в git
import { readFileSync } from "node:fs";
 
const password = process.env.DB_PASSWORD_FILE
  ? readFileSync(process.env.DB_PASSWORD_FILE, "utf8").trim()
  : process.env.DB_PASSWORD;

Соглашение *_FILE поддерживают официальные образы (POSTGRES_PASSWORD_FILE).

Переменные окружения — самый распространённый способ, но значения видны через docker inspect и в /proc процесса, наследуются дочерними процессами и легко попадают в логи ошибок. Файл чуть безопаснее.

Внешние хранилища — AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler. Платформа подставляет секрет при запуске, ротация не требует пересборки.

Frontend: секретов нет

VITE_* и runtimeConfig.public / NUXT_PUBLIC_* попадают в браузер и видны всем. Токены сторонних API используют только на сервере (серверный маршрут Nuxt в server/api, backend), а браузер обращается к своему серверу.

Если секрет утёк

  1. Отозвать и перевыпустить секрет — удаление образа из registry недостаточно, копии могли скачать.
  2. Пересобрать образ без секрета.
  3. Добавить сканер секретов в CI (gitleaks, trufflehog) и проверку образов.

Частые ошибки

  • ARG или ENV для токенов и паролей.
  • COPY .env в образ.
  • Логирование process.env при старте.
  • Секреты в VITE_* или NUXT_PUBLIC_*.
  • Production .env в git.

Что важно помнить

  • Слой образа нельзя «почистить» — только пересобрать и отозвать секрет.
  • Build-секреты — --mount=type=secret, runtime-секреты — платформа или файлы /run/secrets.
  • Переменная окружения — допустимый, но не самый безопасный транспорт.

Мини-шпаргалка

  • Сборка: RUN --mount=type=secret,id=x + docker build --secret id=x,....
  • Git: --mount=type=ssh.
  • Запуск: Compose secrets, *_FILE, secret manager.
  • Утечка: отозвать → пересобрать → сканировать.

Документация

Docker: Build secrets, Docker Compose: Secrets.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам