TrueNAS SCALE REST API 2026: Полное руководство по автоматизации для DevOps

REST API TrueNAS SCALE — это ключевой инструмент для интеграции вашего хранилища в современные DevOps-практики. Вместо ручного управления через веб-интерфейс вы можете программно создавать пулы ZFS, настраивать пользователей, управлять сетевыми шарами и контролировать службы. Это руководство предоставляет готовые, проверенные на практике скрипты на Python и команды cURL для немедленного внедрения, а также безопасные паттерны аутентификации, которые защитят вашу инфраструктуру от несанкционированного доступа. Вы научитесь встраивать TrueNAS в CI/CD-пайплайны, системы мониторинга Prometheus и оркестраторы, экономя часы рутинной работы и снижая риск человеческой ошибки.

Безопасный старт: аутентификация и первые запросы к API TrueNAS SCALE 2026

Безопасность сетевых протоколов — основа любой автоматизации. Как показал опыт устранения критических уязвимостей в сетевом взаимодействии Project Zomboid v41.78.19, пренебрежение защитой API может привести к серьезным рискам. Работа с TrueNAS SCALE API начинается с безопасной аутентификации.

В TrueNAS SCALE 2026 для доступа к API используется токен (API Key). Сгенерировать его можно в веб-интерфейсе: Система → API-ключи → Добавить. При создании задайте срок действия, ограничения по IP-адресам и минимально необходимые права (например, только на чтение для скриптов мониторинга).

Где и как безопасно хранить токен доступа

Хранение токена в открытом виде в скрипте — грубая ошибка. Рассмотрим безопасные методы:

• Переменные окружения: Самый простой и распространенный способ, используемый в CI/CD (GitLab CI, Jenkins, GitHub Actions).
• Файлы с ограниченными правами: Например, файл ~/.truenas_token с правами 600 (только для владельца).
• Секреты в оркестраторах: Kubernetes Secrets, HashiCorp Vault.

Практический пример использования файла .env, который нужно добавить в .gitignore:

# .env файл
TRUENAS_API_TOKEN="your_super_secret_token_here"
TRUENAS_HOST="https://192.168.1.100"

Функция на Python для безопасного чтения токена из переменных окружения:

import os
import requests
from dotenv import load_dotenv  # pip install python-dotenv

load_dotenv()  # Загружает переменные из .env файла

TRUENAS_HOST = os.getenv('TRUENAS_HOST')
TRUENAS_API_TOKEN = os.getenv('TRUENAS_API_TOKEN')

headers = {
    'Authorization': f'Bearer {TRUENAS_API_TOKEN}',
    'Content-Type': 'application/json'
}

def make_api_call(endpoint, method='GET', data=None):
    url = f"{TRUENAS_HOST}/api/v2.0/{endpoint}"
    response = requests.request(method, url, headers=headers, json=data, verify=False)  # Внимание: verify=False только для тестов с самоподписанными сертификатами!
    response.raise_for_status()  # Вызовет исключение для кодов 4xx/5xx
    return response.json()

Проверка работоспособности: ваш первый GET-запрос к API

Убедимся, что подключение работает и API версии 2026 отвечает. Используем cURL для запроса системной информации:

curl -X GET "https://192.168.1.100/api/v2.0/system/version" \
  -H "Authorization: Bearer ваш_токен" \
  -H "Content-Type: application/json" \
  -k

Ответ в JSON будет содержать версию TrueNAS SCALE:

{
  "version": "TrueNAS-SCALE-24.10.0",
  "buildtime": "2026-01-15T10:30:00Z",
  "hostname": "truenas.local"
}

Если вы получаете ошибку 401 Unauthorized, проверьте корректность токена и его срок действия. Ошибка 404 Not Found может указывать на устаревший путь к API — всегда используйте базовый путь /api/v2.0/ для версий 2026 года. Перед работой с производственной средой всегда тестируйте скрипты на изолированном стенде.

CRUD на практике: автоматизируем управление дисками, пулами и пользователями

Логика CRUD (Create, Read, Update, Delete) лежит в основе REST API, аналогично модулю управления тарифными планами (traffic_plans.php), который предоставляет функции для создания, удаления, обновления и получения списка ресурсов. Применим эту логику к основным объектам TrueNAS.

Таблица-шпаргалка ключевых эндпоинтов:

Создание и мониторинг пула ZFS через API

Создание пула — типичная задача при развертывании новой инфраструктуры. Пример POST-запроса для создания пула типа mirror из двух дисков:

# Пример тела запроса (JSON) для создания пула
pool_data = {
    "name": "fast_pool",
    "encryption": False,
    "topology": {
        "data": [
            {"type": "MIRROR", "disks": ["sdb", "sdc"]}
        ]
    }
}

# Используем функцию make_api_call из предыдущего примера
try:
    result = make_api_call("pool", method="POST", data=pool_data)
    print(f"Пул создан, задача ID: {result['id']}")
except requests.exceptions.HTTPError as e:
    print(f"Ошибка создания пула: {e}")

