Конфигурация своего экземпляра

Оглавление · Настройки и секреты

Перед развёртыванием проекта у себя нужно определить, какие repository, домены, образы и сервер принадлежат вашей системе. Эти знания хранятся в одном несекретном JSON. Проверка конфигурации помогает найти ошибку до обращения к инфраструктуре.

Текущий этап: реализованы чтение, validation и вычисление адресов. Действующие CI и deploy scripts пока не используют этот файл. Изменение instance.json само по себе не переносит доставку и не меняет работающий сервер. Полные практикумы создания админки и независимого развёртывания предстоит написать.

Что описывает файл

Корневой instance.json содержит публичные настройки проекта. instance.example.json содержит вымышленные значения. В своём клоне замените поля на настройки собственных ресурсов и сохраните файл в собственном repository. UUID нужно получить у своего SourceCraft repository: это отдельная identity, а не старый id репозитория на другой платформе.

Поле	Смысл и ограничения
`schema`	Целое число `1`, версия контракта конфигурации.
`instance_id`	Короткое имя экземпляра: строчные латинские буквы, цифры и дефис, начинается с буквы, до 32 символов.
`repository`	Собственные `organization/repository`: два сегмента, начинающихся с буквы или цифры; дальше допустимы буквы, цифры, `_` и `-`, до 64 символов в каждом.
`repository_id`	Канонический UUID SourceCraft с дефисами и строчными буквами.
`registry_prefix`	`cr.yandex/<20 букв или цифр>/<instance_id>`; только строчные латинские символы.
`install_root`	Ровно `/opt/<instance_id>`. Это граница ресурсов данного экземпляра.
`ssh_host`	DNS-имя SSH-сервера, без username, схемы, пути и порта.
`ssh_user`	Имя пользователя Linux: строчные буквы, цифры, `_` и `-`, начинается с буквы или `_`, до 32 символов.
`production_domain`	Основной домен production; у сайта нет дополнительного префикса `web`.
`environment_domain`	Суффикс адресов test, staging и PR. Может совпадать с production domain.
`operator_email`	Один email оператора: без пробелов и переводов строки, ASCII; локальная часть начинается с буквы/цифры, допускает `.`, `_`, `+`, `-`, до 64 символов.

Все поля обязательны; неизвестные и повторяющиеся JSON-ключи отвергаются. Размер файла ограничен 64 KiB. DNS-имена должны содержать не менее двух меток, быть записаны строчными ASCII-символами, без завершающей точки. URL, IP-адрес и server.example.org:22 не подходят. Существование DNS-записи и возможность входа по SSH проверяются отдельно.

В исходном instance.json поле ssh_host использует публичный домен проекта. Это начальная настройка, а не подтверждённый SSH endpoint: перед будущим применением оператор должен указать и проверить действительный адрес сервера.

Проверить учебную конфигурацию

Из корня repository, Python 3.10 или новее:

python3 scripts/instance/cli.py --config instance.example.json validate
python3 scripts/instance/cli.py --config instance.example.json plan --environment pr-12

Первая команда возвращает JSON с valid: true, schema: 1 и fingerprint. Вторая выводит identity, адреса, image repositories и SSH-настройки. В частности:

hosts.web = web.pr-12.lab.example.org
hosts.cms = cms.pr-12.lab.example.org
images.strapi = cr.yandex/aaaaaaaaaaaaaaaaaaaa/learning-strapi
ssh_host = server.example.org
ssh_user = deploy

Это фрагменты полей реального JSON-вывода plan, а не shell-команды. Адреса вымышленные: DNS и ресурсы для них не создаются.

Обе команды только читают выбранный JSON. Они не читают .env, не используют credentials, не обращаются к SourceCraft/registry/DNS/SSH и не запускают deployment. Успешная validation не подтверждает владение repository, выдачу прав или наличие сервера. Exit code 0 означает успешную проверку; 2 — ошибку ввода либо чтения файла.

Без --config используется корневой instance.json именно того checkout, где находится CLI. Поэтому абсолютный путь к CLI работает из другого каталога. Явный относительный --config отсчитывается от рабочего каталога терминала.

Как получаются адреса

Сервис	Production с `example.org`	PR №12 с `lab.example.org`
Сайт	`example.org`	`web.pr-12.lab.example.org`
CMS	`cms.example.org`	`cms.pr-12.lab.example.org`
Медиа	`media.example.org`	`media.pr-12.lab.example.org`
Storybook	`storybook.example.org`	`storybook.pr-12.lab.example.org`
Учебник	`docs.example.org`	`docs.pr-12.lab.example.org`

Для test и staging заменяется сегмент pr-12 на test или staging. Допустимы только production, test, staging, pr-N с положительным N без ведущих нулей. Слишком длинный вычисленный hostname также отвергается.

В production plan дополнительно появляются monitoring, analytics и errors под основным доменом. Observability для каждого PR не создаётся. images.release — repository транспорта релизов/proxy; он не является пятым application image. Админку читатель добавит отдельным этапом, расширив весь delivery contract: сейчас список application images остаётся прежним.

Identity и fingerprint

Identity состоит из instance_id, repository, repository_id, registry_prefix, install_root. Функция assert_identity сравнивает эти поля целиком с ожидаемым владельцем и отвергает пропуски, лишние поля и расхождения. Она пока не подключена к server owner markers и не меняет их.

Fingerprint — SHA-256 канонического JSON всех полей. Порядок ключей не влияет на результат; изменение домена влияет. Это способ сопоставить конфигурации, а не цифровая подпись и не доказательство права управлять сервером.

После развёртывания нельзя менять identity как способ присвоить существующий сервер: перенос владельца и данных требует отдельной процедуры. Пароли, API tokens, SSH keys и дампы хранятся отдельно по правилам настроек. Не добавляйте их как новые JSON-поля.

Упражнение и диагностика

Скопируйте вымышленный пример в .local/learning-instance.json, измените production_domain на school.example.org, выполните validate и production plan. CMS должна получить адрес cms.school.example.org.
Добавьте повторяющийся ключ или неизвестное поле. Проверка должна завершиться с кодом 2, без частичного результата и вывода содержимого файла.
Попробуйте environment pr-01: это неоднозначное имя и оно отвергается.
Верните корректные значения. Убедитесь, что изменение config не меняет сервер, DNS и существующие volumes.

При Cannot read instance configuration проверьте путь и права чтения. При Invalid instance configuration or environment проверьте JSON, обязательные поля и ограничения выше. Сообщение намеренно не печатает значения полей: ошибочно добавленный секрет не должен оказаться в общих логах.

Результат: вы можете объяснить принадлежность ресурсов и вычислить адреса своего экземпляра до развёртывания. Реальный bootstrap, CI, PR-стенды и выпуск релиза относятся к следующему этапу автоматизации.