Тенантное CLI#
Обзор#
tenant-cli — утилита командной строки для работы с Tenant API подсистемы.
Основные возможности:
работа с подсистемой через консольные команды;
просмотр и применение конфигурации инфраструктуры;
поддержка JWT и OIDC авторизации;
автоматическое сохранение токенов для последующих запросов;
verbose режимы для отладки (включая генерацию curl-команд);
вывод информации в JSON формате.
Установка и первоначальная настройка#
Конфигурационный файл#
Тенантное CLI использует конфигурационный файл для хранения токена подключения к тенантному API, расположенный по пути ~/.config/tenant-cli/config.yaml.
Пример вида конфигурационного файла:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX...."
}
Параметры подключения к тенантному API#
Тенантное CLI может брать параметры подключения к тенантному API подсистемы из нескольких источников. Источники сортируются по приоритету, и при нахождении параметров в одном из них, поиск в источниках с более низким приоритетом не осуществляется.
Список источников по убыванию приоритета:
Из переменных окружения
API_HOST,API_PORTиAPI_SCHEME.Из файла
.env, расположенного в одной директории с тенантным CLI.Из файла
.env, расположенного по пути~/.apos/tenant-cli/.Из файла
.env, расположенного в CWD (Current Working Directory).Если ничего вышеперечисленного не найдено, то используются дефолтные значения
API_HOST=127.0.0.1,API_PORT=9091иAPI_SCHEME=http.
Пример вида файла .env:
API_HOST=127.0.0.1
API_PORT=5001
API_SCHEME=https
Процесс авторизации#
Тенантное CLI поддерживает два метода авторизации:
JWT-токен;
OIDC-провайдер (интерактивный режим через браузер).
Авторизация через JWT-токен#
Нерекомендуемый способ — его можно использовать только в непродуктивных средах для целей отладки и автоматизации
Получить JWT-токен — JWT-токен должен быть предоставлен администратором системы или получен через внешний механизм аутентификации.
Формат токена — JWT в формате eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Авторизация в
tenant-cliкомандой:
./tenant-cli auth --token=../test-token.jwt
Пример успешного ответа:
Авторизация настроена и сохранена успешно
Проверить авторизацию и автоматическое применение токена командой:
./tenant-cli config-show
Если команда выполнилась без ошибок авторизации, значит авторизация прошла успешно.
Примечание
Сохраненный токен расположен в ~/.config/tenant-cli/config.json.
Авторизация через OIDC#
При этом методе требуется браузер и интерактивное взаимодействие с пользователем.
Запустить авторизацию командой:
./tenant-cli auth --issuer https://your-oidc-provider.com --client-id apos
Пример вывода:
Ссылка для авторизации: https://your-oidc-provider.com/oauth2/authorize?client_id=apos&redirect_uri=http://localhost:9876/callback&response_type=code&scope=openid+profile&state=abc123&code_challenge=xyz789&code_challenge_method=S256&nonce=def456
Ожидание ответа сервера на порте 9876
Если доступ невозможен введите строку перенаправления вручную (в формате http://localhost:9876/callback?code=<code>):
В браузере:
скопировать ссылку из вывода команды;
открыть ее в браузере;
войти в систему через OIDC-провайдер;
после успешной аутентификации произойдет перенаправление на
http://localhost:9876/callback.
Страница успешной авторизации:
Успешно
Авторизация выполнена успешно.
После успешного редиректа в терминале появится:
токен получен
Авторизация настроена и сохранена успешно
Альтернативный способ (ручной ввод callback URL)#
Если автоматический callback не работает (например, нет доступа к localhost:9876):
После входа через браузер скопировать полный URL из адресной строки:
http://localhost:9876/callback?code=AUTHORIZATION_CODE&state=abc123
Вставить этот URL в терминал, где ожидает
tenant-cliНажать клавишу Enter.
Пример вывода:
Ожидание ответа сервера на порте 9876
Если доступ невозможен введите строку перенаправления вручную: http://localhost:9876/callback?code=AUTH_CODE_HERE&state=abc123
Получена строка: http://localhost:9876/callback?code=AUTH_CODE_HERE&state=abc123
токен получен
Авторизация настроена и сохранена успешно
Опции команды auth#
Пример вывода команды ./tenant-cli auth --help:
Команда сохраняет параметры подключения к системному API AposCMS.
Пример:
auth --insecure
Usage:
tenant-cli auth [flags]
Flags:
--client-id string Идентификатор клиента (default "apos")
-h, --help help for auth
--insecure Разрешить небезопасные подключения
--issuer string Адрес OIDC провайдера (default "https://roox.apos.network/sso/realms/employee/as/oauth2/idp")
--port int Порт для подключения (default 9876)
--token string Файл с токеном для прямой записи в конфигурацию
Global Flags:
--disable-validation Отключить серверную валидацию конфигурации (ОПАСНО)
-v, --verbose count Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.
Флаг –insecure (подробное описание)#
Флаг --insecure отключает проверку SSL/TLS сертификатов при подключении к OIDC-провайдеру и к API подсистемы.
Примечание
Использование этого флага делает соединение уязвимым к атакам типа Man-in-the-Middle (MITM).
Рекомендуется использовать:
в окружении разработчика с самоподписанными сертификатами;
при тестировании в изолированной сети;
исправление проблем с SSL/TLS.
Запрещено использовать:
в продуктовом окружении;
при работе через публичные сети;
при работе с чувствительными данными.
Пример использования:
Окружении разработчика — авторизация с самоподписанным сертификатом:
./tenant-cli auth --token /opt/apos/tokens/dev-admin.jwt --insecure
Или с OIDC-провайдером:
./tenant-cli auth --issuer https://dev-oidc.internal.local --client-id apos --insecure
Безопасная альтернатива для окружения разработчика:
Вместо использования флага --insecure, добавить самоподписанный сертификат в доверенные:
Скачать сертификат:
openssl s_client -connect dev-oidc.internal.local:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > dev-cert.pem
Добавить в системное хранилище сертификатов:
sudo cp dev-cert.pem /usr/local/share/ca-certificates/dev-oidc.crt
sudo update-ca-certificates
Подключиться без
--insecure:
./tenant-cli auth --issuer https://dev-oidc.internal.local --client-id apos
Переавторизация#
Для смены токена или пользователя Необходимо выполнить команду auth заново:
./tenant-cli auth --token /opt/apos/tokens/another-admin.jwt
Новая авторизация перезапишет старый токен.
Основные команды#
Получение справки#
Для получения общей справки необходимо использовать команду:
./tenant-cli --help
Или:
./tenant-cli -h
Для получения справки по конкретной команде необходимо использовать:
./tenant-cli [имя_команды] --help
Или:
./tenant-cli [имя_команды] -h
Пример вызова ./tenant-cli --help:
CLI используемый для управления внутренними компонентами платформы, конфигурациями и т.д.
Usage:
tenant-cli [flags]
tenant-cli [command]
Available Commands:
address-set-create Создать множество адресов
address-set-delete Удалить множество адресов
...
<прочие команды>
...
vrouter-route-create Создать статический маршрут для виртуального маршрутизатора
vrouter-route-delete Удалить статический маршрут
vrouter-route-list Получить список статических маршрутов виртуального маршрутизатора
vrouter-route-show Получить статический маршрут по ID
vrouter-route-update Обновить статический маршрут
vrouter-show Получить информацию о виртуальном маршрутизаторе по ID
vrouter-update Обновить виртуальный маршрутизатор по ID
Flags:
--disable-validation Отключить серверную валидацию конфигурации (ОПАСНО)
-h, --help help for system-cli
-v, --verbose count Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.
--version version for system-cli
Use "system-cli [command] --help" for more information about a command.
##
Примеры вызова конкретной команды ./tenant-cli vport-list -h:
Выводит список виртуальных портов.
Примеры:
vport-list --tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa6
vport-list --tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa6 \
--tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa7 \
--enabled=true --sort-by=created_at --sort-order=desc
Usage:
tenant-cli vport-list [flags]
Flags:
--chassis-id string Идентификатор шасси
--created-by string Фильтр: кто создал
--created-from string Создано с (datetime)
--created-to string Создано по (datetime)
--display-name string Фильтр по отображаемому имени
--enabled Фильтр: только включенные (default true)
-h, --help help for vport-list
--is-utility Флаг служебного порта (по умолчанию false)
--json Вывод в формате JSON (default true)
--page int Номер страницы (default 1)
--per-page int Размер страницы (default 20)
--purpose string Предназначение служебного порта
--sort-by string Поле сортировки (default "created_at")
--sort-order string Порядок сортировки (asc|desc) (default "desc")
--tenant-id stringArray Идентификатор одного или нескольких тенантов
--updated-by string Фильтр: кто обновил
--updated-from string Обновлено с (datetime)
--updated-to string Обновлено по (datetime)
--vm-port-id string Идентификатор порта OVS подключаемого к виртуальному порту
--vnet-id string Идентификатор виртуальной сети
--vport-id string Идентификатор вирутального порта
--vrouter-id string Идентификатор виртуального маршрутизатора
Global Flags:
--disable-validation Отключить серверную валидацию конфигурации (ОПАСНО)
-v, --verbose count Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.
Команда vnet-list#
Просмотр списка виртуальных сетей.
Базовое использование:
./tenant-cli vnet-list
Пример вывода (JSON):
{
"data": [
{
"active": true,
"created_at": "2026-06-26T13:35:20Z",
"created_by": "tenant_admin",
"dhcp_v4": {
"active": true,
"dns": [],
"enabled": true,
"excluded_address_ranges": [
"192.168.10.1-192.168.10.5",
"192.168.10.7-192.168.10.10"
],
"gateway": "192.168.10.1",
"id": "60545eae-0cb8-4ee4-8557-b3a1adf089fd",
"server_ip": "192.168.10.1",
"server_mac": "00:59:2e:ba:b5:8b"
},
"display_name": "vnet01",
"enabled": true,
"id": "44550d68-e21f-4a42-a1ca-6e8a1128297f",
"is_utility": false,
"ovn_version": 1,
"subnet_v4": "192.168.10.0/24",
"tenant_id": "14973214-4597-490a-b7ae-626c0c099dfc",
"updated_at": "2026-06-29T12:22:12Z",
"updated_by": "enant_admin",
"version": 1
},
],
"pagination": {
"count": 1,
"page": 1,
"per_page": 10,
"total_count": 1
}
}
Справка (команда ./tenant-cli vnet-list --help):
Получить список виртуальных сетей с возможностью фильтрации и пагинации.
Пример:
vnet-list --tenant-id=3fa85f64-5717-4562-b3fc-2c963f66afa6 --enabled=true --page=1 --per-page=10 --sort-by=display_name
Usage:
tenant-cli vnet-list [flags]
Flags:
--created-by string Фильтр по создателю
--created-from string Дата создания от (RFC3339)
--created-to string Дата создания до (RFC3339)
--display-name string Фильтр по отображаемому имени
--enabled Фильтр по включенности (default true)
-h, --help help for vnet-list
--is-utility Флаг служебной виртуальной сети (по умолчанию false)
--json Выводить результат в формате JSON (default true)
--page int Номер страницы (default 1)
--per-page int Кол-во элементов на странице (default 10)
--purpose string Предназначение служебной виртуальной сети
--sort-by string Поле сортировки (display_name, subnet, created_at, updated_at)
--sort-order string Направление сортировки (asc|desc) (default "desc")
--subnet string Фильтр по подсети
--tenant-id stringArray Фильтр по ID одного или нескольких тенантов
--updated-by string Фильтр по обновившему
--updated-from string Дата обновления от (RFC3339)
--updated-to string Дата обновления до (RFC3339)
--vrouter-id string Фильтр по ID виртуального маршрутизатора
Global Flags:
--disable-validation Отключить серверную валидацию конфигурации (ОПАСНО)
-v, --verbose count Уровень детализации логов.
Уровень 0 (по умолчанию): Логи отключены.
Уровень 1 (-v): Логируется x-request-id для отслеживания запросов.
Уровень 2 (-vv): Логируются все исходящие запросы в виде curl-команд.
Глобальные флаги#
Глобальные флаги доступны для всех команд tenant-cli.
Флаг –verbose / -v#
Управление уровнем детализации вывода для отладки и мониторинга.
Уровень 0 (по умолчанию) — логи отключены#
./tenant-cli config-show
Выводится только результат команды без дополнительной отладочной информации.
Уровень 1 (-v) — логирование x-request-id#
./tenant-cli config-show -v
Пример вывода после выполнения команды:
x-request-id: 550e8400-e29b-41d4-a716-446655440000
{
"configuration": {
...
}
}
Применение:
отслеживание запросов в логах сервера;
корреляция запросов между клиентом и сервером;
отладка распределенных систем.
Использование x-request-id в логах сервера:
На стороне сервера этот ID можно найти в логах:
[2026-03-18 10:00:00] INFO request_id=550e8400-e29b-41d4-a716-446655440000 method=GET path=/api/v1/configuration status=200
Это позволяет легко связать клиентский запрос с серверными логами.
Уровень 2 (-vv) — логирование curl-команд#
./tenant-cli config-show -vv
Пример вывода после выполнения команды:
curl -X GET 'http://127.0.0.1:4010/api/v1/vports?page=1&per_page=20&sort_by=created_at&sort_order=desc' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo.......'
Успешно:
{
"data": [
{
"active": true,
"addresses": [
{
"ip": "192.168.10.1",
"mac": "55:87:E2:CD:EE:F2",
"type": "generated_v4"
}
],
"chassis_id": "d2407ce7-9a09-4c19-a766-239486331a8d",
"created_at": "2019-08-24T14:15:22Z",
"created_by": "string",
"display_name": "string",
"enabled": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_utility": false,
"ovn_version": 0,
"purpose": "VNF-NGFW",
"tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
"unknown": false,
"updated_at": "2019-08-24T14:15:22Z",
"updated_by": "string",
"version": -9007199254740991,
"vm_port_id": "string",
"vnet_id": "15730f2a-d355-4139-9942-db8cedb3dda9"
}
],
"pagination": {
"count": 2,
"page": 1,
"per_page": 25,
"total_count": 2
}
}
Применение:
отладка API-запросов;
воспроизведение запросов вручную через curl;
документирование API взаимодействий;
обучение работе с API;
создание shell-скриптов для автоматизации.
Пример использования вывода:
Скопировать curl-команду из вывода и выполнить ее отдельно:
# Скопированная команда из вывода -vv
curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' -H 'Authorization: Bearer eyJhbGc...' -H 'Content-Type: application/json'
Это позволяет:
модифицировать запрос для тестирования;
добавлять дополнительные заголовки;
изменять параметры запроса;
Использовать в CI/CD pipeline.
Флаг: –disable-validation#
Отключение серверной валидации конфигурации.
./tenant-cli config-apply --input config.json --disable-validation
Предупреждение
Этот флаг необходимо использовать с осторожностью.
При использовании флага:
сервер пропускает все проверки корректности конфигурации;
могут быть применены некорректные данные;
возможны конфликты в конфигурации;
система может перейти в нестабильное состояние.
Когда рекомендуется использовать:
отладка проблем с валидацией;
экстренное восстановление системы;
миграция между версиями с изменениями в схеме данных;
только при действительной необходимости.
Запрещено использовать:
в продуктивном окружении;
при автоматизированных процессах;
когда нет уверенности корректности конфигурации.
Пример безопасного использования:
Применить с валидацией:
./tenant-cli config-apply --input config.json
Если валидация не прошла, изучить ошибки:
# Ошибка: "vnet subnet overlaps with existing vnet"
Исправить конфигурацию и попробовать снова:
./tenant-cli config-apply --input config.json
Примечание
При необходимости, в крайнем случае, можно использовать флаг --disable-validation (например, для экстренного восстановления)
./tenant-cli config-apply --input emergency-recovery.json --disable-validation
Примеры использования тенантного CLI#
Пример 1: Первоначальная настройка системы#
Авторизоваться в системном CLI:
./tenant-cli auth --token=../test-token.jwt
Просмотреть текущую конфигурацию:
./tenant-cli config-show
Применить новую конфигурацию:
./tenant-cli config-apply --input-json="$(cat config-example.json)"
Пример 2: Отладка запросов с verbose режимом#
Получить curl-команду для воспроизведения запроса:
./tenant-cli config-show -vv
Пример вывода команды:
# curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' # -H 'Authorization: Bearer eyJ...' # -H 'Content-Type: application/json'
Выполнить curl вручную для тестирования:
curl -X GET 'http://127.0.0.1:5000/api/v1/configuration' -H 'Authorization: Bearer eyJ...' -H 'Content-Type: application/json' | jq .
Полная документация по командам#
Полную документацию по командам в формате markdown можно найти в архиве: