Puppet — централизованная система управления конфигурацией: установите Puppet Server на одном сервере и Puppet Agent на другом, настройте DNS/hosts, откройте порт 8140, подпишите сертификат агента и примените первый манифест (в примере — LAMP). В статье приведён пошаговый SOP, чеклисты, рекомендации по безопасности, отладке и примеры тестов.

Что такое Puppet — кратко

Puppet — инструмент централизованного управления конфигурацией и автоматизации. Он использует свой DSL, похожий на Ruby, для описания желаемого состояния систем. Сервер (Puppet Server) хранит конфигурации; агенты (Puppet Agent) регулярно подтягивают каталоги и приводят узлы в описанное состояние. Взаимодействие по умолчанию защищено SSL/TLS сертификатами.

Важно: в этой инструкции предполагаются два сервера AlmaLinux 8: один для Puppet Server и один для Puppet Agent. Все команды выполняются с правами пользователя, имеющего sudo.

Основные понятия (1‑строчное определение)

• Puppet Server — централизованный сервер конфигураций.
• Puppet Agent — клиент, применяющий конфигурации.
• Манифест (manifest) — файл с описанием ресурсов и состояний.
• Каталог (catalog) — сгенерированная сервером инструкция для агента.
• CA (Certificate Authority) — внутренняя CA Puppet, подписывающая сертификаты агентов.

Содержание

• Предварительные требования
• Настройка hostname и /etc/hosts
• Установка репозитория Puppet и пакетов
• Конфигурация Puppet Server и Agent
• Открытие порта в firewalld
• Регистрация и подписание сертификатов агента
• Создание первого манифеста (LAMP)
• Применение манифеста и проверка
• Отладка: типичные ошибки и шаги по их устранению
• Безопасность и hardening
• SOP: добавление нового агента — пошагово
• Роль‑ориентированные чеклисты
• Критерии приёмки и тесты
• Краткий глоссарий
• Заключение

Предварительные требования

• Два сервера AlmaLinux 8 (или совместимые):
  • pp-server — IP 192.168.10.20 — роль: Puppet Server
  • agent1 — IP 192.168.10.21 — роль: Puppet Agent
• Пользователь с sudo на обоих хостах.
• Доступ между серверами по сети (внутренний диапазон 192.168.10.0/24 в примере).
• Рекомендуется использовать FQDN вместо «чистых» IP — это упрощает сертификаты и совместимость.

Важно: адаптируйте IP‑диапазоны и FQDN под свою инфраструктуру (например, prod.example.local).

Настройка /etc/hosts и hostname

Перед установкой Puppet рекомендуется настроить FQDN и /etc/hosts. В этом примере используем домен hwdomain.lan.

На Puppet Server выполните:

sudo hostnamectl set-hostname pp-server.hwdomain.lan

На Agent:

sudo hostnamectl set-hostname agent1.hwdomain.lan

Отредактируйте /etc/hosts (на обоих узлах):

sudo nano /etc/hosts

Добавьте записи (замените IP и домен на свои):

192.168.10.20   pp-server.hwdomain.lan   pp-server
192.168.10.21   agent1.hwdomain.lan    agent1

Проверьте FQDN:

sudo hostname -f

Проверьте доступность через ping:

ping -c3 pp-server.hwdomain.lan
ping -c3 pp-server

ping -c3 agent1.hwdomain.lan
ping -c3 agent1

Примечание: если вы используете реальный DNS, достаточно корректных запиcей в зоне, /etc/hosts нужен только при отсутствии DNS или для тестов.

Установка Puppet: репозиторий и пакеты

Добавим официальный репозиторий Puppet на оба узла и установим соответствующие пакеты.

Добавление репозитория Puppet (оба узла)

sudo rpm -Uvh https://yum.puppet.com/puppet7-release-el-8.noarch.rpm
sudo dnf repolist

Вы должны увидеть репозиторий puppet в списке.

Установка Puppet Server (на pp-server)

sudo dnf install puppetserver

Подтвердите установку и импорт GPG‑ключа, когда будет запрошено.

После установки загрузите профиль окружения Puppet и проверьте PATH:

source /etc/profile.d/puppet-agent.sh
echo $PATH

Вы должны увидеть /opt/puppetlabs/bin в PATH. Проверьте бинарь и версию:

which puppetserver
puppetserver -v

