DevOpsLab/docs/quickstart-for-dummies.md

DevOpsLab: пошаговое руководство для новичков

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Это руководство описывает по шагам: создание роли, объединение ролей в плейбук, линт, тестирование на контейнерах (подах) с разным количеством и разными ОС, а также формирование инвентори для деплоя на реальные серверы. Подходит и для Docker, и для Podman (отличия указаны в конце).

---

Что нужно установить

• Make (обычно уже есть в Linux/macOS).
• Podman (ветка podman) или Docker (ветка main) — для контейнеров.
• Ansible не обязателен на хосте: тесты и деплой можно запускать через контейнер из Makefile.

Клонируйте репозиторий и перейдите в каталог проекта. Все команды ниже выполняются из корня проекта.

---

Шаг 1. Создать новую роль

Роль — это набор задач (tasks), шаблонов и переменных для одной цели (например, установка nginx или настройка пользователей).

Команда:

make role create

Скрипт спросит имя роли (латиницей, например nginx или myapp). Будет создана структура:

• roles/<имя_роли>/tasks/main.yml — основные задачи
• roles/<имя_роли>/handlers/main.yml
• roles/<имя_роли>/defaults/main.yml — переменные по умолчанию
• roles/<имя_роли>/meta/main.yml
• и др.

Что сделать после создания:

1. Открыть roles/<имя_роли>/tasks/main.yml и добавить свои задачи (модули package, copy, template, service и т.д.).
2. При необходимости задать переменные в roles/<имя_роли>/defaults/main.yml.

Роль автоматически попадёт в общий плейбук развёртывания после следующего шага (обновления плейбуков).

---

Шаг 2. Объединить роли в один плейбук

Все роли, которые должны выполняться на серверах, собираются в один плейбук: roles/deploy.yml.

Вариант А — обновить плейбук автоматически (все роли из roles/):

make update-playbooks

Скрипт перезапишет roles/deploy.yml: для каждой роли в каталоге roles/ будет добавлен свой play (hosts: all, одна роль в play).

Вариант Б — править вручную:

Откройте roles/deploy.yml. Каждая роль описывается своим блоком:

- name: Установка роли repo
  hosts: all
  become: true
  roles:
    - repo

- name: Установка роли devops
  hosts: all
  become: true
  roles:
    - devops

