basforge

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

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

    Секреты сервера в git: sops и age

    Секреты лежат в git рядом с конфигами, зашифрованные sops: правим их на компьютере, на сервер они подтягиваются через git, у каждой правки есть история. Расшифровать файлы могут два ключа age — компьютера и сервера; остальным, у кого есть репозиторий, видны имена переменных, но не значения. Новый сервер получает секреты, когда его открытый ключ добавлен в .sops.yaml.

    Почему секрета нет в git

    На пути «Свой сервер» /opt — git-репозиторий, но секретов в нём нет: их не пускает белый список .gitignore («Конфиги серверов в git»). Секреты лежат только на сервере — в /srv/secrets/<каталог>/ и в .env стеков («Секреты в Docker-стеках»). Отсюда три неудобства:

    • поменять секрет можно только на сервере, по SSH. С «Деплой без SSH» всё остальное подтягивается через git, а секрет — нет;
    • истории нет: через месяц не узнать, какой адрес пинга стоял до правки;
    • на второй сервер секреты переносим руками, на новый — из бэкапа («Переезд на новый сервер»).

    Открытым секрет в git не кладём даже в приватный репозиторий: история хранит значение навсегда, а копия есть у GitHub и в каждом клоне («Секрет в коммите»). Зашифрованный — кладём. sops шифрует значения внутри файла и оставляет открытыми имена, а расшифровывает их ключ age. Ключей два: один на компьютере, другой у сервера, и каждый открывает все файлы в secrets/.

    компьютер                       git (GitHub, infra-web1)               web1
      ключ age владельца              /opt/secrets/  — зашифровано          ключ age сервера
      sops edit ─── git push ───▶     .sops.yaml     — открытые ключи  ───▶ git pull, secrets.sh
                                                                            /srv/secrets/<каталог>/   400
                                                                            /opt/<стек>/.env          600

    /opt/secrets/ повторяет /srv/secrets/ один в один: secrets/deploy/hc-url сервер выкладывает в /srv/secrets/deploy/hc-url. .env стека лежит в secrets/<стек>/.env и выкладывается в /opt/<стек>/.env.

    Что видно в зашифрованном файле

    secrets/gatus/.env до шифрования — одна строка NTFY_TOPIC=lab-only-topic-1. После sops encrypt -i:

    NTFY_TOPIC=ENC[AES256_GCM,data:Ry7UoYwtqg0uGhMbo2WeTQ==,iv:tTBrTjytrlN6ArREFnUiUNZXZ2EuA4dmg/qiFrLVUjA=,tag:…,type:str]
    sops_age__list_0__map_enc=-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA0MEs5…
    sops_age__list_0__map_recipient=age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4
    sops_age__list_1__map_enc=-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB4Zk8y…
    sops_age__list_1__map_recipient=age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg
    sops_lastmodified=2026-11-12T15:05:08Z
    sops_mac=ENC[AES256_GCM,data:l/lUE+MvplSzPjwFIprKgH7mOvf3zWzUxo/yedzrR0nyTc0l6P24xDCzfObUlBmv3aNGXsuy/PkfjeAJD…,type:str]
    sops_unencrypted_suffix=_unencrypted
    sops_version=3.13.3

    Значения зашифрованы одним ключом данных, а сам он лежит в файле несколько раз — по копии для каждого получателя. Пара list_N — это открытый ключ age (recipient) и ключ данных, зашифрованный для него (enc).

    Всем, у кого есть репозиторий, видно:

    • имена переменных и их число — поэтому в имя секрет не кладём;
    • длину значения: у 16 символов lab-only-topic-1 в data: 16 байт, 24 знака base64;
    • для кого зашифрован файл (recipient) и когда его правили (lastmodified).

    Зашифрованы значения и комментарии. Файл без расширения — token, hc-url — sops хранит как JSON с одним значением data, и зашифровано всё содержимое.

    Правка одного значения меняет в diff три строки: само значение, sops_lastmodified и sops_mac. По git log -p видно, какая переменная менялась и когда, но не видно, на что.

    Настройка

    Почти всё делаем на сервере. Открытые значения уже лежат там — там их и шифруем, и на компьютер они не попадают. Хук и secrets.sh тоже создаём на сервере и коммитим оттуда, как deploy.sh в «Деплой без SSH»: так git запомнит, что файлы исполняемые. Файл, добавленный в git на Windows, получает режим 100644. На сервере secrets.sh с таким режимом не запустится, а хук git пропустит — hint: The '.githooks/pre-commit' hook was ignored because it's not set as executable — и закоммитит без проверки.

    1. sops и age на сервере

      В apt Ubuntu 24.04 пакета sops нет — берём бинарник с GitHub со сверкой суммы. age из apt нужен только ради age-keygen: сам sops его не вызывает.

      v=3.13.3
      curl -fLO https://github.com/getsops/sops/releases/download/v$v/sops-v$v.linux.amd64
      curl -fLO https://github.com/getsops/sops/releases/download/v$v/sops-v$v.checksums.txt
      sha256sum -c --ignore-missing sops-v$v.checksums.txt     # sops-v3.13.3.linux.amd64: OK
      sudo install -m 755 sops-v$v.linux.amd64 /usr/local/bin/sops
      sudo apt install age
      sops --version --disable-version-check                  # sops 3.13.3
    2. Ключ сервера

      Ключ кладём туда, где sops ищет его сам:

      sudo install -d -m 700 /root/.config/sops/age
      sudo age-keygen -o /root/.config/sops/age/keys.txt
      # Public key: age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg

      age-keygen ставит файлу права 600 и существующий ключ не перезаписывает. sudo задаёт HOME=/root, поэтому sudo sops находит ключ без переменных. Открытый ключ — строка Public key: — понадобится в .sops.yaml.

    3. sops, age и свой ключ на компьютере

      sops и age-keygen берём со страниц релизов на GitHub, на Windows — sops-v3.13.3.amd64.exe и архив age-v1.3.2-windows-amd64.zip. Ключ кладём туда, где sops найдёт его без переменных:

      mkdir -p ~/.config/sops/age && age-keygen -o ~/.config/sops/age/keys.txt          # Linux
      mkdir -p "$APPDATA/sops/age" && age-keygen -o "$APPDATA/sops/age/keys.txt"        # Windows, Git Bash

      На Windows ключ держим в профиле, а не на втором диске: файл получает права каталога, а у второго диска они по умолчанию дают читать его любой учётной записи компьютера. Предупреждение age-keygen — writing secret key to a world-readable file — на Windows печатается всегда и о правах ничего не говорит. Копия закрытого ключа — в менеджере паролей.

    4. .sops.yaml — для кого шифровать

      На сервере, sudo nano /opt/.sops.yaml. В файле только открытые ключи, он лежит в git:

      keys:
        - &owner age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4   # компьютер
        - &web1 age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg    # сервер
      creation_rules:
        - path_regex: '^secrets[/\\]'
          age: [*owner, *web1]

      Правило говорит: файл из secrets/ шифруем для обоих ключей. Путь sops сверяет от каталога .sops.yaml, на Windows — через \, поэтому разделитель — [/\\], в одинарных кавычках. Сам .sops.yaml sops ищет вверх от текущего каталога: команды работают из любого места клона, а вне клона — нет.

    5. Хук: открытый файл в secrets/ не пройдёт

      sudo install -d /opt/.githooks, затем sudo nano /opt/.githooks/pre-commit:

      #!/bin/sh
      # Файл из secrets/ коммитим, только если он расшифровывается: открытый или испорченный не пройдёт.
      # Ошибку sops не выводим: в ней бывает открытое значение
      git -c core.quotePath=false diff --cached --name-only --diff-filter=ACMR -- secrets/ | {
        fail=0
        while IFS= read -r f; do
          git show ":$f" | sops decrypt --filename-override "$f" >/dev/null 2>&1 && continue
          echo "pre-commit: $f не расшифровывается, причина — sops decrypt $f >/dev/null" >&2
          fail=1
        done
        [ $fail = 0 ] || echo "pre-commit: новый файл шифруем — sops encrypt -i <файл>, правим — sops edit <файл>" >&2
        exit $fail
      }
      sudo chmod 755 /opt/.githooks/pre-commit
      sudo git -C /opt config core.hooksPath .githooks

      Хук берёт файл из индекса — то, что уйдёт в коммит, — и пробует расшифровать. sops filestatus для этого не годится: файл, в который дописали открытую строку, он называет зашифрованным. А ошибку sops хук прячет, потому что на такой строке sops печатает в ошибке само значение: Input string lab-only-smtp does not match sops' data format.

      Расшифровывает хук ключом того, кто коммитит: на компьютере — ключом владельца, на сервере — ключом сервера. core.hooksPath — настройка клона, в git она не попадает: на компьютере её включаем отдельно. git commit --no-verify хук обходит: он страхует от ошибки, от намеренного коммита открытого файла он не защитит.

    6. Скрипт деплоя secrets.sh

      sudo nano /opt/scripts/secrets.sh:

      #!/bin/bash
      # Расшифровывает /opt/secrets: <каталог>/.env — в /opt/<каталог>/.env (600), остальное — в /srv/secrets/<каталог>/ (400)
      set -u
      cd /opt/secrets
      umask 077
      shopt -s dotglob nullglob
      for f in */*; do
        d=${f%%/*}
        if [ "${f#*/}" = .env ]; then
          out=/opt/$d/.env mode=600
        else
          out=/srv/secrets/$f mode=400
          install -d -m 700 "/srv/secrets/$d"
        fi
        # --output при сбое прежний файл не трогает, а «> файл» обнулил бы его.
        # Ошибку sops не выводим: в ней бывает открытое значение, а вывод deploy.sh уходит в Healthchecks.io
        if ! sops decrypt --output "$out" "$f" 2>/dev/null; then
          echo "secrets.sh: $f не расшифрован, подробно — sudo sops decrypt /opt/secrets/$f >/dev/null" >&2
          exit 1
        fi
        chmod "$mode" "$out"
      done
      sudo chmod 700 /opt/scripts/secrets.sh
      • Права — как в «Секреты в Docker-стеках»: каталоги 700, файлы 400, .env 600. Новый файл --output создаёт с правами 644, отсюда umask 077 и chmod.
      • Файлы, которых нет в git, скрипт не трогает: ключ SSH для Kopia в /srv/secrets/kopia/ остаётся на месте.
      • Подкаталоги в secrets/<каталог>/ скрипт не разбирает: файлы лежат на одном уровне, как в /srv/secrets/.
    7. .gitignore пропускает secrets/

      В белом списке /opt/.gitignore рядом с !/scripts/:

      !/.sops.yaml
      !/.githooks/

      И в конец файла:

      # Зашифрованные sops — всё из secrets/; открытый файл туда не пустит хук
      !/secrets/
      !/secrets/**

      .env и *.key белый список запрещает на любой глубине. Строки в конце разрешают в secrets/ всё: побеждает последнее подходящее правило. Файлы внутри secrets/ проверяет хук.

    8. Шифруем и коммитим на сервере

      cd /opt
      sudo install -d secrets/deploy secrets/gatus
      sudo cp /srv/secrets/deploy/hc-url secrets/deploy/
      sudo cp gatus/.env secrets/gatus/
      sudo sops encrypt -i secrets/deploy/hc-url
      sudo sops encrypt -i secrets/gatus/.env
      sudo git add .gitignore .sops.yaml .githooks scripts/secrets.sh secrets
      sudo git commit -m "secrets: sops, deploy и gatus"
      sudo git push

      Каталог из /srv/secrets/ копируем в secrets/ под тем же именем, .env стека — в secrets/<стек>/.env. Ключ SSH для Kopia в git не кладём: у каждого сервера он свой, на новом его создаёт «Переезд на новый сервер». Коммит проходит через хук — его проверил ключ сервера. В git теперь шифротекст:

      sudo git -C /opt show HEAD:secrets/gatus/.env | head -1
      # NTFY_TOPIC=ENC[AES256_GCM,data:Ry7UoYwtqg0uGhMbo2WeTQ==,iv:…
    9. Правим на компьютере

      git pull
      git config core.hooksPath .githooks
      sops edit secrets/gatus/.env
      git commit -am "gatus: новый топик ntfy"
      git push

      sops edit расшифровывает файл во временный, открывает редактор — SOPS_EDITOR, EDITOR, без них vim, nano или vi — и после закрытия шифрует обратно, а временный файл удаляет. У файла без расширения в редакторе — само значение. Новый .env — тоже через sops edit: файла нет, и sops создаёт его сразу зашифрованным, с примером внутри. Новый файл без расширения пишем открытым и шифруем sops encrypt -i: пока он открытый, хук не пустит его в коммит.

    10. Выкладываем на сервере

      sudo git -C /opt pull && sudo /opt/scripts/secrets.sh
      cd /opt/gatus && sudo docker compose up -d --force-recreate

      Стек пересоздаём: .env compose читает, когда создаёт контейнер. Файл Docker secret --output переписывает на месте, и в контейнере он новый сразу, но приложение могло прочитать его только при старте. С автоматическим деплоем этот шаг делает deploy.sh — следующий раздел.

    Если сервер забирает git сам

    С «Деплой без SSH» секрет подтягивается через git вместе с остальным, если deploy.sh умеет его расшифровывать. Четыре правки:

       # Отдельный файл после git контейнер не видит: изменилось не только compose — пересоздаём
    -  elif git diff --name-only "$old" "$new" -- "$s" | grep -qvx "$s/docker-compose.yaml"; then
    +  elif git diff --name-only "$old" "$new" -- "$s" "secrets/$s" | grep -qvx "$s/docker-compose.yaml"; then
    …
       git merge -q --ff-only "$new" || fail "git merge не прошёл"
    +  # Секреты — до стеков. Не расшифровались — откат, как у стека
    +  if ! git diff --quiet "$old" "$new" -- secrets && ! out=$(/opt/scripts/secrets.sh 2>&1); then
    +    git reset -q --hard "$old"
    +    /opt/scripts/secrets.sh >/dev/null 2>&1
    +    echo "$new" > "$failed"
    +    fail "Секреты ${new:0:7} не расшифровались, вернули ${old:0:7}:
    +$out"
    +  fi
    …
    -  for s in $(git diff --name-only "$old" "$new" | cut -d/ -f1 | sort -u); do
    +  for s in $(git diff --name-only "$old" "$new" | sed 's|^secrets/||' | cut -d/ -f1 | sort -u); do
    …
           git reset -q --hard "$old"
    +      /opt/scripts/secrets.sh >/dev/null 2>&1
           for d in $touched; do up "$d" >/dev/null 2>&1; done
    • Изменились файлы в secrets/ — secrets.sh расшифровывает их до перезапуска стеков.
    • secrets/gatus/.env относится к стеку gatus: он попадает в список изменённых и пересоздаётся с --force-recreate.
    • Секрет не расшифровался — откат, как у стека, который не поднялся: коммит назад, прежние секреты обратно. В Healthchecks.io — Секреты f72479b не расшифровались, вернули cd3048c и строка secrets.sh с именем файла, дальше каждый запуск — f72479b не поднялся, ждём следующего коммита, пока на GitHub не придёт исправление.
    • Стек не поднялся — при откате возвращаются и прежние секреты.

    deploy.service уже задаёт Environment=HOME=/root: без него sops из службы ключа не найдёт. После updatekeys меняются все файлы в secrets/, и deploy.sh пересоздаёт все стеки с секретами.

    Новый сервер

    При переезде и для второго сервера секреты подтягиваются через git, когда у нового сервера появился свой ключ.

    1. На новом сервере — шаги «sops и age на сервере» и «Ключ сервера». age-keygen печатает открытый ключ.

    2. На компьютере дописываем его в .sops.yaml и перешифровываем все файлы для нового списка получателей:

      # в .sops.yaml: - &new age1jt0hu4qn6lcdsxx6rn0q2qnphnqyllj9u5rx2pn9cd607vf52q6qxx4elx
      #               age: [*owner, *web1, *new]
      sops updatekeys -y $(git ls-files secrets)
      git commit -am "secrets: ключ нового сервера" && git push
      The following changes will be made to the file's groups:
      Group 1
          age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4
          age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg
      +++ age1jt0hu4qn6lcdsxx6rn0q2qnphnqyllj9u5rx2pn9cd607vf52q6qxx4elx

      updatekeys шифрует ключ данных для нового списка, значения в файлах остаются прежними. git ls-files берёт и .env, который шаблон secrets/*/* в bash пропускает.

    3. На новом сервере — git clone из «Переезд на новый сервер» и sudo /opt/scripts/secrets.sh. Порядок с restore.sh любой: файлы из git secrets.sh всё равно запишет поверх, а restore.sh с --skip-existing уже выложенные не трогает.

    Ключ сервера в бэкап не нужен: новый сервер получает свой. Старый сервер удалили — убираем его ключ из .sops.yaml и снова запускаем updatekeys. Если ключ мог утечь, этого мало: updatekeys не меняет ключ данных, и утёкший ключ вместе с блоком получателя из старой версии файла откроет значения, добавленные позже. Тогда нужны sops rotate -i для каждого файла и смена самих секретов у сервисов: старые версии из истории git утёкший ключ читает всегда.

    Варианты

    Что Как Что учесть
    ключ хоста SSH вместо ключа age у сервера получатель в .sops.yaml — строка из /etc/ssh/ssh_host_ed25519_key.pub без комментария; расшифровка — с SOPS_AGE_SSH_PRIVATE_KEY_FILE=/etc/ssh/ssh_host_ed25519_key сам sops из ключей SSH смотрит только ~/.ssh/id_ed25519 и ~/.ssh/id_rsa: без переменной ключа хоста он не найдёт, и её нужно задать и в терминале, и в службе
    несекретное оставить открытым суффикс _unencrypted у имени (port_unencrypted: 8080) или encrypted_regex в правиле .sops.yaml открытые значения тоже охраняет sops_mac: правка руками — MAC mismatch, правим через sops edit
    один репозиторий на несколько серверов правило на каждый каталог: path_regex: '^web1[/\\]secrets[/\\]' с age: [*owner, *web1], так же для web2 сервер расшифровывает только свои файлы, на чужой — Failed to get the data key. На пути у каждого сервера свой репозиторий («Переезд на новый сервер»), правило одно

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

    sops encrypt -i пишет error loading config: no matching creation rules found

    Причина
    Путь файла не подходит под path_regex в .sops.yaml: файл лежит не в secrets/, или на Windows в выражении разделитель /, а sops сверяет путь через \.
    Делаем
    Файл кладём в secrets/<каталог>/, разделитель в выражении — [/\\], в одинарных кавычках: '^secrets[/\\]'.

    sops encrypt пишет config file not found, or has no creation rules, and no keys provided through command line options

    Причина
    Команду запустили вне клона: .sops.yaml sops ищет вверх от текущего каталога, а не от каталога файла.
    Делаем
    Переходим в клон — на сервере cd /opt — и повторяем. Из подкаталога клона тоже работает.

    В Healthchecks.io — Секреты f72479b не расшифровались, вернули cd3048c, а sudo sops decrypt этого файла пишет Failed to get the data key required to decrypt the SOPS file и identity did not match any of the recipients

    Причина
    Ключа сервера нет среди получателей файла: его добавили в .sops.yaml, а updatekeys не запустили, или файл зашифровали с --age в обход правил. Хук на компьютере такой файл пропускает: ключ владельца среди получателей есть. Получатели файла перечислены в той же ошибке.
    Делаем
    На компьютере sops updatekeys -y secrets/gatus/extra — получатели станут как в .sops.yaml, — коммит и push. Следующий запуск deploy.sh выложит секреты.

    secrets.sh из службы systemd пишет, что файл не расшифрован, а с sudo в терминале всё работает

    Причина
    Служба без User= запускается без HOME, и sops не находит /root/.config/sops/age/keys.txt: sops decrypt в такой службе пишет $HOME is not defined; user config directory could not be determined.
    Делаем
    Environment=HOME=/root в разделе [Service]. В deploy.service из «Деплой без SSH» он уже есть.

    sops decrypt для .env пишет parsing time "2026-11-12T13:31:42Z\x0d": extra text: "\x0d"

    Причина
    В клоне .env с переводами строк CRLF: git на Windows с core.autocrlf=true так записывает файлы в рабочий каталог. YAML и файлы без расширения с CRLF расшифровываются, .env — нет.
    Делаем
    В .gitattributes — * text=auto eol=lf, на пути он есть с первого коммита. Если строку добавили позже, файлы, которые уже лежат в клоне, git pull не переписывает: rm secrets/gatus/.env && git checkout -- secrets/gatus/.env.

    Пароль из .env не подходит, хотя в sops edit он верный

    Причина
    Редактор на Windows сохранил текст с CRLF, и sops оставил \r в конце каждого значения. Зашифрованный файл при этом цел, и хук его пропускает.
    Делаем
    В редакторе — переводы строк LF, правим заново. Проверка: sops decrypt secrets/gatus/.env | tr -cd '\r' | wc -c — 0.

    Новое значение уже в /opt/gatus/.env или /srv/secrets/, а сервис работает со старым

    Причина
    .env compose читает, когда создаёт контейнер. Файл Docker secret secrets.sh переписывает на месте, в контейнере он новый сразу, но приложение могло прочитать его только при старте.
    Делаем
    cd /opt/gatus && sudo docker compose up -d --force-recreate. У Docker secret описание сервиса не меняется, и без --force-recreate контейнер не пересоздаётся.

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

    На компьютере хук не пускает открытый файл:

    printf 'A=1\n' > secrets/gatus/test.env
    git add secrets/gatus/test.env && git commit -m test
    # pre-commit: secrets/gatus/test.env не расшифровывается, причина — sops decrypt secrets/gatus/test.env >/dev/null
    # pre-commit: новый файл шифруем — sops encrypt -i <файл>, правим — sops edit <файл>
    git rm -q --cached secrets/gatus/test.env && rm secrets/gatus/test.env

    На сервере выложено то же, что в git. Сравниваем, не выводя значений на экран:

    sudo sops decrypt /opt/secrets/gatus/.env | sudo cmp - /opt/gatus/.env && echo совпадает
    sudo sops decrypt /opt/secrets/deploy/hc-url | sudo cmp - /srv/secrets/deploy/hc-url && echo совпадает
    sudo stat -c '%a %n' /srv/secrets/deploy/hc-url /opt/gatus/.env
    # 400 /srv/secrets/deploy/hc-url
    # 600 /opt/gatus/.env