Конфигурирование образа

Конфигурирование образа происходит с помощью YAML-файла конфигурации и команды apm system image build.

Базовый конфиг

Первоначальный файл с которого начинается конфигурация — /etc/apm/image.yml

apm system image build применяет изменения к текущему контейнеру исходя из настроек в image.yml.

Уточнение

При создании образа в CI/CD, файл с конфигурацией копируется с помощью Containerfile из репозиторий в контейнер по вышеуказанному пути

Переменные среды и поля конфигурационного файла используется в приоритете над конфигом и нужны для конфигурирования сборки в CI/CD. Подробнее в разделе «Переменные среды и поля конфигурационного файла»

Пример конфига ALT Atomic Core

name: core
hostname: alt-atomic-core

branding:
  name: alt-atomic-core

kernel:
  flavour: 6.12
  modules:
    - drm

repos:
  clean: true
  branch: sisyphus
  tasks: []

modules:
  - name: Move root
    type: move
    body:
      target: root
      destination: /
      replace: true

  - type: include
    body:
      targets:
        - packages.yml
        - apt-rpm.yml
        - filesystem.yml
        - systemd.yml
        - settings.yml
        - passwd.yml
        - disable-bins.yml

  - name: Configurate grub
    type: shell
    body:
      command: scripts/grub.s

Поля конфигурационного файла

Легенда

! — обязательное поле

Поле	Описание	Имя переменной среды
name!	Имя сборки. Влияет на имя некоторых специфичных для образа файла, которые генерируются во время работы. Например, sources.list.d/<name>.list от repos.	APM_BUILD_NAME
image!	OCI-образ, на базе которого будет собран образ.	APM_BUILD_IMAGE
build-type	Тип сборки. Доступны stable, nightly. Может определять некоторую логику и влияет на os-release.	APM_BUILD_BUILD_TYPE
hostname	Назначение имени хоста в образе (имеются проблемы, в будущем лучше использовать ReadySet)
branding	Информация о брендинге образа. Подробнее в разделе «Брендинг».
kernel	Блок для работы с ядром. Подробнее в разделе «Ядро».
repos	Блок настроек репозиториев. Подробнее в разделе «Репозитории».
modules	Массив модулей. Подробнее в разделе «Модули»

Брендинг (branding)

Набор полей branding, которые содержат информацию о брендинге образа.

Поле	Описание	Имя переменной среды
name	Установит пакеты брендинга. Всё из branding-<name>-*.
plymouth-theme	Если не указан, установит пакет темы по паттерну plymouth-theme-<name> и назначит её через конфигурационный файл в /etc.

Примеры branding

ALT Atomic Core:

branding:
  name: alt-atomic-core

Брендинг с пользовательской темой Plymouth:

branding:
  name: my-cool-alt
  plymouth-theme: cat

Репозитории (repos)

Управление системными репозиториями

Поле	Описание	Имя переменной среды
clean	Очистить или нет существующие репозитории. Полезно при создании базового образа.
custom	Массив из ссылок APT-репозиториев в формате rpm http://ftp.altlinux.org/... classic
branch	Ветка для автоматического добавления заготовленных репозиториев. Доступен только sisyphus. Обязательное поле при указании поля date.	APM_BUILD_REPO_BRANCH
date	Дата репозитория, если нужен конкретный срез в формате YYYY.MM.DD. При отсутствии берётся не срез, а просто репозиторий.	APM_BUILD_REPO_DATE
tasks	Номера тасков, которые будут добавлены как репозитории. Допустимы только таски EPERM или TESTED. DONE пока не поддерживаются

Примеры repos

ALT Atomic Core:

repos:
  clean: true
  branch: sisyphus
  tasks: []

Подключение ветки ветки p11 и дополнительных тасков:

repos:
  clean: true
  custom:
    - rpm [p11] http://ftp.altlinux.org/pub/distributions/ALTLinux p11/branch/x86_64 classic
    - rpm [p11] http://ftp.altlinux.org/pub/distributions/ALTLinux p11/branch/noarch classic
    - rpm [p11] http://ftp.altlinux.org/pub/distributions/ALTLinux p11/branch/x86_64-i586 classic
  tasks:
    - 391737
    - 397468

Ядро (kernel)

Блок для работы с ядром

Поле	Описание	Имя переменной среды
flavour	Разновидность ядра. Например, 6.12. Обязателен, если указываются модули	APM_BUILD_KERNEL_FLAVOUR
modules	Массив дополнительных модулей ядра
include-headers	Переменная, указывающая на то, включать ли заголовки ядра при установке

Примеры kernel

ALT Atomic Core:

kernel:
  flavour: 6.12
  modules:
    - drm

Использование ядра без модулей:

