Shell Runner

Описание

runner-shell — раннер для выполнения shell-команд через платформу Unishift. Выполняет команды через /bin/sh -c, что позволяет использовать все возможности POSIX shell.

Возможности

• Выполнение произвольных shell-команд
• Поддержка пайпов, перенаправлений, логических операторов
• Подстановка переменных окружения из задач
• Стриминг stdout/stderr в реальном времени
• Обработка ошибок и таймаутов
• Сбор и загрузка артефактов (файлы/директории) в storage платформы

Конфигурация

Общие параметры runner-common

См. Общая документация.

Специфичные параметры

Shell-раннер не имеет специфичных параметров — используются только общие параметры runner-common.

Примеры конфигурации

YAML

url: "https://app.com/"
token: "your-token"
session_timeout: 10000
concurrency: 1
tags: "shell,linux"
description: "Shell command executor"

JSON

{
  "url": "https://app.com/",
  "token": "your-token",
  "session_timeout": 10000,
  "concurrency": 1
}

Переменные окружения

export URL="https://app.com/"
export TOKEN="your-token"
export CONCURRENCY=1
export TAGS="shell,linux"

Через ush

# интерактивный опрос url/token/… и запуск
ush install shell --start

# без вопросов — все параметры сразу
ush install shell --start --non-interactive \
  --set url=http://HOST:18090 \
  --set token=YOUR_TOKEN \
  --set concurrency=1 \
  --set tags=shell,linux

# изменить конфиг установленного раннера
ush config set shell-eedb1b0f concurrency 2
ush restart shell-eedb1b0f

Выполнение команд

Команды выполняются через /bin/sh -c, что поддерживает:

• Простые команды: ls -la
• Пайпы: ps aux | grep nginx
• Перенаправления: echo "text" > file.txt
• Логические операторы: cd /tmp && ls
• Подстановку команд: echo "Date: $(date)"
• Heredoc: cat << EOF > file.txt

Особенности работы команды cd

Каждая задача исполняется в отдельном subshell-процессе /bin/sh -c. В силу природы shell-процессов команда cd меняет текущую директорию только внутри своего процесса.

• Изоляция: Команда cd /srv/app, выполненная отдельной строкой или отдельной задачей, не меняет рабочую директорию раннера для следующих команд.
• Правильный подход: Для выполнения команд в целевом каталоге объединяйте переход и команду в одну цепочку через &&:

  cd /srv/app && ./deploy.sh

Примеры команд

# Список файлов
ls -la /var/log

# Мониторинг системы
df -h && free -m

# Обработка логов
grep "ERROR" /var/log/app.log | tail -100

# Создание резервной копии
tar -czf backup.tar.gz /path/to/dir

Переменные задач

Переменные из cmdReq.Variables передаются как переменные окружения в shell:

 Variables: [
   { name: "MY_VAR", value: "hello" },
   { name: "ENV", value: "production" }
 ]

Внутри команды доступны как $MY_VAR и $ENV.

Артефакты

Раннер поддерживает автоматический сбор и загрузку артефактов в storage платформы.

Переменные для артефактов

Переменная	Описание	Пример
ARTIFACT_DIR	Директория для сбора всех файлов (рекурсивно)	/tmp/output
ARTIFACT_FILES	Список glob-масок через запятую	report_*.csv,summary.json

Поведение

• Артефакты собираются только при успешном выполнении команды (код возврата 0)
• Файлы упаковываются в zip-архив и загружаются в storage
• После успешной загрузки временные файлы удаляются автоматически
• artifact_id возвращается в статусе задачи

Примеры

Сбор директории:

# В задаче: ARTIFACT_DIR="/tmp/output"
mkdir -p /tmp/output
python3 generate_report.py --output /tmp/output

Сбор файлов по маске:

# В задаче: ARTIFACT_FILES="result_*.csv,logs/*.log"
./process_data.sh

Комбинированный сбор:

# В задаче:
#   ARTIFACT_DIR="/tmp/build"
#   ARTIFACT_FILES="config.yaml,README.md"
make build DESTDIR=/tmp/build
cp config.yaml README.md /tmp/build/

Без артефактов:

# Если переменные ARTIFACT_DIR и ARTIFACT_FILES не заданы,
# артефакты не собираются
echo "Просто вывод в консоль"

Обработка ошибок

• Ненулевой код возврата → статус failed
• stdout возвращается в поле output
• stderr возвращается в поле error
• Таймаут контекста → сообщение "Command timed out"

Остановка

Корректно обрабатывает сигналы SIGINT и SIGTERM. Текущие команды получают контекст отмены.

Права доступа и безопасность

Команды выполняются от имени ОС-пользователя, под которым запущен процесс runner-shell.

Настройка прав доступа (Permission denied)

Если команда падает с ошибкой доступа к директориям (например, cd /srv/... или mkdir /srv/...: Permission denied), настройте права в зависимости от вашего окружения запуска:

1. Права на директорию хоста (Рекомендуется)

Выдайте пользователю раннера права на нужный каталог на сервере:

sudo chown -R <user>:<group> /srv/your-dir
sudo chmod -R 775 /srv/your-dir

2. Production: через ush CLI

Инстансы ush работают с правами пользователя, вызвавшего запуск.

• Для запуска под конкретным пользователем:

  sudo -u deploy ush start shell-<id>

3. Development / Local: через PM2

Процесс наследует права пользователя, запустившего PM2:

• Перезапустить процесс после изменения прав или прав пользователя:

  pm2 restart runner-shell

4. Container / Docker

Если раннер запущен в Docker-контейнере:

• Смонтируйте директорию хоста в volumes:

  volumes:
    - /srv/your-dir:/srv/your-dir

• Убедитесь, что UID пользователя контейнера имеет права на /srv/your-dir на хосте:

  sudo chown -R 1000:1000 /srv/your-dir

5. Linux Systemd Service

Если раннер оформлен как системный сервис, укажите User и Group в /etc/systemd/system/runner-shell.service:

[Unit]
Description=Unishift Shell Runner
After=network.target

[Service]
Type=simple
User=deploy
Group=deploy
WorkingDirectory=/opt/runner-shell
ExecStart=/opt/runner-shell/runner-shell -config config.yaml
Restart=always

[Install]
WantedBy=multi-user.target

Примените настройки: sudo systemctl daemon-reload && sudo systemctl restart runner-shell.

6. Использование sudo без пароля

Если задаче требуются права root, добавьте правило в /etc/sudoers (visudo):

<runner-user> ALL=(ALL) NOPASSWD: /bin/mkdir, /bin/cp

И вызовите команду с sudo: sudo mkdir -p /srv/dir.