• Чтобы включить роль — добавьте такой блок или раскомментируйте существующий.
• Чтобы выключить роль — закомментируйте блок (перед каждой строкой поставьте #).
• Порядок блоков задаёт порядок применения ролей.

Итог: в roles/deploy.yml перечислены все роли, которые будут и тестироваться в контейнерах, и деплоиться на реальные серверы (см. шаги 4 и 6).

---

Шаг 3. Запуск линт-проверок

Линт проверяет синтаксис и типичные ошибки в ролях (и в плейбуках, которые их вызывают).

Проверить все роли:

make role lint

Проверить одну роль:

make role lint <имя_роли>
# Пример:
make role lint repo
make role lint devops

При ошибках будут указаны файл и строка. Исправьте замечания и запустите линт снова. Без ошибок линт завершится без падения.

---

Шаг 4. Тестирование ролей на контейнерах (подах)

Тесты поднимают контейнеры с разными ОС, применяют к ним плейбук (в т.ч. ваши роли) и проверяют результат. Контейнеры в этом шаге — это и есть «поды» (тестовые хосты).

4.1. Подготовка образов (чтобы не качать из registry)

Если используете Podman (ветка podman):

Образы должны быть собраны локально. Один раз выполните:

make buildall

Собираются все образы (Ubuntu, Debian, CentOS и т.д.). Долго, но делается один раз. Для одного образа, например для минимального теста:

make buildall-image IMAGE=ubuntu22
make buildall-image IMAGE=debian12

Если используете Docker (ветка main):

make docker build

(при необходимости сначала make docker setup-builder).

4.2. Запуск тестов

С пресетом по умолчанию (обычно 2 хоста):

make role test

С конкретным пресетом:

make role test minimal
make role test default
make role test all-images

Что происходит: создаются контейнеры по выбранному пресету, к ним применяется плейбук (converge), затем они удаляются. Результат виден в выводе команды.

---

Шаг 5. Менять количество подов и ОС (пресеты)

Количество «подов» (контейнеров) и их ОС задаются пресетами — файлами в molecule/presets/ и molecule/presets/examples/.

5.1. Посмотреть доступные пресеты

make presets list

Будет выведен список пресетов и краткое описание (в т.ч. количество хостов).

5.2. Что задаёт пресет

В пресете задаётся:

• hosts — список хостов (контейнеров): имя, семейство ОС (family), группы.
• images — соответствие family и образа (например ubuntu22: "inecs/ansible-lab:ubuntu22-latest").
• Общие настройки (сеть, systemd и т.д.).

От количества элементов в hosts и от выбранных family зависит, сколько подов поднимется и какие ОС будут использоваться.

5.3. Примеры пресетов по количеству и ОС

Пресет	Описание	Кол-во хостов
minimal	Один хост (быстрый тест)	1
default	Два хоста (например Ubuntu + Debian)	2
all-images	Максимум образов/ОС	много

Запуск:

make role test minimal
make role test default
make role test all-images

5.4. Создать свой пресет (свои поды и ОС)

1. Скопируйте существующий пресет, например:

   cp molecule/presets/default.yml molecule/presets/my-preset.yml
   

2. Откройте molecule/presets/my-preset.yml.

3. В секции hosts укажите свои хосты. Формат одного хоста:

   hosts:
     - name: web1
       family: ubuntu22
       groups: [web, test]
     - name: db1
       family: centos9
       groups: [db, test]
     - name: lb1
       family: debian12
       groups: [lb, test]
   

   • name — уникальное имя контейнера (пода).
   • family — ключ из секции images (ubuntu20, ubuntu22, ubuntu24, debian9–debian12, centos7–centos9, alma, rocky, rhel, redos, astra, alt9, alt10 и т.д.).
   • groups — группы для инвентори (можно использовать в плейбуках через hosts: web или hosts: db).

4. Сохраните файл. Запуск теста с вашим пресетом:

   make role test my-preset
   

Количество подов = количество элементов в списке hosts. Разные ОС = разные family при наличии соответствующих образов в images (и собранных локально при Podman через make buildall).

---

Шаг 6. Инвентори и деплой на реальные серверы

Когда роли и плейбук готовы и протестированы в контейнерах, их можно применять к реальным серверам. Для этого нужен инвентори и команды деплоя.

6.1. Где лежит инвентори

Файл инвентори по умолчанию:

• inventory/hosts.ini

Именно его используют команды make role deploy и make role dryrun (см. ниже).

6.2. Как сформировать инвентори

Откройте inventory/hosts.ini. Формат — обычный ini-инвентори Ansible.

Пример минимального инвентори:

# Группа веб-серверов
[web_servers]
web1 ansible_host=192.168.1.10 ansible_user=deploy
web2 ansible_host=192.168.1.11 ansible_user=deploy

# Группа БД
[db_servers]
db1 ansible_host=192.168.1.20 ansible_user=deploy

# Общие переменные для всех хостов
[all:vars]
ansible_ssh_private_key_file=~/.ssh/id_rsa
ansible_ssh_common_args='-o StrictHostKeyChecking=no'

• Группы — [web_servers], [db_servers]. Имена можно менять и добавлять свои.
• Хосты — каждая строка: имя хоста + переменные. Обязательно укажите ansible_host (IP или hostname) и ansible_user (пользователь для SSH).
• all:vars — переменные для всех хостов (ключ SSH, опции подключения и т.д.).

Чтобы применять плейбук только к части серверов, в плейбуке можно использовать группы (например hosts: web_servers) или ограничивать запуск через --limit (см. ниже).

6.3. Проверка без изменений (dry-run)

Перед реальным деплоем полезно проверить, что плейбук выполнится без ошибок и что изменения именно те, что нужны:

make role dryrun <имя_роли>
# Пример:
make role dryrun repo

Команда запускает плейбук в режиме check (без реальных изменений) для указанной роли. Убедитесь, что в inventory/hosts.ini указаны ваши серверы и что с них есть SSH-доступ.

6.4. Реальный деплой плейбука на серверы

Когда инвентори заполнен и dry-run устраивает:

make role deploy

Будет выполнен плейбук roles/deploy.yml на всех хостах из inventory/hosts.ini (с подтверждением перед применением). При необходимости можно запускать Ansible вручную, например:

• Только на одной группе:

  ansible-playbook -i inventory/hosts.ini roles/deploy.yml --limit web_servers
  

• Только проверка (аналог dry-run для всего плейбука):

  ansible-playbook -i inventory/hosts.ini roles/deploy.yml --check --diff
  

(Если Ansible запускается через контейнер в Makefile, пути и вызов могут отличаться; логика та же: тот же инвентори и тот же плейбук.)

6.5. Кратко по шагам деплоя

1. Заполнить inventory/hosts.ini (группы, хосты, ansible_host, ansible_user, ключ SSH).
2. Проверить доступ: ansible -i inventory/hosts.ini all -m ping (если Ansible установлен локально).
3. Запустить make role dryrun <роль> для проверки.
4. Запустить make role deploy для применения плейбука к реальным серверам.

---

Универсальность: Docker и Podman

Один и тот же сценарий (роли, плейбук, пресеты, инвентори) работает и с Docker, и с Podman. Отличия только в подготовке образов и в том, как вызываются контейнеры внутри Makefile.

Действие	Podman (ветка podman)	Docker (ветка main)
Сборка образов	make buildall	make docker build
Один образ	make buildall-image IMAGE=ubuntu22	make docker build-image IMAGE=ubuntu22
Запуск тестов	make role test [preset]	то же
Линт	make role lint	то же
Деплой / инвентори	make role deploy, inventory/hosts.ini	то же

• Пресеты, роли, deploy.yml, inventory — одни и те же.
• Линт, тесты, деплой — одни и те же команды make role ....
• Разница только в том, как и откуда берутся образы (локальная сборка через buildall у Podman или сборка/пулл через docker build у Docker).

K8s в этом руководстве не рассматривается; см. отдельную документацию по Kubernetes при необходимости.