kernel:
  flavour: rt
  include-headers: true

Модули (modules)

Массив модулей для выполнения

Поле	Описание
name	Имя модуля, опционально и используется для вывода в логи во время выполнения
type	Типы модуля. Подробнее в разделе Типы модулей
if	Условие в формате языка Expr для выполнения этого модуля. Может использовать переменные среды и поля конфигурационного файла (подробнее в разделе «Переменные среды и поля конфигурационного файла»)
body	Тело модуля. Наполнение определяется полем type. Подробнее в разделе «Типы модулей»

Использование относительных путей

Относительные пути разворачиваются относительно директории ресурсов (по умолчанию — /etc/apm/resources).

Переменные среды и поля конфигурационного файла

Переменные среды и поля конфигурационного файла доступны в разделе if через структуру Env.VAR и Config.Var из текущего конфигурационного файла соответственно.

Пример модуля с использованием переменных среды и полей конфигурационного файла

modules:
  - type: shell
    if: Env.HOSTNAME == "good_host_name" || Config.Kernel.Flavour == "6.12"
    body:
      command: echo $HOSTNAME

Уточнение

К переменным среды, также, можно обращаться из раздела body в формате $NAME.

Для полей конфигурационного файла это не доступно.

Переменные среды

Переменные среды могут задаваться как в Containerfile, так и во время работы модулей.

Пример Containerfile:

ENV APM_BUILD_BUILD_TYPE="some-build-type"
ENV APM_BUILD_IMAGE="some-image"
ENV APM_BUILD_REPO_DATE="some-date"

Доступ из блока if:

Env.APM_BUILD_BUILD_TYPE
Env.APM_BUILD_IMAGE
Env.APM_BUILD_REPO_DATE

Доступ из блока body:

$APM_BUILD_BUILD_TYPE
$APM_BUILD_IMAGE
$APM_BUILD_REPO_DATE

Поля конфигурационного файла

Имена полей из конфигурационного файла преобразуются в PascalCase.

Пример конфигурационного файла:

name: some-name
image: some-image
build-type: some-type

kernel:
  modules:
    - some-module

Доступ из блока if:

Config.Name
Config.Image
Config.BuildName
Config.Kernel.Modules

Типы модулей

git

Модуль для клонирования и выполнения операций над склонированным репозиторием. После копирования репозитория команды будут выполняться внутри директории репозитория.

Легенда

! — обязательное поле;

? — должно быть указано хотя бы одно из этих полей.

Поле	Описание
url!	Ссылка на Git-репозиторий.
command?	Команда для выполнения.
commands?	Массив команд для выполнения.
deps	Зависимости сборки в виде пакетов. Они будут удалены после окончания сборки.

Примечание для command/commands

Если указаны оба поля, то выполнится сначала command, а затем всё из commands.

Пример git-модуля

Клонирование проекта https://github.com/SuperDev/SuperGoProject.git, установка зависимости golang (будет удалено после завершения работы модуля) и выполнение сборки и установки проекта:

modules:
  - type: git
    body:
      url: https://github.com/SuperDev/SuperGoProject.git
	  deps:
	    - golang
      command: |
        go build
        go install

copy

Модуль для копирования файлов и директорий.

Легенда

! — обязательное поле

Поле	Описание
target!	Путь до файла, который нужно скопировать.
destination!	Абсолютный путь, куда будет скопирован файл.
replace	Замещать ли объект по пути destination, если он уже существует. По умолчанию — false.

Пример copy-модуля

Копирование файла /etc/apm/resources/scripts/my-script в /usr/bin/my-script с заменой:

modules:
  - type: copy
    body:
      target: scripts/my-script
      destination: /usr/bin/my-script
      replace: true

include

Модуль для включения других конфигурационных файлов. Работает только с массивом modules (поля, не входящие в modules, будут игнорироваться).

Важно

include-модули не работают при использовании apm system image apply.

Легенда

? — должно быть указано хотя бы одно из этих полей.

Поле	Описание
target?	Путь к YAML-файлу
targets?	Массив путей к YAML-файлам

Пример include-модуля

Подключение файлов конфигурации /etc/apm/resources/packages.yml и /usr/share/strange_place/common.yml:

modules:
  - type: include
    body:
      targets:
        - packages.yml
	    - /usr/share/strange_place/common.yml

link

Создание символической ссылки (target), которая будет ссылаться на указанный файл или директорию (destination).

Легенда

! — обязательное поле

Имя	Описание
target!	Абсолютный путь, где будет создана ссылка
destination!	Путь, куда эта ссылка будет вести. Если путь относительный ссылка, создаётся «как есть», без развёртывания пути
replace	Замещать ли объект по пути target, если он уже существует. По умолчанию — false.

Важно

