Перейти к основному содержимому

Подсказки

Подсказки (prompts) — это предопределённые флаги и опции, специфичные для каждого типа шаблона, которые можно включить, чтобы разрешить настройку во время запуска. В отличие от переменных опроса, которые вы создаёте сами, подсказки — это встроенные опции, соответствующие конкретным флагам командной строки для Ansible, Terraform и других инструментов.

Эта возможность позволяет:

  • Переопределять значения шаблона по умолчанию во время запуска
  • Нацеливаться на конкретные хосты или ресурсы
  • Управлять поведением выполнения через флаги командной строки
  • Передавать опции запуска через вызовы API или расписания

Подсказки и переменные опроса​

ВозможностьПодсказкиПеременные опроса
ОпределениеПредопределённые опции конкретного шаблонаПользовательские поля, которые вы создаёте
ПримерыAnsible: --limit, --tags
Terraform: рабочие пространства, -destroy		Имя окружения, номер версии, произвольные параметры
НастройкаВключаются флажками в шаблонеДобавляются в настройках шаблона с именем и типом
Передаются какВстроенные флаги командной строкиAnsible: --extra-vars
Terraform: -var

Подсказки — это стандартизованные опции, встроенные в Semaphore для конкретных инструментов, а переменные опроса — это гибкие пользовательские поля, которые вы определяете сами.

Подсказки Ansible​

Для шаблонов playbook Ansible можно включить подсказки для следующих опций командной строки:

Limit​

Включите подсказку --limit, чтобы указывать, на какие хосты нацеливаться при запуске playbook.

Эквивалент в командной строке: ansible-playbook playbook.yml --limit webservers

Сценарии использования:

  • Запуск playbook на части хостов инвентаря
  • Нацеливание на конкретные серверы для развёртывания
  • Проверка изменений на одном хосте перед массовым применением

Пример:

  • В вашем инвентаре 50 веб-серверов
  • Включите подсказку Limit
  • При запуске задачи укажите web-01.example.com, чтобы обработать только этот сервер
  • Либо укажите webservers:&production, чтобы обработать production-веб-серверы

Tags​

Включите подсказку --tags, чтобы выполнять только задачи с определёнными тегами.

Эквивалент в командной строке: ansible-playbook playbook.yml --tags deploy,restart

Сценарии использования:

  • Выполнение только отдельных частей playbook
  • Запуск шагов развёртывания без задач настройки
  • Быстрый перезапуск сервисов без выполнения всего playbook

Пример:

---
- hosts: all
  tasks:
    - name: Install packages
      apt:
        name: nginx
      tags: install

    - name: Deploy application
      copy:
        src: app.tar.gz
        dest: /opt/app/
      tags: deploy

    - name: Restart service
      service:
        name: nginx
        state: restarted
      tags: restart

Включите подсказку Tags и введите deploy,restart, чтобы пропустить шаг установки.

Skip Tags​

Включите подсказку --skip-tags, чтобы пропускать задачи с определёнными тегами.

Эквивалент в командной строке: ansible-playbook playbook.yml --skip-tags testing,debug

Сценарии использования:

  • Пропуск необязательных задач в production
  • Исключение отладочных и тестовых задач
  • Обход длительных задач, когда они не нужны

Пример: используя playbook выше, включите Skip Tags и введите install, чтобы пропустить установку пакетов и выполнить только развёртывание и перезапуск.

Skip Galaxy install​

Включите подсказку, чтобы пользователь мог пропустить шаг ansible-galaxy install для ролей и коллекций при запуске задачи.

Сценарии использования:

  • Зависимости уже установлены в образе раннера
  • Экономия времени при повторных запусках, когда requirements.yml не менялся

Force Galaxy install​

Включите подсказку, чтобы пользователь мог принудительно выполнить ansible-galaxy install --force для каждого файла зависимостей, игнорируя контрольную сумму requirements, которую Semaphore хранит между запусками.

Эквивалент в командной строке: ansible-galaxy role install -r requirements.yml --force

Сценарии использования:

  • Файл зависимостей ссылается на ветку, а не на фиксированную версию, и нужен последний коммит
  • Предыдущая установка оставила роли или коллекции в некорректном состоянии
  • Проверка работы playbook с чистым набором зависимостей

О том, как работают значения по умолчанию на уровне шаблона, см. Зависимости Galaxy.

