Puppet — это централизованный инструмент управления конфигурацией и автоматизации. DevOps-команды создают конфигурации для развертывания серверов и приложений, а вся конфигурация хранится на центральном Puppet Server. Узлы Agent автоматически запрашивают конфигурацию у Puppet Server и приводят систему в описанное состояние.

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

В этом руководстве вы установите и настроите Puppet Server и Agent на Debian 11 (Bullseye). Puppet Server будет на хосте с именем puppet-server, а Agent — на хосте agent. В конце вы создадите первый модуль и манифест для установки базового LEMP-стека на агенте.

Требования

• Две виртуальные машины или физические сервера с Debian 11.
• Хост puppet-server: IP 192.168.5.100, FQDN puppet-server.localdomain.lan.
• Хост agent: IP 192.168.5.150, FQDN agent.localdomain.lan.
• Доступ root или пользователь с sudo.

Важно: в примерах используется подсеть 192.168.5.0/24 и порт 8140 для Puppet. Подставьте свои значения в продакшн-среде.

Настройка FQDN

Нужно задать корректные имена хостов и отредактировать /etc/hosts на обеих машинах, чтобы сервер и агент видели друг друга по именам.

На puppet-server выполните:

hostnamectl set-hostname puppet-server.localdomain.lan

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

hostnamectl set-hostname agent.localdomain.lan

Отредактируйте /etc/hosts и добавьте записи:

sudo vim /etc/hosts

Вставьте:

192.168.5.100   puppet-server.localdomain.lan
192.168.5.150   agent.localdomain.lan

Проверьте подключение командами ping обоих хостов:

ping puppet-server.localdomain.lan -c3
ping agent.localdomain.lan -c3

Вы должны увидеть ответы от соответствующих IP.

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

Puppet Labs предоставляет пакет репозитория для Debian 11. На обеих машинах загрузите пакет репозитория (релиз v7 на момент написания).

wget https://apt.puppet.com/puppet7-release-bullseye.deb
sudo dpkg -i puppet7-release-bullseye.deb
sudo apt update

После обновления индекс пакетов вы готовы установить Puppet-пакеты.

Установка Puppet Server

На puppet-server установите пакет puppetserver:

sudo apt install puppetserver

Пакет автоматически установит зависимости, включая Java OpenJDK.

Puppet хранит свои двоичные файлы в /opt/puppetlabs/bin. Чтобы команды puppet и puppetserver были доступны, загрузите окружение:

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

Если хотите, добавьте в ~/.bashrc:

echo "export PATH=$PATH:/opt/puppetlabs/bin/" | tee -a ~/.bashrc
source ~/.bashrc

Проверьте путь:

echo $PATH
puppetserver -v

Проверьте вывод — должна быть версия Puppet Server.

Измените параметры памяти Java, редакцией /etc/default/puppetserver. Подберите значение в зависимости от ОЗУ. Для 2 ГБ ОЗУ можно выделить 1 ГБ:

sudo vim /etc/default/puppetserver

Установите строку:

JAVA_ARGS="-Xms1g -Xmx1g"

Сохраните файл и перезапустите systemd и сервис:

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

Если используется UFW, откройте порт 8140 только для внутренней подсети:

sudo ufw allow from 192.168.5.0/24 to any proto tcp port 8140
sudo ufw status

Настройка конфигурации Puppet Server

Вы можете редактировать /etc/puppetlabs/puppet/puppet.conf вручную или использовать команду puppet config для создания параметров. Установим server, runinterval, environment и dns_alt_names:

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

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

Проверьте файл:

cat /etc/puppetlabs/puppet/puppet.conf

Перезапустите puppetserver:

sudo systemctl restart puppetserver

Установка и настройка Puppet Agent

На машине agent установите puppet-agent:

sudo apt install puppet-agent

Запустите и включите сервис Puppet:

sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

Добавьте в окружение путь к /opt/puppetlabs/bin так же, как делали на сервере.

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

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

Проверьте доступность FQDN с агента:

ping puppet-server.localdomain.lan -c3

Настройте параметры сервера и CA в конфигурации агента:

puppet config set server puppet-server.localdomain.lan --section agent
puppet config set ca_server puppet-server.localdomain.lan --section agent

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

sudo systemctl restart puppet
sudo systemctl status puppet

Теперь инициируйте генерацию запроса на подпись сертификата с агента:

puppet ssl bootstrap

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

puppetserver ca list --all
puppetserver ca sign --certname agent.localdomain.lan

