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

Prompts

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

Эта функция позволяет:

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

Prompts и Survey-переменные​

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

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

Prompts для Ansible​

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

Limit​

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

Эквивалент в CLI: ansible-playbook playbook.yml --limit webservers

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

  • Запуск playbook на подмножестве хостов inventory
  • Выбор конкретных серверов для развёртывания
  • Проверка изменений на одном хосте перед развёртыванием на всех

Пример:

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

Tags​

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

Эквивалент в CLI: 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

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

Skip Tags​

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

Эквивалент в CLI: ansible-playbook playbook.yml --skip-tags testing,debug

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

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

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

Включение prompts для Ansible​

Чтобы включить prompts для Ansible:

  1. Перейдите в Шаблоны задач и выберите ваш шаблон Ansible
  2. Найдите раздел Ansible Prompts в настройках шаблона
  3. Отметьте флажки нужных prompts:
    • ☐ Limit - включить флаг --limit
    • ☐ Tags - включить флаг --tags
    • ☐ Skip Tags - включить флаг --skip-tags
  4. Сохраните шаблон

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

Prompts для Terraform/OpenTofu​

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

Выбор workspace​

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

Эквивалент в CLI: terraform workspace select staging

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

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

Настройка:

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

Подробная настройка описана в разделе Workspaces Terraform.

Флаг Destroy​

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

Эквивалент в CLI: terraform apply -destroy

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

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

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

Флаг Migrate State​

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

Эквивалент в CLI: terraform init -migrate-state

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

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

Включение prompts для Terraform​

Prompts для Terraform доступны в настройках шаблона:

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

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

Prompts для Bash, PowerShell и Python​

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

Доступные prompts:

  • CLI args
  • Branch

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

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

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

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

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

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

Вызовы API​

Чтобы передать значения prompts через 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

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

Запланированные задачи​

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

Пример: Расписание с prompts для Ansible

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

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

Интеграции и webhooks​

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

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

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

Настройка webhooks описана в разделе Интеграции.

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

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

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

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

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

Используйте prompts для специфичных для инструмента опций CLI, а Survey-переменные — для пользовательских параметров:

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

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

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

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

## 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 с помощью prompt Limit:

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

Проверяйте сочетания prompts​

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

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

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

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

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

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

Выборочное выполнение с помощью Tags​

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

Утром: tags: "deploy" - развёртывание новой версии Днём: tags: "config" - обновление конфигурации Вечером: tags: "restart" - перезапуск служб с новой конфигурацией

Управление окружениями с помощью workspaces​

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

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

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

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

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

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

Значения prompts игнорируются​

Проблема: Значения prompts передаются, но не применяются

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

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

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

Решение:

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

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

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

Решение:

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

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

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

Решение:

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