Создание пула — асинхронная операция. После отправки запроса нужно отслеживать статус задачи. Скрипт на Python, который создает пул и ждет его готовности:

def wait_for_job(job_id, timeout=300):
    """Ожидает завершения задачи."""
    import time
    start = time.time()
    while time.time() - start < timeout:
        job_status = make_api_call(f"core/get_jobs?id={job_id}")
        state = job_status[0].get('state')
        if state == 'SUCCESS':
            print("Задача успешно завершена.")
            return True
        elif state == 'FAILED':
            print(f"Задача завершилась с ошибкой: {job_status[0].get('error')}")
            return False
        time.sleep(2)
    print("Таймаут ожидания задачи.")
    return False

# После создания пула получаем его детальную статистику
pool_info = make_api_call("pool?name=fast_pool")
print(f"Использовано пространства: {pool_info[0]['used']} из {pool_info[0]['size']}")

Управление пользователями и группами: массовое создание и права

Автоматизация создания учетных записей полезна при подключении новых сотрудников или развертывании служб, требующих отдельных пользователей. JSON-тело для создания пользователя:

user_data = {
    "username": "dev_user",
    "full_name": "Developer User",
    "password": "StrongPass123!",
    "group": 1000,  # GID группы 'developers'
    "home": "/mnt/fast_pool/home/dev_user",
    "shell": "/usr/bin/bash"
}
make_api_call("user", method="POST", data=user_data)

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

import csv

with open('new_users.csv', 'r') as file:
    reader = csv.DictReader(file)
    for row in reader:
        user_payload = {
            "username": row['username'],
            "full_name": row['full_name'],
            "password": row['temp_password'],
            "group": int(row['gid'])
        }
        try:
            make_api_call("user", method="POST", data=user_payload)
            print(f"Пользователь {row['username']} создан.")
        except requests.exceptions.HTTPError:
            print(f"Ошибка при создании {row['username']}.")

Для изменения пароля используйте PUT-запрос к эндпоинту user/id/{id}, а для отключения учетной записи — установите поле "locked": true в том же PUT-запросе.

Настройка сетевых служб: SMB и NFS шары без веб-интерфейса

Программное управление сетевым доступом — ключ к интеграции TrueNAS в инфраструктуру. Рассмотрим цепочку действий: создание каталога, настройка прав и открытие доступа по SMB/NFS.

Создадим каталог для проекта и сразу настроим SMB-шар:

# 1. Создание файловой системы (каталога)
dataset_data = {
    "name": "fast_pool/project_alpha",
    "type": "FILESYSTEM",
    "aclmode": "RESTRICTED"
}
make_api_call("pool/dataset", method="POST", data=dataset_data)

# 2. Настройка SMB-шара для этого каталога
smb_share_data = {
    "path": "/mnt/fast_pool/project_alpha",
    "name": "PROJECT_ALPHA",
    "purpose": "DEFAULT_SHARE",
    "comment": "Automated share for CI/CD artifacts"
}
make_api_call("sharing/smb", method="POST", data=smb_share_data)

# 3. (Опционально) Перезапуск службы SMB для применения изменений
make_api_call("service/restart", method="POST", data={"service": "cifs"})

Для настройки NFS-экспорта с ограничением по IP-адресам:

nfs_share_data = {
    "path": "/mnt/fast_pool/project_alpha",
    "aliases": [],
    "comment": "NFS for backup servers",
    "networks": ["192.168.10.0/24"],  # Только с этой подсети
    "hosts": ["backup-server-01"],
    "enabled": True
}
make_api_call("sharing/nfs", method="POST", data=nfs_share_data)

Готовый Python-скрипт, который создает структуру каталогов для нового проекта и открывает доступ, может стать частью вашего пайплайна развертывания. Помните о безопасности: не открывайте полный доступ (rw, no_root_squash) без необходимости и всегда ограничивайте доступ подсетями или конкретными хостами. Для критичных по производительности задач, таких как хранение баз данных или виртуальных машин, дополнительно настройте параметры ZFS (recordsize, компрессию) и сетевые протоколы, как описано в нашем руководстве по оптимизации производительности TrueNAS 2026.

Интеграция в DevOps-ландшафт: CI/CD, мониторинг и оркестрация

Настоящая ценность API раскрывается при его интеграции в существующие инструменты автоматизации. Подобно тому, как использование WebCodecs API позволило достичь 83% роста трафика за счет эффективной клиентской обработки видео, интеграция TrueNAS в DevOps-пайплайны экономит время и снижает операционные риски.

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

Вот пример job для GitLab CI, который создает изолированное тестовое хранилище по тегу в коммите, а после прохождения тестов — очищает его.

# .gitlab-ci.yml
stages:
  - deploy_test_env
  - test
  - cleanup