Вы должны увидеть сообщение об успешной подписи. Затем проверьте список сертификатов:

puppetserver ca list-all

На агенте появится сообщение Completed SSL initialization, что означает успешную установку TLS-сессии.

Создание первого Puppet манифеста (модуль lemp)

Все модули среды production хранятся в /etc/puppetlabs/code/environments/production/.

Перейдите в каталог окружения и создайте структуру модуля:

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

Вставьте следующий манифест для установки LEMP (вариант базовый):

class lemp {

    Package { ensure => 'installed' }
    $lemppackages = [ 'nginx', 'mariadb-server', 'php-fpm' ]
    package { $lemppackages: }

    Service { ensure => 'running', enable => 'true'}
    $lempsvc = [ 'nginx', 'mariadb', 'php7.4-fpm' ]
    service { $lempsvc: }

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

}

Сохраните и проверьте синтаксис:

puppet parser validate init.pp

Создайте site manifest, чтобы привязать модуль к узлу agent:

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

Вставьте:

node 'agent.localdomain.lan' {
    include lemp
}

Сохраните и проверьте:

puppet parser validate site.pp

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

На агенте можно дождаться автоматического выполнения по расписанию или запустить вручную:

puppet agent -t

Результат покажет установленные пакеты и состояния сервисов.

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

sudo systemctl status nginx
sudo systemctl status mariadb
sudo systemctl status php7.4-fpm

Откройте в браузере http:// и вы увидите кастомную index.html:

Поздравляем — LEMP успешно развернут через Puppet.

Проверка и критерии приёмки

Критерии приёмки для успешного развёртывания:

• Puppet Server запущен и отвечает на порту 8140.
• Agent зарегистрирован и имеет подписанный сертификат на сервере.
• На агенте установлены пакеты nginx, mariadb-server, php-fpm.
• Сервисы nginx, mariadb, php-fpm активны и включены при старте.
• index.html от Puppet доступен через HTTP.

Команды для проверки:

sudo systemctl status puppetserver
puppetserver ca list-all
puppet agent -t
sudo systemctl status nginx mariadb php7.4-fpm
curl -I http://agent.localdomain.lan/

Если любой из этих пунктов не выполняется, см. раздел Устранение неисправностей.

Устранение неисправностей

Частые проблемы и быстрые решения:

• Puppet Agent не подключается к серверу: проверьте DNS/FQDN и /etc/hosts, доступность порта 8140, правильность server и ca_server в puppet.conf.
• Сертификат не подписан: на сервере выполните puppetserver ca list –all и puppetserver ca sign –certname <имя>. Повторно выполните puppet ssl bootstrap на агенте.
• Пакеты не устанавливаются: проверьте apt-репозитории, обновите apt update и проверьте зависимости (иногда нужно добавить component main в sources).
• Сервисы не стартуют: посмотрите логи systemd: journalctl -u nginx -e и /var/log/syslog для ошибок при старте.
• Неверные пути в PATH: убедитесь, что /opt/puppetlabs/bin есть в $PATH и что вы используете правильный бинарник puppet.

Полезные команды для отладки:

puppet config print all
puppet resource service 
puppet agent --test --debug --trace
sudo journalctl -u puppetserver -e

Важно: не подписывайте сертификаты неизвестных узлов. Сверяйте certname и IP.

Рекомендации по безопасности и хардининг

• Откройте порт 8140 только для доверенных подсетей.
• Настройте мониторинг сертификатов и автоматическую ротацию при необходимости.
• Обновляйте Puppet и компоненты ОС согласно политике безопасности.
• Ограничьте доступ к каталогу /etc/puppetlabs/code только администраторам.
• Используйте role-based access control (RBAC) для управления доступом к Puppet Enterprise или окружению.

Альтернативные подходы

Если Puppet не подходит, рассмотрите:

• Ansible — агентless, удобен для ad-hoc задач и инфраструктуры без постоянного агента.
• Chef — похож на Puppet, ориентирован на Ruby DSL.
• SaltStack — быстрый, масштабируемый, поддерживает push и pull модели.

Модель принятия решения: для управления долгожителями-серверами и детерминированных конфигураций Puppet часто лучше; для одноразовых задач и меньшего накладного агента — Ansible.

Модель мышления и хорошие практики

• Идем сверху вниз: environment → role → profile → module.
• Держите модули идемпотентными: повторное применение не должно ломать систему.
• Делите роли и профили: роль связывает профили, профиль управляет модулями.
• Тестируйте модули локально и на staging перед промоцией в production.

