basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN
    МануалHomelabСекреты

    Секреты в Docker-стеках: где хранить и как не засветить

    Секрет хранится на сервере в одном экземпляре, и читает его только root: копий в git, в командной строке и в окружении чужих контейнеров нет. Место по умолчанию — файл в /srv/secrets/<стек>/, подключённый как Docker secret; если приложение так не умеет — .env с правами 600.

    Где лежит секрет

    Место Когда Права
    файл /srv/secrets/<стек>/<имя>, в контейнере — Docker secret /run/secrets/<имя> приложение умеет читать секрет из файла каталоги root 700, файлы root 400
    /opt/<стек>/.env значение нужно самому compose (лейблы, подстановка) или приложение читает только переменные окружения root 600
    .env.example в git только имена переменных, без значений —
    compose-файл, git (даже приватный), командная строка, общий чат, /tmp никогда —

    /srv/secrets лежит вне /opt. Если /opt смонтирован в панель управления Docker (Dockhand, Portainer) или попадёт в архив конфигов, секретов там не окажется.

    Настройка

    1. Каталог для секретов

      install -d -m 700 /srv/secrets /srv/secrets/<стек>

      Каталоги — root 700, файлы в них — root 400. Docker работает от root, поэтому смонтировать файл в контейнер это не мешает.

    2. Переносим секрет в файл — мимо экрана

      Из файла:

      install -m 400 /opt/<стек>/token.txt /srv/secrets/<стек>/token
      wc -c < /srv/secrets/<стек>/token          # не 0 — и ничего на экране

      Из строки конфига — через переменную, без вывода и без перевода строки в конце:

      key=$(sed -nE 's/^[[:space:]]*apiKey:[[:space:]]*"?([^"[:space:]]+)"?.*/\1/p' config.yml)
      printf '%s' "$key" > /srv/secrets/<стек>/key; unset key
      chmod 400 /srv/secrets/<стек>/key
    3. Подключаем как Docker secret

      services:
        traefik:
          environment:
            CF_DNS_API_TOKEN_FILE: /run/secrets/cf_api_token     # приложение читает файл
          secrets:
            - cf_api_token
            - crowdsec_lapi_key
      secrets:
        cf_api_token:
          file: /srv/secrets/traefik/cf_api_token
        crowdsec_lapi_key:
          file: /srv/secrets/traefik/crowdsec_lapi_key

      Без Swarm это обычное монтирование файла в /run/secrets/<имя>. Отличие от тома в том, что по compose сразу видно: это секрет, и все секреты описаны в одном месте.

    4. Приложение читает секрет из файла

      Способ Пример
      переменная *_FILE CF_DNS_API_TOKEN_FILE, MARIADB_ROOT_PASSWORD_FILE, POSTGRES_PASSWORD_FILE — официальные образы MariaDB и Postgres это умеют; у Postgres — только для POSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB и POSTGRES_INITDB_ARGS
      параметр …File в конфиге crowdsecLapiKeyFile у плагина CrowdSec для Traefik («CrowdSec с Traefik за Cloudflare»)
      файл пользователей Basic Auth в Traefik: basicauth.usersfile=/path вместо basicauth.users=…
    5. Хэш Basic Auth — файлом пользователей

      Лейбл получает значение при запуске compose, поэтому секретом его не сделать: хэш в basicauth.users=${APP_AUTH} может прийти только из .env. Чтобы убрать его оттуда, нужен файл пользователей:

      # Traefik: каталог с файлами пользователей — одно монтирование на все сервисы
      services:
        traefik:
          volumes:
            - /srv/secrets/traefik/basicauth:/basicauth:ro
      # сервис: лейбл указывает путь внутри контейнера Traefik
      - "traefik.http.middlewares.app-auth.basicauth.usersfile=/basicauth/app"

      В файле /srv/secrets/traefik/basicauth/app — строки user:hash в формате htpasswd, $ без экранирования.

    Пароли: новый, для команды, засветившийся

    Новый пароль — сразу на место

    new=$(openssl rand -hex 20)      # на экран не выводится
    # … применяем new: в базу, в .env …
    unset new

    Пароли для людей храним в менеджере паролей (например, Vaultwarden), для сервисов — на сервере. Это два разных места, так и должно быть.

    Пароль для команды — не в командной строке

    Аргумент -p'пароль' остаётся в истории оболочки (~/.bash_history) и виден в списке процессов. Если пароль уже есть в окружении контейнера, берём его оттуда, внутри контейнера:

    docker exec db sh -c 'exec mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction app' | gzip > app.sql.gz

    Одинарные кавычки снаружи нужны, чтобы $MARIADB_ROOT_PASSWORD раскрыла оболочка внутри контейнера.

    Пароль засветился — меняем мимо экрана

    Для MariaDB:

    new=$(openssl rand -hex 20)
    docker exec -e NEW="$new" db sh -c 'mariadb -u root -p"$MARIADB_ROOT_PASSWORD" -e "ALTER USER IF EXISTS root@localhost IDENTIFIED BY \"$NEW\"; ALTER USER IF EXISTS root@\"%\" IDENTIFIED BY \"$NEW\";"' \
      && sed -i "s/^MARIADB_ROOT_PASSWORD=.*/MARIADB_ROOT_PASSWORD='$new'/" .env && echo "сменён"
    unset new; docker compose up -d     # чтобы в контейнере оказался новый пароль

    && нужен, чтобы .env поменялся, только если база приняла новый пароль. Подробно — «MariaDB в контейнере».

    Другие способы хранить секреты

    Подход Что даёт Цена
    Docker secrets из /srv/secrets секрет вне /opt, в compose виден как секрет, права 400 нужна поддержка *_FILE или чтения из файла
    .env с правами 600 работает со всем, без него не обойтись для лейблов лежит в /opt рядом с конфигами и уезжает вместе с ними в любой архив
    зашифрованные секреты в git (sops, age) секреты версионируются, сервер можно развернуть с нуля ключ расшифровки всё равно где-то хранить; ещё один инструмент в цепочке
    менеджер секретов (Vault, Infisical) ротация, аудит, доступ по ролям ещё один сервис, который надо держать живым

    Для нескольких своих серверов хватает первых двух: /srv/secrets для всего, что умеет читать файлы, .env 600 — для остального.

    Если не работает

    Секрет попал в git — даже в приватный репозиторий

    Причина
    История git хранит его навсегда. Вычистить историю можно, но это долго и не гарантирует, что нигде не осталось копии.
    Делаем
    Считаем секрет утёкшим и меняем значение.

    Пароль попал в чат, тикет или на скриншот

    Причина
    Значение видели все, у кого есть доступ к переписке.
    Делаем
    Меняем так, чтобы новый пароль не появился на экране. Команда для MariaDB — в разделе «Пароли» выше.

    .env с правами 644

    Причина
    Его читает любой пользователь сервера.
    Делаем
    chmod 600 /opt/*/.env.

    Одна и та же переменная-секрет в .env нескольких стеков, а читает её один

    Причина
    Ключ скопировали «на всякий случай» — например, ключ bouncer'а в .env CrowdSec. При смене ключа про копии забудут.
    Делаем
    Удаляем лишние копии.

    Скрипт сделал резервные копии .env в /tmp

    Причина
    /tmp читают все пользователи сервера.
    Делаем
    Копии делаем в /root и удаляем сразу после.

    Ключ из файла не принимается, хотя он правильный

    Причина
    В конце файла перевод строки: часть программ читает ключ вместе с \n.
    Делаем
    Пишем файл через printf '%s', а не echo.

    Поменяли путь секрета в compose — контейнер не создаётся

    Причина
    Файла по новому пути ещё нет, а без него compose контейнер не создаёт.
    Делаем
    Сначала кладём файл, потом git pull и up -d одной командой («Файл секрета — до up -d»).

    Как проверить

    find /srv/secrets -exec stat -c '%a %U %s %n' {} \;      # права, владелец, размер — без содержимого
    stat -c '%a %n' /opt/*/.env                              # 600
    docker exec traefik sh -c 'test -s /run/secrets/cf_api_token && echo "токен на месте"'

    Плюс поиск секретов в том, что идёт в git, — с маскировкой значений («Конфиги серверов в git», шаг 5).