Окончание пути (имя файла или директории) в полях target и destination должны совпадать. Если target — /home, то строго destination должен записываться в формате <path>/home, где <path> — какой-то путь

Пример link-модуля

Создать ссылку /home, которая будет ссылаться на /var/home, с заменой, если /home существует.

modules:
  - type: link
    body:
      target: /home
      destination: /var/home
      replace: true

merge

Вставка содержимого одного файла в конец другого. Полезно для модификации конфигурационных файлов.

Легенда

! — обязательное поле

Имя	Описание
target!	Путь к файлу, содержимое которого нужно добавить
destination!	Путь к файлу, в конец которого нужно добавить содержимое

Пример merge-модуля

Дополнение файла /path/to/file2 содержимым файла /etc/apm/resources/path/to/file1

modules:
  - type: merge
    body:
      target: path/to/file1
      destination: /path/to/file2

replace

Замена содержимого файла по регулярному выражению.

Легенда

! — обязательное поле

Имя	Описание
target!	Абсолютный путь до файла
pattern!	Шаблон регулярного выражения
repl!	Текст, на который нужно заменить совпадения

::: Пример replace-модуль

В файле /path/ заменить все символы (.*) на строку (Что вы делаете в моём холодильнике?)

modules:
  - type: replace
    body:
      target: /path/to/file
      pattern: .*
      repl: Что вы делаете в моём холодильнике?

:::

move

Легенда

! — обязательное поле

Имя	Описание
target!	Абсолютный путь к объекту, который нужно переместить
destination!	Абсолютный путь к объекту, куда нужно переместить объект
replace	Замещать ли объект по пути destination, если он уже существует. По умолчанию — false.
create-link	Создать ли в target относительную ссылку на destination после перемещения. Подробнее в разделе про link-модуль.

Пример move-модуля

Переместить файл /path/to/file1 в /path/to/file2 с заменой, если file2 существует, со ссылкой /path/to/file1 на /path/to/file2:

modules:
  - type: move
    body:
      target: /path/to/file1
      destination: /path/to/file2
      replace: true
      create-link: true

packages

Действия с пакетами в рамках одной транзакции.

Имя	Описание
install	Массив пакетов для установки
remove	Массив пакетов для удаления

Пример packages-модуля

Будет установлен пакет stprl и удалён пакет flatpak:

modules:
  - type: packages
    body:
      install:
        - stplr
	  remove:
	    - flatpak

remove

Удаление файлов и директорий

Легенда

? — должно быть указано хотя бы одно из этих полей.

Имя	Описание
target?	Путь к объекту, который нужно удалить
targets?	Массив путей к объектам, которые нужно удалить

Примечание для target/targets

Если указаны оба поля, то выполнится сначала target, а затем всё из targets.

Пример remove-модуля

Удалить файл /path/to/file:

modules:
  - type: packages
    body:
      target: /path/to/file

shell

Выполнение Bash-команд

Легенда

? — должно быть указано хотя бы одно из этих полей.

Имя	Описание
command?	Команда для выполнения
commands?	Массив команд для выполнения

Примечание

Команды будут выполняться относительно директории ресурсов. По умолчанию — /etc/apm/resources).

Если указаны оба поля, то выполнится сначала command, а затем всё из commands.

Пример shell-модуля

Выполнить cat somefile > /path/to/file и export ARCH=$(uname -m)

modules:
  - type: shell
    body:
      commands:
        - cat somefile > /path/to/file
        - export ARCH=$(uname -m)

systemd

Модуль для включения сервсисов SystemD.

Легенда

? — должно быть указано хотя бы одно из этих полей.

Имя	Описание
target?	Имя сервиса
targets?	Массив имён сервисов
enabled	Включить ли серсвис. По умолчанию — false
global	Включить ли пользовательский сервис глобально (для всех пользователей). По умолчанию — false

Примечание для target/targets

Если указаны оба поля, то выполнится сначала target, а затем всё из targets.

Пример systemd-модуля

Включить сервисы service1 и service2, а также включить пользовательский сервис user-service

modules:
  - type: systemd
    body:
      targets: 
        - service1
        - service2
      enabled: true
  - type: systemd
    body:
      target: user-service
      enabled: true
      global: true

mkdir

Создание директорий по абсолютным путям.

Легенда

? — должно быть указано хотя бы одно из этих полей.

Имя	Описание
target?	Абсолютный путь к директории, которую нужно создать
targets?	Массив абсолютных путей к директориям, которые нужно создать

Примечание для target/targets

Если указаны оба поля, то выполнится сначала target, а затем всё из targets.

Пример mkdir-модуля

Создать директорию /usr/new-dir

modules:
  - type: mkdir
    body:
      targets: /usr/new-dir