Включение подсказок Ansible​

Чтобы включить подсказки Ansible:

  1. Перейдите в Task Templates и выберите свой шаблон Ansible
  2. Найдите раздел Ansible Prompts в настройках шаблона
  3. Отметьте флажки для нужных подсказок:
    • ☐ Limit — включает флаг --limit
    • ☐ Tags — включает флаг --tags
    • ☐ Skip Tags — включает флаг --skip-tags
    • ☐ Debug — включает выбор уровня подробности (-v)
    • ☐ Skip Galaxy install — разрешает пропуск ansible-galaxy install
    • ☐ Force Galaxy install — разрешает принудительный ansible-galaxy install --force
  4. Сохраните шаблон

После включения эти поля появляются в форме запуска задачи, в запросах API и в настройках расписаний.

Подсказки Terraform/OpenTofu​

Для шаблонов Terraform и OpenTofu Semaphore предоставляет несколько встроенных подсказок:

Выбор рабочего пространства​

Выбор рабочего пространства Terraform, которое будет использовано при выполнении задачи.

Эквивалент в командной строке: terraform workspace select staging

Сценарии использования:

  • Управление несколькими окружениями (dev, staging, production)
  • Раздельные файлы состояния для разных конфигураций
  • Изолированная проверка изменений инфраструктуры

Настройка:

  1. Создайте рабочие пространства на вкладке Workspaces шаблона
  2. Селектор рабочего пространства автоматически появится в форме задачи
  3. При запуске задачи пользователи выбирают нужное рабочее пространство

Подробнее о настройке см. Рабочие пространства Terraform.

Флаг Destroy​

Включите флаг -destroy, чтобы удалить инфраструктуру.

Эквивалент в командной строке: terraform apply -destroy

Сценарии использования:

  • Очистка временных тестовых окружений
  • Вывод инфраструктуры из эксплуатации
  • Удаление отдельных ресурсов

Важно: это разрушающая операция. Используйте её осторожно и рассмотрите возможность требовать подтверждения в своих процессах.

Флаг Migrate State​

Включите флаг -migrate-state при изменении конфигурации backend.

Эквивалент в командной строке: terraform init -migrate-state

Сценарии использования:

  • Перенос состояния в другой backend
  • Миграция между хранилищами
  • Обновление конфигурации backend

Включение подсказок Terraform​

Подсказки Terraform доступны в настройках шаблона:

  1. Перейдите в Task Templates и выберите свой шаблон Terraform
  2. Настройте доступные подсказки в настройках шаблона:
    • Выбор рабочего пространства (включается автоматически, если рабочие пространства настроены)
    • Опция флага destroy
    • Опция migrate state
  3. Сохраните шаблон

Форма задачи отображает эти опции при запуске задач Terraform.

Подсказки Bash, PowerShell и Python​

Для шаблонов Bash, PowerShell и Python подсказок немного, поскольку основная настройка выполняется через переменные опроса.

Доступны следующие подсказки:

  • CLI args
  • Branch

Для передачи параметров в скрипты этим типам шаблонов больше подходят пользовательские переменные опроса.

Использование подсказок​

Ручной запуск задачи​

При запуске задачи из шаблона с включёнными подсказками:

  1. Нажмите Run на шаблоне
  2. Появится форма с полями включённых подсказок
  3. Заполните значения нужных подсказок (необязательные поля можно оставить пустыми)
  4. Нажмите Run Task

Задача выполнится с указанными значениями подсказок, переданными как флаги командной строки.

Вызовы API​

Чтобы передать значения подсказок через API, включите их в тело запроса:

Пример для Ansible:

curl -XPOST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "template_id": 123,
    "limit": "webservers",
    "tags": "deploy,restart",
    "skip_tags": "testing"
  }' \
  https://your-semaphore.com/api/project/1/tasks

Важно: чтобы значения принимались, соответствующие подсказки должны быть включены в шаблоне. Если передать значения подсказок через API, не включив их, эти значения будут проигнорированы.

Задачи по расписанию​

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

Пример: расписание с подсказками Ansible

  • Ежедневное расписание развёртывания с limit: "production" и tags: "deploy"
  • Еженедельное расписание обслуживания с tags: "updates,cleanup"

Задайте значения подсказок в настройках расписания, чтобы каждый запуск по расписанию использовал указанные опции.

Интеграции и вебхуки​

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

