core.repo

soul-sidesoulstack.systemsystem

Объявление пакетного репозитория OS (apt / dnf / yum / apk).

core.repo объявляет пакетный репозиторий OS: пишет файл-описание в системный каталог менеджера, а для apt — ещё и GPG-ключ, на который .list ссылается через signed-by=. Backend (apt/dnf/yum/apk), формат и путь файла выбираются автоматически по пакетному менеджеру хоста. Модуль только объявляет репозиторий и не обновляет индекс (apt-get update / dnf makecache) — это делает core.pkg при установке. Состояния идемпотентны: если файл-описание уже совпадает побайтово (и для apt — ключ) — changed=false.

Требования

Rootне требуется
Сторонаsoul-side
Коллекцияsoulstack.system
Категорияsystem

Capabilitiesfs_write_root

Детект backend

Авто по пакетному менеджеру хоста (util.DetectPkgMgr): apt → /etc/apt/sources.list.d/<name>.list + keyring, dnf/yum → /etc/yum.repos.d/<name>.repo (ini), apk → строка в /etc/apk/repositories. Ни один менеджер не найден — шаг падает.

core.repo.present — Репозиторий объявлен: файл-описание (и для apt — GPG-ключ) на месте с нужным содержимым.

Меняется, когда

Целевой файл отсутствовал или отличается побайтово, либо (apt с gpg_key) ключ отсутствовал или отличается.

Не меняется, когда

Файл и ключ уже совпадают побайтово.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`name`	`string`	required	Имя репозитория (= имя файла-описания, [A-Za-z0-9._-]).
`uri`	`string`	required	URL репозитория (http/https; http даёт обязательный warning).
`gpg_key`	`string`	optional	URL или armored GPG-ключ для supply-chain-проверки.
`gpg_check`	`bool`	optional	Проверять подпись пакетов (default true; opt-out даёт warning).
`suite`	`string`	optional	apt suite/дистрибутив (напр. stable).
`components`	`list<string>`	optional	apt components (напр. [main, contrib]).
`enabled`	`bool`	optional	Репозиторий включён (default true).

Пример — apt-репозиторий с inline GPG-ключом

- name: Declare internal apt repo
  module: core.repo.present
  params:
    name: example-internal
    uri: https://apt.example.com/debian
    suite: bookworm
    components: [main]
    gpg_key: "${ file('files/example.gpg.asc') }"

Output

Поле	Тип	Описание
`name`	`string`
`backend`	`apt / yum / apk`
`path`	`string`	затронутый файл-описание
`warnings`	`[string]`	при opt-out gpg_check / http-uri / отсутствии ключа

core.repo.absent — Описание репозитория удалено (GPG-ключ не трогается).

Меняется, когда

Файл или строка были и удалены.

Не меняется, когда

Ни файла, ни строки не было.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`name`	`string`	required	Имя репозитория (= имя файла-описания).

Пример — Удаление apk-зеркала (матч по uri)

- name: Drop old apk mirror
  module: core.repo.absent
  params:
    name: old-mirror
    uri: https://dl-cdn.alpinelinux.org/alpine/edge/testing

Output

Поле	Тип	Описание
`name`	`string`
`backend`	`apt / yum / apk`
`path`	`string`

Справочник

Backend'ы и целевые артефакты

Backend выбирается автоматически по пакетному менеджеру хоста; от него зависят формат и путь файла-описания.

Backend	Дистрибутивы	Артефакт
apt	Debian, Ubuntu	/etc/apt/sources.list.d/<name>.list (one-line) + ключ /etc/apt/keyrings/<name>.gpg через signed-by=
dnf / yum	RHEL, Fedora	/etc/yum.repos.d/<name>.repo (ini-формат)
apk	Alpine	строка в /etc/apk/repositories

Заметки

Модуль только объявляет репозиторий — apt-get update / dnf makecache не делает; refresh индекса выполняет core.pkg при установке.
apt использует современный signed-by=-keyring: доверие привязано к конкретному репозиторию, а не к глобальному trust store (в отличие от deprecated apt-key).
gpg_key задаётся только inline; скачивание ключа по URL в MVP не реализовано — содержимое можно подставить через CEL (${ file(...) } / vault).
Запись preserve-by-default (AtomicWritePreserving): права и владелец существующего файла сохраняются.
Для системных путей (/etc/apt, /etc/yum.repos.d, /etc/apk) нужны права на запись в каталог (обычно root); отдельного run_as_root модуль не объявляет.
absent удаляет только описание репозитория — GPG-ключ не трогается (может использоваться другими репозиториями; чистка ключа — отдельный явный шаг).

Безопасность и умолчания

gpg_key критичен для supply-chain: если задан — ключ реально материализуется (apt: keyring + signed-by=) / прописывается в gpgkey= (dnf/yum) и участвует в idempotency-сравнении.
gpg_check=false разрешён (opt-out), но Apply возвращает обязательный warning «packages will NOT be cryptographically verified».
gpg_check=true без gpg_key для dnf/yum сломает установку пакетов (gpgcheck=1 без gpgkey=) — тоже warning; apt/apk опираются на свои хранилища доверия.
http:// в uri допустим (внутреннее зеркало), но с обязательным warning «traffic is unencrypted».
name санитизируется против path-traversal (только [A-Za-z0-9._-], без / \ ..) — имя становится именем файла.