Установка Puppet Agent (на agent1)

sudo dnf install puppet-agent

Подтвердите импорт GPG‑ключа при необходимости.

После установки загрузите профиль и проверьте PATH:

source /etc/profile.d/puppet-agent.sh
echo $PATH
which puppet
puppet -v

Вы должны увидеть /opt/puppetlabs/bin/puppet и версию (в примере v7.11).

Запустите и включите службу агента:

sudo systemctl start puppet
sudo systemctl enable puppet
sudo systemctl status puppet

Конфигурация Puppet Server

Отредактируем параметры сервера, память JVM и базовые настройки.

Откройте файл конфигурации службы:

sudo nano /etc/sysconfig/puppetserver

Увеличьте память JVM при необходимости (пример для сервера с 4 ГБ ОЗУ — выделяем 2 ГБ):

# Modify this if you'd like to change the memory allocation, enable JMX, etc
JAVA_ARGS="-Xms2g -Xmx2g"

Сохраните.

Установите имя сервера и runinterval (как часто агент применяет конфигурацию):

puppet config set server pp-server.hwdomain.lan --section main
puppet config set runinterval 1h --section main

Установите окружение production и альтернативные DNS‑имена:

puppet config set environment production --section server
puppet config set dns_alt_names pp-server,pp-server.hwdomain.lan --section server

Просмотрите результирующий файл /etc/puppetlabs/puppet/puppet.conf:

cat /etc/puppetlabs/puppet/puppet.conf

Перезагрузите systemd и запустите службу puppetserver:

sudo systemctl daemon-reload
sudo systemctl start puppetserver
sudo systemctl enable puppetserver
sudo systemctl status puppetserver

Важно: для production рекомендуется подобрать параметры JVM в зависимости от количества агентов и нагрузки (RAM × число агентов ≈ ориентиры). Настройка мониторинга и SLI/SLO полезна на масштабах >50 агентов.

Настройка firewalld на Puppet Server

Откройте порт 8140 (TCP) и добавьте сеть источника, если используете firewalld:

sudo firewall-cmd --add-source=192.168.10.0/24 --permanent
sudo firewall-cmd --add-port=8140/tcp --permanent
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

Вы должны увидеть добавленную зону/источник и разрешённый порт 8140.

Регистрация Puppet Agent на Puppet Server

Процесс включает: указание сервера в конфигурации агента, перезапуск службы агента, генерацию CSR, и подпись сертификата на сервере.

На агенте укажите сервер и CA:

puppet config set server pp-server.hwdomain.lan --section agent
puppet config set ca_server pp-server.hwdomain.lan --section agent

Проверьте /etc/puppetlabs/puppet/puppet.conf:

cat /etc/puppetlabs/puppet/puppet.conf

Перезапустите агент и убедитесь, что он запущен:

sudo systemctl restart puppet
sudo systemctl status puppet

Инициализируйте SSL сгенерировав CSR и отправив в CA:

puppet ssl bootstrap

На сервере просмотрите список сертификатов и подпишите запрос агента:

puppetserver ca list --all
puppetserver ca sign --certname agent1.hwdomain.lan

После подписи вы увидите сообщение: Successfully signed certificate request for agent1.hwdomain.lan. На агенте появится: Notice: Completed SSL initialization.

Повторно проверьте список сертификатов:

puppetserver ca list --all

Убедитесь, что сертификат для agent1.hwdomain.lan в разделе Signed Certificates.

Создание первого Puppet‑манифеста (LAMP)

На Puppet Server создадим модуль lamp и манифест, который установит httpd, mariadb и php, создаст index.html и info.php.

Создайте структуру каталогов и файлы манифеста:

cd /etc/puppetlabs/code/environments/production/
mkdir -p modules/lamp/{manifests,files}
cd modules/lamp/
nano manifests/init.pp

Вставьте следующий код (сохраните как manifests/init.pp):

class lamp {

    Package { ensure => 'installed' }
    $lamppackages = [ 'httpd', 'mariadb-server', 'php' ]
    package { $lamppackages: }

    Service { ensure => 'running', enable => 'true'}
    $lampsvc = [ 'httpd', 'mariadb' ]
    service { $lampsvc: }

    file { '/var/www/html/index.html':
     ensure  => file,
     content => "
Welcome to httpd - Managed by Puppet
",
     mode    => '0644',
    }

