Ansible

Данное руководство описывает процесс автоматизированной установки и настройки агентов системы мониторинга Astra Monitoring на группу серверов под управлением Linux с использованием Ansible.

Зачем это нужно?

  • Массовая установка: Развертывание агентов на десятках или сотнях серверов одновременно

  • Единообразие конфигурации: Гарантия того, что все агенты настроены одинаково и корректно

  • Автоматизация: Исключение человеческого фактора и рутинных операций

  • Управление через код: Возможность версионирования и контроля изменений конфигурации

Перед началом работы убедитесь, что:

  • Ansible установлен и настроен на управляющей машине

  • У вас есть доступ по SSH на целевые хосты

  • Вы имеете привилегии sudo на целевых хостах

  • У вас есть адрес сервера мониторинга и токен для подключения (если используется)

Установка роли Ansible

Для использования роли установки агента ее необходимо сначала загрузить из репозитория. Роль будет скачана в локальную коллекцию Ansible.

Ознакомьтесь с публичным репозиторием роли ansible-role-am-agent

Выполните команду на управляющей машине (там, где установлен Ansible):

shell
ansible-galaxy install git+https://gitflic.ru/project/astra-monitoring/ansible-role-am-agent.git

Результат: Роль ansible-role-am-agent будет загружена и станет доступна для использования в ваших плейбуках.

Подготовка плейбука для установки

Создайте файл плейбука (например, install-am-agent.yml) со следующим содержимым, это минимальная конфигурация.

install-am-agent.yml
- name: Install astra-monitoring agent
  hosts: all  # На каких хостах запускать (all = все хосты из инвентаря)
  gather_facts: true  # Собирать информацию о хостах (обязательно true)
  become: true  # Выполнять с повышенными привилегиями (обязательно true)
  roles:
    - role: "ansible-role-am-agent"
      vars:
        am_agent_upstream_address: "https://your-monitoring-server.com"  # ЗАМЕНИТЕ на ваш адрес
        am_agent_upstream_token: "your-secure-token"  # ЗАМЕНИТЕ на ваш токен (если используется)

Подготовка инвентаря для установки

Создайте файл инвентаря для вашей инфраструктуры.

Пример инвентаря для установки на локальный хост:

your_inventory_file.yml
all:
  hosts:
    localhost:
      ansible_connection: local
      ansible_become: true

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

shell
ansible all -i your_inventory_file.yml -m ping

Запуск плейбука

Запустите выполнение плейбука на целевых хостах:

shell
ansible-playbook -i your_inventory_file.yml install-am-agent.yml

Где:

  • your_inventory_file.yml - файл с перечнем ваших серверов (инвентарь)

  • install-am-agent.yml - созданный вами плейбук

Что произойдет при запуске:

  1. Ansible подключится к указанным хостам

  2. Установит агент мониторинга в директорию /opt/am-agent

  3. Настроит агент для подключения к вашему серверу мониторинга

  4. Зарегистрирует и запустит агент как systemd-сервис

  5. Агент начнет отправлять метрики на сервер

Основные параметры конфигурации

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

Параметр

Описание

Обязательный

По умолчанию

am_agent_enabled

Включает/выключает выполнение роли

Нет

true

am_agent_upstream_address

Адрес сервера мониторинга для подключения агента

Да

""

am_agent_upstream_token

Токен для аутентификации на платформе мониторинга

нет

""

am_agent_proxy_url

Адрес, который будет слушать агент для подключения других агентов (режим прокси)

Нет

0.0.0.0:9700

am_agent_autodiscovery

Включает режим автонастройки и обнаружения

Нет

true

am_agent_systemd_autostart

Включает автозапуск агента как службы systemd при загрузке системы

Нет

true

am_agent_install_path

Директория для установки агента

Нет

/opt/am-agent

am_agent_version

Версия агента для установки (latest или конкретная версия)

Нет

latest

am_agent_url

Ссылка для скачивания бинарного файла агента

Нет

dl.astralinux.ru

am_agent_url_token

Токен для аутентификации при скачивании агента по URL

Нет

""

am_agent_url_username

Имя пользователя для аутентификации при скачивании агента по URL

Нет

""

am_agent_url_password

Пароль для аутентификации при скачивании агента по URL

Нет

""

am_agent_environments

Список переменных окружения для запуска агента

Нет

[]

am_agent_reinstall

Включает полную переустановку агента с созданием бэкапа данных

Нет

false

am_agent_config

Конфигурация агента для модификации (переопределяет стандартные настройки)

Нет

{}

Примеры плейбуков

Минимальный

Минимальные данные для работы роли:

- name: Install astra-monitoring agent
  hosts: all
  gather_facts: true
  become: true
  roles:
    - role: "ansible-role-am-agent"
      vars:
        am_agent_upstream_address: https://astra-monitoring-server

Стандартный

