Survey-переменные

Survey-переменные — это пользовательские поля ввода, которые можно добавить в шаблоны задач для получения данных от пользователя при запуске задач. Вместо того чтобы жёстко прописывать значения в playbook или скриптах, вы можете определить пользовательские переменные, значения которых запрашиваются у пользователей во время запуска.

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

• Запуска одного и того же шаблона с разными параметрами (например, значениями конфигурации)
• Приёма динамических данных через вызовы API
• Передачи пользовательских параметров в запланированных задачах
• Запуска задач из интеграций с данными, извлечёнными из webhook

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

Важно понимать разницу между survey-переменными и prompts:

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

Survey-переменные — это гибкие пользовательские поля, которые вы определяете сами, а prompts — встроенные опции, специфичные для каждого типа шаблона (например, флаги --limit или --tags в Ansible).

Добавление survey-переменных в шаблон

Survey-переменные настраиваются в настройках шаблона:

1. Перейдите в Шаблоны задач и выберите ваш шаблон
2. Перейдите в раздел Survey Variables в настройках шаблона
3. Нажмите Add Survey Variable
4. Настройте переменную:
   • Name: имя переменной (используется в вашем коде)
   • Title: отображаемая подпись в форме
   • Type: выберите тип поля
   • Pass variable as: extra-переменная (по умолчанию) или переменная окружения
   • Default value: необязательное предзаполненное значение, отображаемое при открытии формы задачи
   • Required: должно ли поле быть обязательно заполнено
5. Сохраните шаблон

Когда пользователи запускают задачу из этого шаблона, они видят форму с вашими пользовательскими survey-переменными.

Типы переменных

Survey-переменные поддерживают шесть типов:

String

Текстовое поле ввода для строковых значений.

Сценарии использования: названия окружений, имена веток, имена хостов, пути к файлам

Пример: переменная с именем environment предлагает пользователям ввести «production», «staging» или «development»

Integer

Числовое поле ввода для целочисленных значений.

Сценарии использования: номера портов, количество повторных попыток, таймауты, лимиты ресурсов

Пример: переменная с именем timeout_seconds предлагает пользователям ввести «300» или «600»

Text

Многострочное текстовое поле для длинных строковых значений.

Сценарии использования: сообщения commit, фрагменты JSON, произвольные заметки, многострочная конфигурация

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

Enum (единичный выбор)

Выпадающий список, в котором пользователь выбирает ровно один вариант из предопределённого списка.

Сценарии использования: тип окружения, стратегия развёртывания, варианты вида «да/нет»

Пример: переменная с именем deployment_type с вариантами: «rolling», «blue-green», «canary»

При создании enum-переменной добавьте каждый вариант с отображаемой подписью и значением в редакторе переменной.

Select (множественный выбор)

Выпадающий список, в котором пользователь может выбрать один или несколько вариантов из предопределённого списка. Выбранные значения передаются как JSON-массив (например, ["staging","production"]), а не как одна строка.

Сценарии использования: целевые регионы, feature flags, несколько групп хостов, списки тегов

Пример: переменная с именем target_regions с вариантами us-east-1, eu-west-1, ap-southeast-1

Ограничения:

• Значения по умолчанию должны выбираться из списка вариантов и могут включать несколько значений
• В шаблонах Bash, PowerShell и Python разбирайте JSON-массив из аргумента или значения переменной окружения (см. примеры ниже)

Secret

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

Сценарии использования: ключи API, пароли, token'ы, конфиденциальная конфигурация

Пример: переменная с именем api_token, введённое значение которой отображается точками в целях безопасности

В шаблонах Ansible значение попадает в playbook в файле, зашифрованном с помощью Ansible Vault, а не через командную строку.

Значения по умолчанию

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

• String, integer, text, secret: одно значение по умолчанию
• Enum: один вариант из списка
• Select: один или несколько вариантов из списка

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

Способ передачи переменной (цель)

Каждая survey-переменная может быть передана одним из двух способов:

Настройка	Поведение
Extra variable (по умолчанию)	Передаётся способом, специфичным для приложения: Ansible --extra-vars, Terraform -var или аргументы CLI вида name=value для shell-приложений
Environment variable	Задаётся как переменная окружения процесса, имя которой совпадает с именем survey-переменной

Используйте Environment variable, когда ваш скрипт или инструмент читает значения из окружения, а не из флагов CLI. Для переменных Terraform, которые должны следовать соглашению TF_VAR_, назовите survey-переменную TF_VAR_instance_type и установите в качестве цели переменную окружения.

Переменные с целью «переменная окружения» не дублируются в extra-vars, -var или аргументах CLI. Каждое значение передаётся ровно один раз.