    file { '/var/www/html/info.php':
     ensure  => file,
     content => "",
     mode    => '0644',
    }

}

Создайте файл манифеста узлов (sites.pp):

cd /etc/puppetlabs/code/environments/production/
nano manifests/sites.pp

Добавьте привязку модуля к узлу:

node 'agent1.hwdomain.lan' {
    include lamp
}

Сохраните и закройте редактор.

Комментарии к манифесту:

• Package { ensure => ‘installed’ } — задаёт дефолт для ресурсов package в этом классе.
• Service { ensure => ‘running’, enable => ‘true’ } — гарантирует запуск и автозапуск сервисов.
• Если нужны более точные зависимости (например, настроить БД до запуска сервиса), используйте ресурсы notify/require/subscribe либо metaparameter before/require.

Применение манифеста на агенте

На агенте запустите ручное применение:

puppet agent -t

Агент должен получить каталог, закэшировать его и применить ресурсы.

Проверьте статус сервисов:

sudo systemctl is-enabled httpd
sudo systemctl status httpd

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

Откройте в браузере http://192.168.10.21/ — вы должны увидеть index.html. По адресу http://192.168.10.21/info.php — вывод phpinfo.

Проверка и приёмка — что тестировать

Критерии приёмки (минимум):

• Агент проходит TLS‑аутентификацию и имеет подписанный сертификат на сервере.
• При выполнении puppet agent -t отсутствуют ошибки и все ресурсы применены с состоянием “changed”/“ok” как ожидается.
• httpd и mariadb установлены, запущены и включены в автозагрузку.
• Файлы /var/www/html/index.html и /var/www/html/info.php присутствуют и имеют корректное содержимое и права доступа.

Тестовые команды для верификации:

puppet agent -t
sudo systemctl status httpd
curl -I http://localhost/    # проверка кодов 200
php -v                         # проверка PHP на агенте

Отладка: типичные проблемы и решения

1. Puppet Agent не может подключиться к серверу (connection refused / timeout)

• Проверьте доступность порта 8140 (telnet/ss/ss -tnlp), правила firewalld/iptables.
• Проверьте правильность server/ca_server в /etc/puppetlabs/puppet/puppet.conf.

2. Сертификат на сервере в состоянии waiting или не подписан

• На агенте: puppet ssl bootstrap
• На сервере: puppetserver ca list –all и puppetserver ca sign –certname <имя>

3. Проблемы с путями и PATH (puppet не найден в PATH)

• Убедитесь, что вы загрузили профиль: source /etc/profile.d/puppet-agent.sh
• Перезапустите shell или вручную указывайте полный путь /opt/puppetlabs/bin/puppet

4. SELinux мешает установке/запуску httpd или записи в директории

• Проверяйте audit.log (/var/log/audit/audit.log) и use restorecon/chcon для корректных меток.
• Для тестов можно временно переключить SELinux в permissive, но в production решайте через правильные контексты.

5. Длительное время генерации каталога / высокое потребление памяти puppetserver

• Подберите параметры JVM в /etc/sysconfig/puppetserver; добавьте мониторинг и масштабирование при росте числа агентов.

Безопасность и hardening

• Всегда используйте FQDN в сертификатах и конфигурациях.
• Разграничьте сеть Puppet (VLAN/ACL) — доступ к порту 8140 должен быть контролируемым.
• Регулярно обновляйте пакеты Puppet и OS.
• Резервно храните /etc/puppetlabs и репозитории кода (Git).
• Рассмотрите использование Hiera для хранения чувствительных данных, а секреты — через зашифрованные бэкэнды (eyaml, Vault).
• Аудитируйте логи puppetserver/puppet-agent и systemd для выявления аномалий.

Замечание о персональных данных и GDPR: если вы через Puppet конфигурируете службу, которая хранит персональные данные, обеспечьте шифрование и контроль доступа к конфигурациям, содержащим эти данные. Храните минимально достаточный набор данных в открытом виде.

SOP: добавить новый агент — пошаговый плейбук

