salt-api (REST)

salt-api — демон, предоставляющий HTTP-доступ к мастеру Salt через модули netapi. Основной модуль — rest_cherrypy: REST-интерфейс, через который внешние системы могут выполнять те же действия, что и администратор в консоли мастера, — запускать execution-модули на миньонах, вызывать runner'ы, читать результаты джобов и слушать шину событий. Это штатный способ интеграции Salt с внешним миром: CI-пайплайн запускает выкатку HTTP-запросом, портал самообслуживания перезапускает сервис по кнопке, система мониторинга шлёт вебхук, на который реагирует reactor. Ключевой элемент безопасности — обязательная внешняя аутентификация (eauth): API не работает без настроенной проверки пользователей и явного списка разрешённых функций.

Как это работает

Модуль включается секцией в конфигурации мастера: в rest_cherrypy задаются как минимум port (обычно 8000) и SSL-сертификат, после чего запускается сервис salt-api. Доступ управляется через external_auth: например, бэкенд pam проверяет логин-пароль по системным пользователям, а список рядом с именем пользователя перечисляет, какие функции и на каких миньонах ему разрешены. Клиент сначала отправляет POST /login с логином, паролем и названием eauth-бэкенда — в ответ получает токен, который передаёт в заголовке в последующих запросах. Основной запрос — POST / с полями client (local — выполнить на миньонах, runner — на мастере, local_async — асинхронно), tgt, fun и аргументами; это прямой аналог команды salt. Дополнительные точки входа: GET /jobs — результаты джобов, GET /events — поток событий шины в реальном времени (SSE), POST /hook — приём вебхуков от внешних систем с трансляцией их в события, на которые подписывается reactor.

Когда применять

salt-api нужен везде, где Salt должен вызываться не человеком с консоли мастера. Типовые сценарии: деплой из CI (пайплайн собрал артефакт и дёргает state.apply на группе серверов), самообслуживание (разработчикам — кнопка «перезапустить сервис» без SSH-доступа), ChatOps, приём вебхуков от Git-платформы или мониторинга с реакцией через reactor. Альтернатива — пускать всех на мастер по SSH и давать sudo на команду salt — проигрывает по управляемости: eauth с ACL позволяет выдать каждому потребителю ровно тот набор функций, который ему нужен, и не больше.

Типичные ошибки

Худшая — поднять API без SSL или с eauth-правилом .*, разрешающим все функции: доступ к cmd.run на всех миньонах — это удалённое выполнение кода на всём парке, и такой эндпоинт нельзя оставлять широким. Выдавайте по списку конкретные функции и цели. Вторая — открыть порт API в интернет без крайней необходимости: место этого сервиса — во внутренней сети или за VPN. Третья — вебхуки: точку /hook для внешних систем нередко открывают без токена (это допускает опция webhook_disable_auth), забывая, что тогда любой, кто дотянется до порта, может генерировать события, — валидируйте подпись и содержимое payload в reactor'е. И не используйте синхронный client: local для долгих операций из CI — HTTP-запрос упрётся в таймауты; берите local_async и опрашивайте /jobs/<jid>.

Связанные понятия

• Внешняя аутентификация (eauth)
• События и Reactor
• Шина событий
• Runners и salt-run
• Salt в CI/CD