Пример: вебхук GitHub запускает развёртывание

  • Извлеките имя ветки из вебхука
  • Сопоставьте его с подсказкой Limit, чтобы нацелиться на нужное окружение
  • Разворачивайте только на серверы, соответствующие окружению ветки

О настройке вебхуков см. Интеграции.

Рекомендации​

Включайте только необходимые подсказки​

Каждая включённая подсказка добавляет поле в форму задачи. Включайте только те подсказки, которые пользователям действительно нужно настраивать.

✅ Хорошо: включить Limit для команд эксплуатации, которым нужно нацеливаться на конкретные хосты ❌ Плохо: включить все подсказки «на всякий случай»

Сочетайте с переменными опроса​

Используйте подсказки для опций командной строки конкретных инструментов, а переменные опроса — для собственных параметров:

Пример шаблона Ansible:

  • Подсказки: Limit (на какие хосты), Tags (какие задачи)
  • Переменные опроса: app_version (какая версия), enable_rollback (собственная логика)

Документируйте использование API​

Если шаблоны запускаются через API, задокументируйте, какие подсказки доступны и в каком формате:

## API Usage

Enabled prompts:
- `limit`: Host pattern (optional)
- `tags`: Comma-separated tag list (optional)

Example:
POST /api/project/1/tasks
{
  "template_id": 123,
  "limit": "webservers:&production",
  "tags": "deploy"
}

Используйте Limit для безопасного тестирования​

Всегда проверяйте потенциально разрушающие playbook сначала с подсказкой Limit:

  1. Включите подсказку Limit в шаблоне
  2. Первый запуск: укажите limit: "test-server-01", чтобы проверить на одном хосте
  3. Убедитесь в успешности
  4. Второй запуск: укажите limit: "production", чтобы применить ко всем хостам

Проверяйте сочетания подсказок​

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

  • Использование --tags deploy вместе с --skip-tags deploy конфликтует
  • Одновременное указание рабочего пространства и флага destroy требует особой осторожности

Типичные сценарии использования​

Постепенное развёртывание с Limit​

Разворачивайте в production постепенно, используя Limit в Ansible:

  1. Запуск 1: limit: "web-01.example.com" — развёртывание на один сервер
  2. Наблюдайте за проблемами
  3. Запуск 2: limit: "webservers:&canary" — развёртывание на канареечные серверы
  4. Проверьте метрики
  5. Запуск 3: limit: "webservers:&production" — полное развёртывание

Выборочное выполнение с Tags​

Используйте Tags для выполнения только отдельных частей playbook:

Утро: tags: "deploy" — развернуть новую версию День: tags: "config" — обновить конфигурацию Вечер: tags: "restart" — перезапустить сервисы с новой конфигурацией

Управление окружениями через рабочие пространства​

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

  • Development: выберите рабочее пространство dev — более дешёвые ресурсы, быстрые итерации
  • Staging: выберите рабочее пространство staging — приближённое к production для тестирования
  • Production: выберите рабочее пространство prod — полная production-инфраструктура

Очистка с помощью Destroy​

Используйте destroy в Terraform для временной инфраструктуры:

  1. Создайте тестовое окружение: запуск с рабочим пространством test-branch-123
  2. Выполните интеграционные тесты
  3. Очистите: запуск с включённым флагом destroy и рабочим пространством test-branch-123

Устранение неполадок​

Значения подсказок игнорируются​

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

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

Невозможно указать limit​

Проблема: поле Limit не появляется в форме задачи

Решение:

  1. Откройте шаблон на редактирование
  2. Найдите раздел «Ansible Prompts»
  3. Отметьте флажок «Limit»
  4. Сохраните шаблон

Вызовы API со значениями подсказок завершаются ошибкой​

Проблема: запросы API со значениями подсказок возвращают ошибки

Решение:

  1. Убедитесь, что подсказки включены в шаблоне
  2. Проверьте форматирование JSON в теле запроса
  3. Проверьте, что имена полей совпадают в точности (limit, а не host_limit)

Теги не фильтруют задачи​

Проблема: вы указываете теги, но выполняются все задачи

Решение:

  1. Убедитесь, что у задач в playbook действительно заданы теги
  2. Проверьте опечатки в именах тегов
  3. Убедитесь, что теги разделены запятыми без пробелов: deploy,restart, а не deploy, restart