Как survey-переменные передаются задачам

Survey-переменные передаются по-разному в зависимости от типа шаблона и настройки Pass variable as.

Значения множественного выбора (тип select) — это массивы в формате JSON при любом способе передачи (JSON extra-vars, -var, аргументы CLI и переменные окружения). Выбор вариантов 1 и 2 превращается в ["1","2"], а не в строку, разделённую пробелами.

Шаблоны Ansible

Survey-переменные передаются как extra-переменные Ansible. Semaphore записывает их во временный YAML-файл и передаёт его с помощью --extra-vars @file; файл доступен для чтения только пользователю задачи и удаляется после её завершения.

Пример: если вы определили survey-переменную с именем app_version:

---
- hosts: webservers
  tasks:
    - name: Deploy application
      command: deploy.sh {{ app_version }}

При запуске задачи пользователь вводит «2.5.0» в форме survey, и Ansible получает это как:

app_version: "2.5.0"

Каждое значение записывается как строка в кавычках, поэтому ответ, который выглядит как число, логическое значение или дата, например 2026.08 или 00123, остаётся в playbook строкой. Значение, содержащее разделитель Jinja2 ({{ … }}, {% … %} или {# … #}), дополнительно помечается тегом !unsafe: Ansible использует его буквально и никогда не вычисляет выражение Jinja2, введённое в поле survey, сохранённое в группе переменных или переданное из рабочего процесса. Survey-переменная типа secret попадает во второй файл, зашифрованный с помощью Ansible Vault одноразовым паролем, который Semaphore вводит в ответ на запрос vault, поэтому секреты никогда не появляются в командной строке и не хранятся на диске в открытом виде.

Шаблоны Terraform/OpenTofu

Survey-переменные передаются как переменные Terraform с помощью флага -var.

Пример: если вы определили survey-переменную с именем instance_count:

variable "instance_count" {
  type        = number
  description = "Number of instances to create"
}

resource "aws_instance" "web" {
  count         = var.instance_count
  instance_type = "t2.micro"
  # ... other configuration
}

При запуске задачи пользователь вводит «3» в форме survey, и Terraform получает это как:

terraform apply -var="instance_count=3"

Шаблоны Shell/Bash

Survey-переменные передаются скрипту Bash как аргументы командной строки:

/bin/bash your_script.sh var1=val1 var2=val2 ... varN=valN

Для разбора аргументов в массив внутри скрипта можно использовать следующий код:

declare -A args
for arg in "$@"; do
  KEY="${arg%%=*}"
  VALUE="${arg#*=}"
  args["$KEY"]="$VALUE"
done
 
echo "ARG1: ${args[ARG1]}"
echo "ARG2: ${args[ARG2]}"

Для переменных с множественным выбором значение представляет собой строку с JSON-массивом. Разберите её с помощью jq (убедитесь, что jq доступен в образе исполнителя):

regions_json='["us-east-1","eu-west-1"]'
regions=$(echo "$regions_json" | jq -r '.[]')
for region in $regions; do
  echo "Deploying to $region"
done

Шаблоны PowerShell

Survey-переменные передаются выполняемому скрипту PowerShell как аргументы командной строки:

pwsh your_script.sh var1=val1 var2=val2 ... varN=valN

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

$parsed = @{}

foreach ($a in $args) {
    if ($a -match "^([^=]+)=(.*)$") {
        $key = $matches[1]
        $val = $matches[2]
        $parsed[$key] = $val
    }
}


Write-Host "Parsed arguments:"

write-host $parsed['env1']
write-host $parsed.env1

Для переменных с множественным выбором разберите JSON-массив из значения аргумента:

$regions = $parsed['target_regions'] | ConvertFrom-Json
foreach ($region in $regions) {
    Write-Host "Deploying to $region"
}

Шаблоны Python

Survey-переменные передаются выполняемому скрипту Python как аргументы командной строки:

python3 your_script.sh var1=val1 var2=val2 ... varN=valN

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

import sys

parsed = {}

for arg in sys.argv[1:]:
    if "=" in arg:
        key, val = arg.split("=", 1)
        parsed[key] = val

print("Parsed arguments:")
print(parsed.get("env1"))
print(parsed["env1"] if "env1" in parsed else None)

Для переменных с множественным выбором разберите JSON-массив:

import json

regions = json.loads(parsed["target_regions"])
for region in regions:
    print(f"Deploying to {region}")

Использование survey-переменных

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

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

1. Нажмите Run в шаблоне
2. Появится форма со всеми определёнными survey-переменными
3. Заполните значения каждого поля
4. Нажмите Run Task

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

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

Расписания могут содержать значения survey-переменных, чтобы запускать один и тот же шаблон с разными параметрами по разным расписаниям.

Настройка:

1. Добавьте survey-переменные в шаблон
2. Создайте расписание для этого шаблона
3. В настройках расписания задайте значения survey-переменных
4. Каждый запланированный запуск использует эти предопределённые значения

Пример сценария: запуск playbook резервного копирования с разными политиками хранения:

• Ежедневное расписание с retention_days=7
• Еженедельное расписание с retention_days=30
• Ежемесячное расписание с retention_days=365

Подробнее см. в документации по расписаниям.

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

Интеграции могут извлекать значения из входящих webhooks и сопоставлять их с survey-переменными.

Настройка:

1. Добавьте survey-переменные в шаблон
2. Создайте интеграцию, которая запускает этот шаблон
3. Настройте извлечение значений из тела webhook
4. Сопоставьте извлечённые значения с вашими survey-переменными

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

• Извлеките тег релиза из тела webhook
• Сопоставьте его с survey-переменной с именем release_version
• Playbook развёртывания получает номер версии

Подробнее см. в документации по интеграциям.

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

Используйте понятные имена

Выбирайте для survey-переменных ясные, говорящие имена, отражающие их назначение:

• ✅ Хорошо: target_environment, app_version, backup_retention_days
• ❌ Плохо: env, ver, days

Задавайте информативные заголовки

Заголовок отображается в форме, поэтому сделайте его понятным для пользователя:

• Имя переменной: db_host
• Заголовок: «Имя хоста или IP-адрес базы данных»

Используйте enum или select для известных вариантов

Когда пользователи должны выбирать из ограниченного набора вариантов, используйте enum или select вместо string:

• ✅ Enum для ровно одного выбора: production, staging или development
• ✅ Select, когда допустимо несколько вариантов: несколько регионов или feature flags
• ❌ Строковое поле с примечанием «введите production или staging»

Осознанно используйте цель «переменная окружения»

Предпочитайте передачу через extra-переменные по умолчанию, если только ваш playbook, скрипт или инструмент явно не читает значения из окружения процесса. Называйте переменные с целью «переменная окружения» ровно так, как ожидает целевой инструмент (например, TF_VAR_region).

Правильно отмечайте обязательные поля

Отмечайте поля как обязательные, только если они действительно необходимы. Для необязательных полей предусмотрите разумные значения по умолчанию в ваших playbook.

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

Не считайте, что значения survey-переменных всегда корректны. Добавьте логику проверки в playbook или скрипты:

- name: Validate environment variable
  assert:
    that:
      - environment in ['production', 'staging', 'development']
    fail_msg: "Invalid environment: {{ environment }}"

Используйте secret для конфиденциальных данных

Всегда используйте тип secret для конфиденциальных значений, таких как ключи API, пароли или token'ы. Это гарантирует, что значения будут скрыты в интерфейсе и журналах.

Сочетайте с группами переменных

Survey-переменные хорошо сочетаются с группами переменных:

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

Пример:

• Группа переменных: параметры подключения к базе данных, конечные точки API
• Survey-переменные: окружение развёртывания, номер версии, feature flags

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

Развёртывания для конкретных окружений

Создайте survey-переменные:

• environment: enum с вариантами «production, staging, development»
• app_version: string для версии, которую нужно развернуть
• enable_debug: enum с вариантами «true, false»

Операции с базами данных

Создайте survey-переменные:

• db_name: string для имени базы данных
• backup_retention_days: integer для политики хранения
• maintenance_window: string для временного окна

Развёртывание инфраструктуры

Создайте survey-переменные:

• instance_count: integer для количества экземпляров
• instance_type: enum с вариантами «t2.micro, t2.small, t2.medium»
• region: enum с регионами AWS

CI/CD pipelines

Создайте survey-переменные:

• git_branch: string для ветки, которую нужно собрать
• build_type: enum с вариантами «debug, release»
• run_tests: enum с вариантами «true, false»

Отличия от групп переменных

Характеристика	Survey-переменные	Группы переменных
Назначение	Ввод данных при каждом запуске задачи	Переиспользуемая статическая конфигурация
Когда определяются	В момент выполнения задачи	Заранее настраиваются в проекте
Сценарий использования	Значения, меняющиеся от запуска к запуску	Общие настройки для нескольких задач
Формат	Отдельные типизированные поля	Формат JSON с вложенными объектами
Область действия	Один запуск задачи	Несколько шаблонов/inventory
Безопасность	Тип secret скрывает конфиденциальные значения	Вкладка Secrets для конфиденциальных данных

Используйте survey-переменные, когда вам нужна гибкость во время запуска, и группы переменных, когда нужна единая конфигурация для нескольких выполнений задач.