1. Зарегистрировать запись в DNS (FQDN) или добавить запись в /etc/hosts на сервере и в существующих узлах.
2. Установить пакет puppet-agent (rpm репозиторий puppet).
3. Настроить /etc/puppetlabs/puppet/puppet.conf: server и ca_server на FQDN Puppet Server.
4. Запустить puppet ssl bootstrap на агенте.
5. На сервере проверить список CSR: puppetserver ca list –all.
6. Подписать сертификат: puppetserver ca sign –certname .
7. На агенте выполнить puppet agent -t и проверить, что применены нужные классы.
8. Добавить узел в site manifest или через ENC/Hiera.
9. Протоколирование: зафиксировать в CMDB/там где храните инвентарь.

Роль‑ориентированные чеклисты

Администратор (Puppet Server):

• Проверить состояние puppetserver и логи.
• Подписать CSR и контролировать список сертификатов.
• Обновлять репозитории модулей и тикетировать изменения в репозитории кода.

Оператор (поддержка):

• Проверить статус агента и сервисов на узлах.
• При проблемах собирать логи: /var/log/puppetlabs/puppetserver/ и /var/log/puppetlabs/puppet/ на агенте.

Разработчик конфигураций:

• Писать idempotent модули.
• Создавать тесты (beaker, rspec‑puppet) для модулей.

Acceptance / Критерии приёмки (тестовые сценарии)

Тесты для проверки работоспособности манифеста:

• TC1: puppet agent -t выполняется без ошибок и возвращает exit code 0.
• TC2: Файлы index.html и info.php существуют с правильным содержимым и правами.
• TC3: Сервисы httpd и mariadb запущены и включены в автозагрузку.
• TC4: HTTP GET / возвращает код 200.

Примеры команд для автоматизации тестов:

ssh root@agent1 'puppet agent -t --detailed-exitcodes; echo $?'  # ожидаем 0/2
ssh root@agent1 'test -f /var/www/html/index.html && echo OK'
curl -s -o /dev/null -w "%{http_code}" http://192.168.10.21/

Мини‑методология: как писать устойчивые Puppet‑модули

• Идем от простого к сложному: сначала установить пакет и сервис, затем добавлять конфигурации.
• Используйте declare‑style классы и избегайте множества инстанций с одинаковыми именами.
• Используйте зависимости (require, before) для надёжного порядка.
• Пишите idempotent ресурсы: повторный запуск не должен ломать систему.

Decision Tree — как действовать при проблемах с сертификатом

flowchart TD
  A[Агент не подключается] --> B{Есть ли соединение по 8140?}
  B -- Нет --> C[Проверить firewalld/маршрутизацию]
  B -- Да --> D{Сгенерирован ли CSR на агенте?}
  D -- Нет --> E[Выполнить puppet ssl bootstrap на агенте]
  D -- Да --> F{CSR подписан на сервере?}
  F -- Нет --> G[На сервере: puppetserver ca list --all; puppetserver ca sign --certname <имя>]
  F -- Да --> H[На агенте: puppet agent -t и проверка логов]
  C --> I[Разобраться с сетью]
  G --> H

Полезные команды сбора информации (cheat‑sheet)

• Проверить версию puppetserver: puppetserver -v
• Список сертификатов: puppetserver ca list –all
• Подписать сертификат: puppetserver ca sign –certname
• Логи puppetserver: /var/log/puppetlabs/puppetserver/puppetserver.log
• Логи агента: /var/log/puppetlabs/puppet/puppet.log

Security checklist и mitigations

• Отключить неиспользуемые DNS‑alias в dns_alt_names.
• Регулярно ротация сертификатов (если есть политика).
• Контроль доступа к Puppet Console (если используется).
• Защитить Git‑репозиторий с кодом Puppet: MFA, RBAC.

Краткий глоссарий (1 строка на термин)

• FQDN — fully qualified domain name, полное доменное имя хоста.
• CSR — certificate signing request, запрос на подпись сертификата.
• Idempotent — свойство операции давать одинаковый результат при повторном применении.
• Hiera — иерархическое хранилище данных для Puppet.

Заключение

Вы успешно установили и настроили Puppet Server и Puppet Agent на AlmaLinux, настроили сетевую доступность, подписали сертификат агента и создали первый манифест для установки LAMP‑стека. В статье приведены практические SOP, чеклисты и рекомендации по отладке и безопасности — используйте их как стартовую базу и расширяйте модули по мере роста инфраструктуры.

Важно: при масштабировании подумайте о мониторинге puppetserver, резервном хранении кода модулей и применении практик CI для тестирования модулей (rspec‑puppet, beaker).