Мини-методология тестирования манифестов:

1. Парсинг и синтаксический анализ: puppet parser validate.
2. Линтинг: puppet-lint (опционально).
3. Прогон в изолированной среде (LXC, Vagrant, Docker с systemd).
4. Интеграция через CI, прогон puppet agent –test в тестовом окружении.

Пример улучшенного модуля lemp с параметрами

Ниже пример более гибкого init.pp, где используются параметры и зависимости:

class lemp(
  Array[String] $packages = ['nginx','mariadb-server','php-fpm'],
  Array[String] $services = ['nginx','mariadb','php7.4-fpm'],
  String $index_content = '
Welcome to Nginx - Managed by Puppet
'
) {

  package { $packages:
    ensure => installed,
  }

  file { '/var/www/html/index.html':
    ensure  => file,
    content => $index_content,
    mode    => '0644',
    require => Package['nginx'],
  }

  service { $services:
    ensure => running,
    enable => true,
    require => Package[$packages],
  }

}

Такой подход упрощает переиспользование и тестирование.

Playbook для развертывания Puppet в вашей сети

Шаги SOP для администратора:

1. Подготовить 2 ВМ с Debian 11.
2. Настроить FQDN и /etc/hosts.
3. Добавить репозиторий Puppet и обновить apt.
4. Установить puppetserver на сервере.
5. Скорректировать JAVA_ARGS и запустить сервис.
6. Установить puppet-agent на клиенте.
7. Инициировать puppet ssl bootstrap на клиенте.
8. Подписать CSR на puppetserver.
9. Развернуть модуль и проверить по критериям приёмки.

Роль-базированные чеклисты

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

• Убедиться в наличии резервного копирования /etc/puppetlabs.
• Настроить ротацию логов.
• Контролировать сертификаты и список подписанных узлов.

DevOps-инженер (модули и манифесты):

• Следить за идемпотентностью.
• Писать тесты для модулей.
• Поддерживать структуру environment/roles/profiles.

Разработчик приложения:

• Тестировать, что deployment-манифесты корректно настраивают окружение.
• Писать параметры конфигурации для модулей.

Тестовые сценарии и критерии приёмки

Тест-кейсы:

• После puppet agent -t на агенте, пакеты nginx, mariadb-server и php-fpm должны быть установлены.
• Файл /var/www/html/index.html должен содержать ожидаемую строку.
• systemctl status должен показать active (running) для всех трёх сервисов.

Критерии приёмки приведены в разделе Критерии приёмки.

Диаграмма принятия решения при ошибках

flowchart TD
  A[Agent не подключается] --> B{Проверить DNS}
  B -- OK --> C{Порт 8140 доступен?}
  B -- Не OK --> D[Исправить /etc/hosts или DNS]
  C -- Да --> E{Сертификат подписан?}
  C -- Нет --> F[Открыть порт 8140 в firewall]
  E -- Да --> G[puppet agent -t с debug]
  E -- Нет --> H[puppetserver ca list; sign certname]

Краткий глоссарий

• Puppet Server: центральный сервис, хранящий коды конфигураций.
• Puppet Agent: клиент, применяющий манифесты.
• manifest: файл с декларативной конфигурацией (init.pp, site.pp).
• module: набор манифестов, файлов и шаблонов.

Когда решать не использовать Puppet

• Если инфраструктура небольшая и вы предпочитаете agentless подход — выбирайте Ansible.
• Если вам требуется быстрое одноразовое конфигурирование — Ansible или ad-hoc скрипты быстрее.

Заключение

Вы успешно установили Puppet Server и Puppet Agent на Debian 11 и создали первый модуль для развертывания LEMP. В руководстве показаны шаги от настройки FQDN до подписи TLS-сертификатов и запуска puppet agent. Вложены практические советы, чеклисты и примеры кода для промышленного использования.

Важно: адаптируйте значения памяти, политики firewall и адреса под вашу инфраструктуру. Следуйте принципам идемпотентности и используйте тестирование перед промоцией в production.

Краткое резюме и следующие шаги: настройте CI для тестирования модулей, добавьте второй агент и разделите конфигурацию на роли и профили для масштабирования.

Заметки

• В примерах используется пакет php7.4-fpm. В зависимости от репозитория и версии Debian пакет может называться иначе (php-fpm). Проверьте доступные пакеты с apt-cache search php | grep fpm.
• Если вы используете Puppet Enterprise, UI и RBAC будут доступны и части команды управления могут отличаться.