create_truenas_test_env:
  stage: deploy_test_env
  script:
    - |
      # Скрипт создания тестового пула и шара (упрощенный пример)
      python3 << EOF
      import requests, os
      host = os.environ['TRUENAS_HOST']
      token = os.environ['TRUENAS_API_TOKEN']
      headers = {'Authorization': f'Bearer {token}'}
      # Создание временного датасета
      requests.post(f"{host}/api/v2.0/pool/dataset",
                    json={"name": "fast_pool/test_$CI_COMMIT_SHORT_SHA"},
                    headers=headers, verify=False)
      # Создание SMB-шара
      requests.post(f"{host}/api/v2.0/sharing/smb",
                    json={"path": f"/mnt/fast_pool/test_$CI_COMMIT_SHORT_SHA", "name": "CI_TEST"},
                    headers=headers, verify=False)
      EOF
  only:
    - tags

cleanup_truenas_test_env:
  stage: cleanup
  script:
    - |
      # Удаление тестового датасета (рекурсивно удалит и шар)
      python3 << EOF
      import requests, os
      host = os.environ['TRUENAS_HOST']
      token = os.environ['TRUENAS_API_TOKEN']
      headers = {'Authorization': f'Bearer {token}'}
      requests.delete(f"{host}/api/v2.0/pool/dataset/id/fast_pool%2Ftest_$CI_COMMIT_SHORT_SHA",
                      headers=headers, verify=False)
      EOF
  only:
    - tags
  when: always

Мониторинг здоровья хранилища через Prometheus

Для интеграции с Prometheus можно использовать Textfile Collector. Python-скрапер будет опрашивать API TrueNAS и записывать метрики в файл, который Prometheus будет считывать.

#!/usr/bin/env python3
# truenas_exporter.py
import requests
import time

# ... (код аутентификации из первого раздела) ...

def get_pool_metrics():
    pools = make_api_call("pool")
    metrics = []
    for pool in pools:
        metrics.append(f'truenas_pool_size_bytes{{pool="{pool["name"]}"}} {pool["size"]}')
        metrics.append(f'truenas_pool_used_bytes{{pool="{pool["name"]}"}} {pool["used"]}')
        metrics.append(f'truenas_pool_status{{pool="{pool["name"]}"}} {1 if pool["healthy"] else 0}')
    return "\n".join(metrics)

def get_system_alerts():
    alerts = make_api_call("alert/list")
    critical_alerts = sum(1 for a in alerts if a["level"] in ["CRITICAL", "ERROR"])
    return f'truenas_critical_alerts {critical_alerts}'

if __name__ == "__main__":
    while True:
        all_metrics = "\n".join([get_pool_metrics(), get_system_alerts()])
        with open("/var/lib/prometheus/node-exporter/truenas_metrics.prom", "w") as f:
            f.write(all_metrics)
        time.sleep(60)  # Обновление каждую минуту

Запустите этот скрапер как службу, и в Grafana вы сможете создать дашборд для отслеживания состояния ваших пулов ZFS и получения уведомлений о критических алертах. Для более глубокой настройки сетевой инфраструктуры, включая сегментацию трафика, обратитесь к руководству по настройке маршрутизации между VLAN в TrueNAS Scale 2026.

Идеи для интеграции с оркестраторами: используйте TrueNAS как бэкенд для Kubernetes Persistent Volumes через NFS или iSCSI. Управление созданием и удалением томов (PV/PVC) можно автоматизировать через внешний provisioner, который будет делать вызовы к API TrueNAS. Для настройки высокопроизводительного iSCSI-хранилища под виртуализацию или СУБД следуйте нашему пошаговому руководству по настройке iSCSI Target в TrueNAS 2026.

Справочник и устранение неполадок: от структуры API до типовых ошибок

Эта шпаргалка поможет в самостоятельной работе и диагностике проблем.

Сводная таблица ключевых эндпоинтов TrueNAS SCALE API 2026:

Разбор типовых ошибок HTTP:

• 401 Unauthorized: Неверный или просроченный токен. Сгенерируйте новый ключ в веб-интерфейсе.
• 403 Forbidden: У токена недостаточно прав для выполнения операции. Пересмотрите права доступа ключа.
• 404 Not Found: Неверный URL эндпоинта. Убедитесь, что используете префикс /api/v2.0/ и актуальный путь из документации.
• 422 Unprocessable Entity: Ошибка в теле запроса (неверный формат JSON, отсутствуют обязательные поля). Внимательно проверьте отправляемые данные.

Для изучения актуальной структуры API используйте встроенный Swagger UI TrueNAS, доступный по адресу https://<ваш_сервер>/api/v2.0/docs/. Это интерактивная документация, которая всегда соответствует версии вашей системы.

Важное предупреждение: API может меняться между мажорными версиями TrueNAS SCALE. Всегда проверяйте версию API через запрос к /api/v2.0/system/version и сверяйтесь с документацией, соответствующей именно вашей версии (2026). Перед выполнением деструктивных операций (удаление пула, диска) в production-среде обязательно создавайте резервные копии конфигурации. Для отработки навыков автоматизации и безопасного тестирования скриптов используйте практическое руководство по Linux, которое поможет быстро развернуть тестовый стенд.