> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axottle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bash, Ansible, файлы и переменные

> Скриптовые плейбуки: форматы, зависимости, входные файлы, окружение, ограничения и практические примеры.

Скриптовый шаг позволяет выполнять собственные работы на нодах: диагностику приложения, развёртывание, подготовку окружения или обслуживание. Telepúrte сохраняет скрипт в каталоге, фиксирует его в версии плейбука и показывает результат отдельно для каждой ноды.

## Форматы и среда выполнения

| Формат | Как выполняется | Что требуется на ноде |
| - | - | - |
| `.sh` | Bash-скрипт | `/bin/bash` и используемые команды |
| `.yml`, `.yaml` | Ansible-плейбук с локальным подключением к `localhost` | `ansible-playbook`, нужные коллекции и зависимости |

Ansible выполняется локально на каждой выбранной ноде. Список серверов задаётся в Telepúrte; не переносите в такой файл внешнюю SSH-инвентаризацию в расчёте на отдельный управляющий Ansible-сервер.

Скрипт работает в контексте агента и его системных ограничений. Проверьте пользователя процесса и доступные права: выбор скрипта в панели не выдаёт root или sudo автоматически. У импортированной ноды требуется совместимая версия Axottle Agent с поддержкой скриптов.

## Добавить материалы

В **Плейбуки и расписания** добавьте скрипт в каталог: загрузите файл или вставьте текст. Имя должно использовать латиницу, цифры, точку, дефис или подчёркивание и подходящее расширение. Скрипт — UTF-8 без нулевых символов.

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

Один файл каталога ограничен 1 МиБ. Входных файлов у шага может быть до восьми; суммарный объём скрипта и его входных файлов ограничен 2 МиБ. Имена входных файлов должны быть уникальными в рамках запуска.

## Пример Bash без изменения сервера

Сохраните как `inspect.sh`:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

printf 'Environment: %s\n' "${DEPLOY_ENV:-test}"
/usr/bin/uptime
if [[ -f "$TELEPURTE_FILES_DIR/app.conf" ]]; then
  sha256sum "$TELEPURTE_FILES_DIR/app.conf"
fi
```

Добавьте обычный файл `app.conf` и набор переменных с `DEPLOY_ENV=test`. Прикрепите их к шагу и выполните на одной ноде. Скрипт печатает метку окружения, uptime и контрольную сумму переданного файла. Он не устанавливает `app.conf` в `/etc`: такое размещение нужно явно написать в сценарии или сделать типизированным действием.

Входные файлы находятся в каталоге, путь к которому задаёт `TELEPURTE_FILES_DIR`. Рабочий каталог запуска временный; не рассчитывайте на файлы от предыдущего исполнения. После завершения временные материалы удаляются.

## Пример Ansible

Сохраните `inspect.yml`:

```yaml theme={null}
- name: Inspect the current node
  hosts: all
  connection: local
  gather_facts: false
  tasks:
    - name: Read uptime
      ansible.builtin.command: /usr/bin/uptime
      changed_when: false
```

На каждой выбранной машине должен быть установлен `ansible-playbook`. Если его нет, результат будет `ansible_unavailable`; Telepúrte не устанавливает Ansible автоматически в ходе этого шага. Коллекции, утилиты и права для более сложного плейбука также подготовьте заранее.

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

Создайте именованный набор и добавьте пары имя/значение. Имена должны быть уникальными; поддерживаются до 64 переменных и до 32 КиБ набора. Системные имена, влияющие на запуск интерпретатора, и префикс `LD_` запрещены. Не заменяйте `PATH`, `BASH_ENV` или `TELEPURTE_FILES_DIR`.

Значения передаются непосредственно в окружение процесса; `.env` на сервере не создаётся. Если приложение ожидает файл, добавьте его отдельно или явно создайте в скрипте с нужными правами.

Материалы хранятся зашифрованными. В выводе выполняется скрытие совпадающих значений окружения, но это не защита от всех способов вывода секрета: преобразованное, разбитое или закодированное значение может не совпасть. Не включайте `set -x` и не печатайте окружение целиком в сценариях с секретами.

## Срок и результат

Скриптовое исполнение ограничено 15 минутами. В результат входят код завершения, код ошибки и ограниченный объединённый stdout/stderr. Сохранённый вывод может обрезаться; интерфейс показывает соответствующий признак. Длинный полный журнал храните там, где его предусмотрело ваше приложение, и не считайте короткий результат Telepúrte полным логом развёртывания.

| Ошибка | Что проверить |
| - | - |
| `ansible_unavailable` | Установку Ansible и доступность бинарника агенту |
| `script_failed` | Код завершения, зависимости, параметры и вывод |
| `timeout` | Длительность и зависание шага; фактическое состояние перед повтором |
| Агент не поддерживает скрипты | Версию и состояние агента на конкретной ноде |
| `execution_uncertain` | Исполнилась ли работа до потери подтверждения |

Обычный запуск из интерфейса не включает автоматическую канарейку. Выбирайте сначала тестовую ноду; поэтапный rollout с порогом ошибок описан в [заданиях](https://docs.axottle.com/ru/telepurte/jobs.md).

## Проверка

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

## Откат

Остановите ещё не выданные действия в задании. Это не отменяет уже исполненный скрипт. Возвращайте конфигурации, версии и данные отдельным подготовленным сценарием; перед повтором после тайм-аута сначала проверьте, что уже изменилось.

Возможности автоматизации зависят от версии и локальной политики агента.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.