В большинстве случаев будет использоваться такая версия плейбука. Устанавливается агент фиксированной версии 2.5.1 (если это не последняя версия, требуется доступ к dl.astralinux.ru). Для подключения к платформе используется токен. При таком запуске файл конфига не используется, адрес для поджключения вписывается в файл сервиса.

- name: Install astra-monitoring agent
  hosts: all
  gather_facts: true
  become: true
  roles:
    - role: "ansible-role-am-agent"
      vars:
        am_agent_upstream_address: https://astra-monitoring-server
        am_agent_upstream_token: secure-platform-token
        am_agent_version: 2.5.1

Установка с конфигом (управление целиком через ansible)

Часто встречающийся сценарий - использование подхода iac. В данном случае единственным источнкиом конфигурации системы является git репозиторий с конфигурациями. Ключевыми параметрами конфигурации в этом случае являются watcher.force_local и watcher.disable_force_local, подробнее про работу этих параметров можно прочитать в описании параметров.

При повторном выполнении плейбука агент примет состояние, которое заложено в его конфигурационный файл. Если были сделаны изменения в конфигурации агента на ui, все его настройки будут приведены к эталонным, описаным в плейбуке.

Данный плейбук имеет конфиг для:

  • сбора логов с использованием файлов конфигурации сбора syslog и audit

  • сбора метрик с haproxy установленного на этом хосте и отдающем метрики на :8404/metrics

  • установка и сбор метрик с экспортёров node_exporter и systemd_exporter

  • уровень логирования агента info и запись логов в формате json

- name: Install astra-monitoring agent
  hosts: all
  gather_facts: true
  become: true
  roles:
    - role: "ansible-role-am-agent"
      vars:
        am_agent_upstream_address: https://astra-monitoring-server
        am_agent_upstream_token: secure-platform-token
        am_agent_config:
          watcher:
            force_local: True
            disable_force_local: False
          logs:
            vector_config_names:
              - logs_syslog.yaml
              - logs_audit.yaml
          metrics:
            custom_targets:
              - name: haproxy
                target: "127.0.0.1:8404"
                metrics_path: /metrics
                scrape_interval: 30s
                labels:
                  group: default
                  hostname: "{{ ansible_hostname }}"
          exporters:
            exporters:
              - name: node_exporter
                start_type: args
                args: --log.format=json --web.listen-address=0.0.0.0:9101
                address: 127.0.0.1:9101
                labels:
                  group: default
                  hostname: "{{ ansible_hostname }}"
              - name: systemd_exporter
                start_type: am
                args: "-c data/exporters/configs/systemd_exporter.yaml"
                base:
                  address: 0.0.0.0:9750
                  metrics_path: /metrics
                  interval: 60s
                  logger:
                    level: info
                    file: data/exporters/logs/systemd_exporter.log
                    disable_console_log: true
                    go_metrics: false
                    proc_metrics: false
                config:
                  base:
                    address: 0.0.0.0:9750
                    metrics_path: /metrics
                    interval: 60s
                    logger:
                      level: info
                      file: data/exporters/logs/systemd_exporter.log
                      disable_console_log: true
                      go_metrics: false
                      proc_metrics: false
                  services:
                    - includes: .*\.service
                  general:
                    Interval: 30
                labels:
                  hostname: "{{ ansible_hostname }}"
                  group: default
          logger:
            level: info
            stderr: json

Установка с конфигом (управление через ui)

Основной сценарий использования - установка агента на хосты с определёнными настройками, после регистрации в платформе управление агентом происходит из платформы мониторинга.

Если агент уже зарегистрирован в системе, необходимо установить force_local: True, что вызовет повторное применение конфигурации агента.

Данный плейбук имеет конфиг для:

  • отправка метрик во второй сервер мониторинга для отказоустойчивости

  • установка и сбор метрик с экспортёров node_exporter и cadvisor_exporter

- name: Install astra-monitoring agent
  hosts: all
  gather_facts: true
  become: true
  roles:
    - role: "ansible-role-am-agent"
      vars:
        am_agent_upstream_address: https://astra-monitoring-server
        am_agent_upstream_token: secure-platform-token
        am_agent_config:
          watcher:
            force_local: False
            disable_force_local: True
          upstream:
            upstreams:
              - name: reserve-server
                address: https://astra-monitoring-reserve-server
                auth_token: secure-reserve-token
          exporters:
            exporters:
              - name: node_exporter
                start_type: args
                args: --log.format=json --web.listen-address=0.0.0.0:9101
                address: 127.0.0.1:9101
                labels:
                  group: default
                  hostname: "{{ ansible_hostname }}"
              - name: cadvisor_exporter
                start_type: args
                args: "--logtostderr --listen_ip=0.0.0.0 --port=9730"
                address: 127.0.0.1:9730
                labels:
                  group: default
                  hostname: "{{ ansible_hostname }}"

Проверка установки

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

shell
# Проверить статус службы
ansible all -i your_inventory_file.yml -b -a "systemctl status am-agent"

# Посмотреть логи агента
ansible all -i your_inventory_file.yml -b -a "journalctl -u am-agent -n 20"