Консольная утилита для управления контейнерной платформой Imagenarium

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for koden8 from gravatar.com koden8

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT License (non-commercial) / Commercial License)
  • Author: @koden8
  • Maintainer: @koden8
  • Tags docker , containers , orchestration , cli , imagenarium
  • Requires: Python >=3.8
  • Provides-Extra: dev
Classifiers
Report project as malware

Project description

imgctl

Консольная утилита для управления контейнерной платформой «Imagenarium».

Описание

imgctl представляет собой консольную утилиту для управления контейнерной платформой «Imagenarium».

Содержание

Установка

Системные требования

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

  • Python: версия 3.8 или выше (для установки через pip)
  • Git: версия 2.0 или выше (необходим для работы с Git репозиториями при получении тегов и шаблонов)
  • Сетевое подключение: доступ к API-эндпоинтам «Imagenarium»
  • Операционная система: Linux, macOS, Windows

Способы установки

1. Установка Windows Executable

Скачайте Windows executable из раздела релиза в GitLab или используйте прямую ссылку на Generic Packages:

# Скачать Windows executable (замените 3.2.0 на нужную версию)
Invoke-WebRequest -Uri "https://gitlab.com/api/v4/projects/koden8%2Fimgctl/packages/generic/imgctl/3.2.0/imgctl.exe" -OutFile "imgctl.exe"

# Добавить в PATH (опционально)
# Переместите imgctl.exe в папку, которая уже в PATH, или добавьте текущую папку в PATH
$env:Path += ";$PWD"

2. Установка через Homebrew (macOS)

# Добавить tap
brew tap koden8/homebrew-imgctl https://gitlab.com/koden8/homebrew-imgctl.git

# Установить imgctl
brew install imgctl

# Обновить
brew upgrade imgctl

3. Установка через Docker

# Запуск последней версии
docker run --rm -it registry.gitlab.com/koden8/imgctl:latest

# Запуск конкретной версии
docker run --rm -it registry.gitlab.com/koden8/imgctl:3.2.0

# Создать алиас для удобства (с монтированием конфигурации и кеша)
alias imgctl='docker run --rm -it \
  -v ~/.config/imgctl_docker:/home/imgctl/.config/imgctl \
  -v ~/.cache/imgctl_docker:/home/imgctl/.cache/imgctl \
  registry.gitlab.com/koden8/imgctl:latest'

# Или использовать Docker volumes (рекомендуется)
docker volume create imgctl_config
docker volume create imgctl_cache
alias imgctl='docker run --rm -it \
  -v imgctl_config:/home/imgctl/.config/imgctl \
  -v imgctl_cache:/home/imgctl/.cache/imgctl \
  registry.gitlab.com/koden8/imgctl:latest'

Важно:

  • Монтирование кеша: Для корректной работы кеширования Git репозиториев необходимо монтировать директорию кеша в контейнер. Без этого кеш будет теряться между запусками контейнера.
  • Монтирование конфигурации: Для сохранения настроек серверов и паролей между запусками необходимо монтировать директорию конфигурации. Рекомендуется использовать отдельную директорию ~/.config/imgctl_docker для Docker, чтобы разделить конфигурацию локальной установки и Docker контейнера.
  • Автоматическое исправление прав доступа: Начиная с версии 3.0.18, контейнер автоматически исправляет права доступа к монтируемым директориям при запуске, поэтому предварительная настройка прав доступа не требуется.
  • В Docker контейнерах imgctl автоматически использует PlaintextKeyring из keyrings.alt.file для сохранения паролей, так как системный keyring недоступен. Пароли хранятся в ~/.config/imgctl/keyring_pass.cfg с правами доступа 600. Работает полностью автоматически без запросов пароля.

4. Установка через pip (рекомендуется)

С PyPI:

# Обновить pip
pip install --upgrade pip

# Установить последнюю версию с PyPI
pip install imgctl

# Или установить конкретную версию
pip install imgctl==3.2.0

Из исходников GitLab:

# Скачать и установить из архивов GitLab
pip install https://gitlab.com/koden8/imgctl/-/archive/main/imgctl-main.tar.gz

# Или из релизов
pip install https://gitlab.com/koden8/imgctl/-/archive/v3.2.0/imgctl-v3.2.0.tar.gz

Установка bash completion после установки через pip:

# Найти и установить bash completion
COMPLETION_FILE=$(python3 -c "import os, imgctl; print(os.path.join(os.path.dirname(imgctl.__file__), 'imgctl-completion.bash'))")
bash "$COMPLETION_FILE" install

# Перезагрузите bash или выполните:
source ~/.bashrc

Или добавьте вручную в ~/.bashrc:

# Добавить в ~/.bashrc
source $(python3 -c "import os, imgctl; print(os.path.join(os.path.dirname(imgctl.__file__), 'imgctl-completion.bash'))")

Проверка установки

После завершения установки выполните проверку корректности установки:

# Проверка доступности команд
imgctl --help

# Проверка наличия Git (необходим для работы с репозиториями)
git --version

Устранение проблем установки

В случае возникновения проблем при установке:

  1. Проверьте версию Python: python3 --version (требуется 3.8+)
  2. Проверьте наличие Git: git --version (требуется 2.0+, необходим для работы с Git репозиториями)
  3. Обновите pip: pip install --upgrade pip
  4. Установите зависимости вручную: pip install -e .

Решение проблем с установкой

Проблема: "No module named 'imgctl'"

# Решение: переустановите пакет
pip uninstall imgctl
pip install --no-cache-dir imgctl

Проблема: "Permission denied" при установке

# Решение: используйте флаг --user
pip install --user imgctl

**Проблема: Устаревшая версия**
```bash

Решение: обновите до последней версии

pip install --upgrade imgctl


**Проблема: "git: command not found" или ошибки при работе с Git репозиториями**
```bash
# Решение: установите Git
# macOS
brew install git

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install git

# Windows
# Скачайте и установите Git for Windows: https://git-scm.com/download/win

# Проверка установки
git --version

Быстрый старт

Данный раздел содержит пошаговое руководство по началу работы с imgctl.

Этап 1: Настройка серверного подключения

Первоначальная настройка включает добавление сервера «Imagenarium» и настройку подключения:

# Добавление сервера с указанием параметров подключения
imgctl servers add dev \
  --url http://your-server:5555 \
  --username admin \
  --password your-password \
  --description "Development environment"

# Установка сервера по умолчанию для упрощения работы
imgctl servers set-default dev

Этап 2: Проверка подключения и доступности ресурсов

После настройки сервера выполните проверку подключения и доступности ресурсов:

# Проверка подключения к серверу
imgctl servers test dev

# Получение списка доступных узлов
imgctl nodes list

# Проверка статуса реестров
imgctl registries list

Этап 3: Управление компонентами и стеками

# Список всех компонентов
imgctl components list

# Детальная информация о компоненте
imgctl components get my-component

# Просмотр логов
imgctl logs my-component --follow

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

imgctl поддерживает несколько способов определения сервера (в порядке приоритета):

  1. Параметры командной строки (высший приоритет): --server, --username, --password
  2. Переменные окружения: IMG_SERVER, IMG_USERNAME, IMG_PASSWORD
  3. Файл конфигурации: стандартный путь или через --config
  4. Сервер по умолчанию из сохраненных серверов

Примеры использования

# Через параметры командной строки (высший приоритет)
imgctl --server dev components list
imgctl --server http://server:5555 --username admin --password pass components list

# Через переменные окружения
IMG_SERVER=dev imgctl components list
IMG_SERVER=http://server:5555 IMG_USERNAME=admin IMG_PASSWORD=pass imgctl components list

# Через файл конфигурации
imgctl --config /path/to/config.yaml components list

# Через сервер по умолчанию (низший приоритет)
imgctl components list

Пути к файлу конфигурации

imgctl автоматически ищет файл конфигурации в следующих местах:

ОС Путь Пример полного пути
Linux ~/.config/imgctl/config.yaml /home/username/.config/imgctl/config.yaml
macOS ~/.config/imgctl/config.yaml /Users/username/.config/imgctl/config.yaml
Windows %APPDATA%/imgctl/config.yaml C:\Users\username\AppData\Roaming\imgctl\config.yaml

Пример содержимого файла конфигурации

server: "http://your-imagenarium-server:5555"
username: "your-username"
password: "your-password"
timeout: 30
verify_ssl: true

Параметры подключения

Параметры командной строки

Параметр Короткая форма Описание Пример
--server -s Имя сервера или URL для подключения --server dev или --server http://server:5555
--username -u Имя пользователя (для прямого подключения) --username admin
--password -p Пароль (для прямого подключения) --password secret
--config -c Путь к файлу конфигурации --config /path/to/config.yml
--verbose -v Подробный вывод --verbose

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

Переменная Описание Пример
IMG_SERVER Имя сервера или URL для подключения IMG_SERVER=dev или IMG_SERVER=http://server:5555
IMG_USERNAME Имя пользователя (для прямого подключения) IMG_USERNAME=admin
IMG_PASSWORD Пароль (для прямого подключения) IMG_PASSWORD=secret

Правила использования

  1. Приоритет: Параметры командной строки имеют приоритет над переменными окружения
  2. URL vs имя сервера:
    • Если IMG_SERVER или --server содержит URL (начинается с http:// или https://), то требуются IMG_USERNAME и IMG_PASSWORD
    • Если это имя сервера, то используются сохраненные учетные данные
  3. Безопасность: Пароли в переменных окружения более безопасны, чем в командной строке

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

# Использование имени сервера (используются сохраненные учетные данные)
imgctl --server dev components list
IMG_SERVER=dev imgctl components list

# Прямое подключение через URL
imgctl --server http://server:5555 --username admin --password secret components list
IMG_SERVER=http://server:5555 IMG_USERNAME=admin IMG_PASSWORD=secret imgctl components list

# Смешанное использование (сервер из переменной, учетные данные из параметров)
IMG_SERVER=http://server:5555 imgctl --username admin --password secret components list

Команды

  • imgctl servers - управление серверами
  • imgctl nodes - управление нодами
  • imgctl stacks - управление стеками (list, get)
  • imgctl components - управление компонентами (list, get, upgrade, tags, …)
  • imgctl templates - шаблоны деплоя (get, params, params-changelog, changelog)
  • imgctl logs - просмотр логов компонентов
  • imgctl registries - управление реестрами
  • imgctl repositories - управление репозиториями
  • imgctl shell - интерактивная оболочка (REPL режим)
  • imgctl mcp - MCP-сервер для интеграции с AI-агентами (Claude, Cursor, OpenCode и др.)

Управление серверами

Команды для управления настройками серверов подключения.

Доступные команды

  • imgctl servers list - список серверов
  • imgctl servers add <name> - добавить новый сервер
  • imgctl servers get <name> - информация о сервере
  • imgctl servers update <name> - обновить настройки сервера
  • imgctl servers remove <name> - удалить сервер
  • imgctl servers set-default <name> - установить сервер по умолчанию
  • imgctl servers test <name> - тестировать подключение

Доступные столбцы для list

  • NAME: Имя сервера
  • URL: URL сервера
  • USERNAME: Имя пользователя
  • DESCRIPTION: Описание сервера
  • DEFAULT: Отметка сервера по умолчанию (✓)
  • PASSWORD: Пароль (только с --show-passwords)

По умолчанию: NAME, URL, USERNAME, DESCRIPTION, DEFAULT

Параметры servers list

  • --columns <COLUMNS> - список столбцов для отображения
  • --filter <FILTER> - фильтр данных
  • --no-headers - не показывать заголовки
  • --show-passwords - показать пароли (не рекомендуется)
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)

Примеры

# Список серверов
imgctl servers list

# Список с дополнительными столбцами
imgctl servers list --columns "NAME,URL,USERNAME,DESCRIPTION"

# Фильтр по имени
imgctl servers list --filter NAME=dev

# Фильтр по URL (регулярное выражение)
imgctl servers list --filter URL~registry

# Показать пароли (не рекомендуется)
imgctl servers list --show-passwords

# Добавление нового сервера
imgctl servers add dev --url http://dev.example.com:5555 --username admin --password secret

# Добавление сервера с настройками TTL
imgctl servers add prod \
  --url http://prod.example.com:5555 \
  --username admin \
  --password secret \
  --description "Production environment" \
  --ttl /deployments/list:10 \
  --ttl /deployments/tags:60

# Просмотр информации о сервере
imgctl servers get dev

# Просмотр с настройками TTL
imgctl servers get prod --format json

# Установка сервера по умолчанию
imgctl servers set-default dev

# Обновление сервера с новыми настройками TTL
imgctl servers update prod \
  --description "Updated production environment" \
  --ttl /api/v3/nodes:5 \
  --ttl /deployments/list:15

# Тестирование подключения
imgctl servers test dev

# Удаление сервера
imgctl servers remove dev

Управление нодами

Команды для управления нодами (узлами) кластера.

Доступные команды

  • imgctl nodes list - список нод
  • imgctl nodes get <name> - детальная информация о ноде

Параметры nodes get

  • --output / -o — только json или yaml: одна запись в stdout вместо развёрнутого вывода; без флага — прежний текстовый вид
  • --verbose / -v — подробный вывод HTTP-запросов

Доступные столбцы для list

  • NAME: Имя ноды
  • IP: IP адрес
  • ROLE: Роль (manager/worker)
  • AVAILABILITY: Доступность (ACTIVE/DRAIN/PAUSE)
  • STATUS: Статус (READY/UNHEALTHY)
  • DC: Дата-центр
  • DOCKER_VERSION: Версия Docker
  • TOTAL_MEMORY: Общий объем памяти (GB)
  • SSH_PORT: SSH порт
  • SSH_USER: SSH пользователь
  • EXTERNAL_URL: Внешний URL
  • ID: Уникальный идентификатор

По умолчанию: NAME, IP, ROLE, AVAILABILITY, STATUS

Параметры nodes list

  • --columns <COLUMNS> - список столбцов для отображения
  • --filter <FILTER> - фильтр данных
  • --no-headers - не показывать заголовки
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)
  • --limit <N> - ограничить количество записей

Примеры

# Список нод
imgctl nodes list

# Список нод с дополнительными столбцами
imgctl nodes list --columns "NAME,IP,DC,DOCKER_VERSION,TOTAL_MEMORY"

# Добавить/удалить столбцы
imgctl nodes list --columns "+TOTAL_MEMORY,-ID"

# Фильтр по статусу
imgctl nodes list --filter STATUS=READY

# Фильтр по роли
imgctl nodes list --filter ROLE=manager

# Фильтр по IP (регулярное выражение)
imgctl nodes list --filter IP~10.9

# Вывод без заголовков
imgctl nodes list --no-headers

# Детальная информация о ноде
imgctl nodes get node-01

# Обновление ноды
imgctl nodes update node-01 --role worker --availability drain

Управление стеками

Команды для управления стеками развертываний.

Формат имен

Все имена стеков отображаются в формате stack@namespace:

  • database@production - стек database в namespace production
  • web-api@staging - стек web-api в namespace staging

Имена имеют цветовую подсветку: имя стека отображается белым, а @namespace - серым цветом для лучшей читаемости.

Доступные команды

  • imgctl stacks list - список стеков
  • imgctl stacks get <stack>@<namespace> - детальная информация о стеке
  • imgctl stacks template <stack> - просмотр шаблона деплоя (параметры, задачи, сервисы)
  • imgctl stacks template <stack> <commit> --diff - сравнение текущего шаблона с указанным commit

Параметры stacks get

  • --output / -o — только json или yaml: одна запись в stdout вместо развёрнутого вывода; без флага — прежний текстовый вид
  • --verbose / -v — подробный вывод HTTP-запросов

Доступные столбцы для list

  • NAME: Название стека (в формате stack@namespace)
  • NAMESPACE: Пространство имен
  • VERSION: Версия стека
  • STATUS: Статус стека
  • REPO: Репозиторий
  • COMMIT: Git коммит
  • TIME: Время развертывания
  • TAG: Тег версии
  • PARAMETERS: Параметры
  • COMPONENTS: Компоненты

По умолчанию: NAME, NAMESPACE, VERSION, STATUS

Параметры stacks list

  • --columns <COLUMNS> - список столбцов для отображения
  • --filter <FILTER> - фильтр данных
  • --no-headers - не показывать заголовки
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)
  • --limit <N> - ограничить количество записей

Примеры

# Список стеков
imgctl stacks list

# Список с дополнительными столбцами
imgctl stacks list --columns "NAME,NAMESPACE,VERSION,STATUS,REPO,COMMIT,TIME,TAG"

# Фильтр по статусу
imgctl stacks list --filter STATUS=deployed

# Фильтр по namespace
imgctl stacks list --filter NAMESPACE=production

# Фильтр по имени (регулярное выражение)
imgctl stacks list --filter NAME~database

# Вывод без заголовков
imgctl stacks list --no-headers

# Детальная информация о стеке
imgctl stacks get database@production

Шаблон деплоя стека

Показывает содержимое шаблона (.tpl): объявленные параметры, задачи img.TASK, сервисы swarm.SERVICE. В MCP — инструмент templates_get.

Параметры

  • STACK_SPEC — stack@namespace, stack@namespace:tag или stack@namespace + отдельный COMMIT
  • --diff — сравнить текущий шаблон стека с шаблоном для указанного COMMIT (commit обязателен)
  • --no-cache, --no-headers, --verbose

Примеры

# Шаблон текущего развёрнутого стека
imgctl stacks template database@production

# Шаблон для конкретного тега (commit извлекается из тега)
imgctl stacks template database@production:dev__2025_01_15_10_00-abc1234

# Diff текущего шаблона с другим commit
imgctl stacks template database@production abc1234 --diff

Управление компонентами

Команды для управления компонентами развертываний.

Формат имен

Компоненты связаны со стеками в формате stack@namespace. В поле STACK отображается идентификатор стека в этом формате.

Доступные команды

  • imgctl components list - список компонентов
  • imgctl components get <name> - детальная информация о компоненте
  • imgctl components start <name> - запуск компонента
  • imgctl components stop <name> - остановка компонента
  • imgctl components upgrade - обновление компонентов
  • imgctl components tags <name> - список тегов компонента
  • imgctl templates params <target> - параметры шаблона (компонент или stack@namespace)
  • imgctl templates params-changelog <component> [component …] - история изменений PARAM (несколько имён за один вызов)
  • imgctl templates changelog <component> - git-коммиты файла шаблона
  • imgctl templates get <target> - полный шаблон (компонент или stack@namespace)
  • imgctl logs <name> - просмотр логов компонента

Параметры components get

  • --output / -o — только json или yaml: одна запись в stdout вместо развёрнутого вывода; без флага — прежний текстовый вид
  • --no-cache — не использовать кэш при запросе
  • --verbose / -v — подробный вывод HTTP-запросов

Доступные столбцы для list

  • NAME: Имя компонента
  • NAMESPACE: Пространство имен
  • STACK: ID стека (в формате stack@namespace)
  • IMAGE: Образ Docker
  • TAG: Тег образа
  • IP: IP-адрес ноды из tasks
  • NODE: Имя ноды из tasks
  • STACK_VERSION: Версия стека
  • STATUS: Статус компонента
  • REPLICAS: Количество реплик
  • PORTS: Маппинг портов
  • UPDATED: Дата обновления
  • CREATED: Дата создания
  • REPO: Репозиторий
  • COMMIT: Git коммит
  • ADMIN_MODE: Режим администратора
  • RUN_APP: Запуск приложения
  • SHOW_ADMIN_MODE: Показ режима администратора
  • OFF: Выключен
  • VOLUMES: Тома
  • NETWORKS: Сетевые подключения
  • LABELS: Метки
  • ENV: Переменные окружения (строка)
  • ENV.<переменная>: Динамические переменные окружения
  • PARAMS: Параметры стека (строка ключ=значение, …); у всех компонентов одного стека в строке совпадают с параметрами этого стека
  • PARAMS.<параметр>: Отдельный динамический столбец по имени параметра стека

По умолчанию: NAME, IP, PORTS, TAG, UPDATED, STATUS

Статусы компонентов

  • RUNNING: Компонент работает (все реплики запущены) - зеленый
  • STOPPED: Компонент остановлен - серый
  • STARTING: Компонент запускается - желтый
  • PARTIAL: Частично работает (запущено меньше реплик чем желается) - желтый
  • OFF: Компонент выключен - серый
  • BROKEN: Компонент сломан (несоответствие версий между component и task) - желтый
  • CANCELED: Операция отменена - красный

Sidecar-контейнеры

Sidecar — дополнительный контейнер в том же стеке, у которого своё <имя_sidecar_компонента> (часто служебные роли вроде логирования; пример: logstash-web-api-staging рядом с web-api-staging). Контейнеры checker-* к sidecar не относятся.

  • components list: по умолчанию sidecar не показываются. Флаг --include-sidecars включает их в вывод; в табличном режиме строки sidecar слегка приглушены (italic + dim), чтобы отличать от основных сервисов. В json/yaml/tsv служебные поля не добавляются.
  • components upgrade: sidecar не обновляются — они не попадают в план ни без аргументов, ни при --filter, ни при загрузке из файла, ни при явном указании имени; такие записи пропускаются с сообщением в консоли. Отдельной опции «показать sidecar в upgrade» нет.

Параметры components list

  • --columns <COLUMNS> - список столбцов для отображения
  • --filter <FILTER> - фильтр данных
  • --include-sidecars - показать sidecar-контейнеры (по умолчанию скрыты)
  • --no-headers - не показывать заголовки
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)
  • --limit <N> - ограничить количество записей
  • --no-cache - не использовать кэш

Параметры components upgrade

  • <component>[:tag] - имена компонентов для обновления (по умолчанию обновляются все)
  • --filter <FILTER> - фильтр компонентов для обновления
  • --to-tag <TAG> - обновить до указанного тега
  • --from-file <FILE> - загрузить список обновлений из файла
  • --dry-run - предварительный просмотр без выполнения
  • --output / -o - формат вывода плана: json, yaml, tsv (NAME/CURRENT_TAG/NEW_TAG)
  • --redeploy - полный редеплой стека: undeploy + deploy с новым тегом в параметрах, затем смена образа
  • --param KEY=VALUE - переопределить параметр стека при редеплое (повторяйте для нескольких; KEY= удаляет параметр; автоматически включает --redeploy)
  • --confirm - подтвердить обновления без запроса (только с фильтрами)
  • --force - принудительное обновление без проверки доступности тега
  • --no-cache - не использовать кэш
  • --verbose - подробный вывод HTTP запросов

Новые обязательные параметры и валидация --param

При одиночном обновлении (imgctl components upgrade <name>:<tag> без --filter и --from-file):

  • Если в шаблоне нового тега появились обязательные PARAM без значения по умолчанию, CLI автоматически включает --redeploy и интерактивно запрашивает значения (если они не переданы через --param).
  • Перед upgrade выполняется валидация --param: неизвестный ключ — ошибка; значение вне values или не по regexp — предупреждение.

Рекомендуемый порядок: templates params <name> → при необходимости templates params-changelog <name> […] → components upgrade ... --dry-run → upgrade с --param.

Примеры

# Список компонентов
imgctl components list

# Список со всеми контейнерами стека, включая sidecar
imgctl components list --include-sidecars

# Список с дополнительными столбцами
imgctl components list --columns "NAME,NAMESPACE,STACK,CREATED,REPO,COMMIT,PORTS"

# Фильтр по имени
imgctl components list --filter NAME~web-api-

# Фильтр по namespace
imgctl components list --filter NAMESPACE=production

# Фильтр по статусу
imgctl components list --filter STATUS=RUNNING

# Детальная информация о компоненте
imgctl components get web-api-staging

# Детальная информация без кэша
imgctl components get web-api-staging --no-cache

# Запуск компонента
imgctl components start web-api-staging

# Остановка компонента
imgctl components stop web-api-staging

# Обновление всех компонентов до последних тегов (по умолчанию)
imgctl components upgrade

# Обновление одного компонента до последнего тега
imgctl components upgrade web-api-staging

# Обновление до конкретного тега
imgctl components upgrade web-api-staging:v1.2.3

# Обновление нескольких компонентов
imgctl components upgrade web-api-staging db-staging:latest

# Обновление из файла (tab-separated формат)
imgctl components upgrade --from-file upgrades.txt

# Массовое обновление с фильтрами
imgctl components upgrade --filter NAME~^web-api- --to-tag v1.2.3

# Обновление всех компонентов в namespace staging до latest
imgctl components upgrade --filter NAMESPACE=staging --to-tag latest

# Обновление всех RUNNING компонентов
imgctl components upgrade --filter STATUS=RUNNING --to-tag v1.2.3

# Предварительный просмотр без выполнения
imgctl components upgrade --filter NAME~^web-api- --to-tag v1.2.3 --dry-run

# Подтверждение без интерактивного запроса
imgctl components upgrade web-api-staging --confirm
imgctl components upgrade --filter STATUS=RUNNING --to-tag v1.2.3 --confirm

# Принудительное обновление без проверки доступности тега
imgctl components upgrade --filter NAME~^web-api- --to-tag v1.2.3 --force

# Полный редеплой стека (undeploy + deploy + смена образа)
imgctl components upgrade web-api-staging:v1.2.3 --redeploy

# Редеплой с изменением параметра стека
imgctl components upgrade web-api-staging:v1.2.3 --param DB_HOST=new-db.example.com

# Редеплой с несколькими параметрами и удалением одного
imgctl components upgrade web-api-staging:v1.2.3 --param DB_HOST=new-db --param OLD_PARAM=

# Машиночитаемый план обновлений (JSON)
imgctl components upgrade --dry-run --output json

# TSV: NAME\tCURRENT_TAG\tNEW_TAG
imgctl components upgrade --dry-run --output tsv

Просмотр логов

Команда для просмотра логов компонентов.

Доступные команды

  • imgctl logs <component_name> - просмотр логов компонента

Параметры

  • component_name - имя компонента
  • --browser, -b - открыть логи в браузере
  • --follow, -f - следить за логами в реальном времени
  • --lines, -n <N> - количество строк логов (по умолчанию: 50)
  • --tail, -t <N> - количество последних записей для показа
  • --no-cache - отключить кэширование
  • --no-headers - не показывать заголовок консоли
  • --verbose, -v - подробный вывод HTTP запросов

Примеры

# Показать последние 50 строк логов
imgctl logs web-service-production

# Открыть логи в браузере
imgctl logs web-service-production --browser

# Показать последние 100 строк
imgctl logs web-service-production --lines 100

# Следить за логами в реальном времени
imgctl logs web-service-production --follow

# Показать последние 20 записей
imgctl logs web-service-production --tail 20

# Просмотр логов без кэша
imgctl logs web-service-production --no-cache

Управление реестрами

Команды для управления реестрами образов.

Доступные команды

  • imgctl registries list - список реестров

Параметры registries list

  • --no-headers - не показывать заголовки
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)

Примеры

# Список реестров
imgctl registries list

# Список реестров без заголовков
imgctl registries list --no-headers

Управление репозиториями

Команды для управления репозиториями образов.

Доступные команды

  • imgctl repositories list - список репозиториев

Параметры repositories list

  • --no-headers - не показывать заголовки
  • --output <FORMAT> - формат вывода (table, json, yaml, tsv)

Примеры

# Список репозиториев
imgctl repositories list

# Список репозиториев без заголовков
imgctl repositories list --no-headers

Управление тегами развертываний

Команда для просмотра доступных тегов для компонента.

Доступные команды

  • imgctl components tags <name> - список тегов компонента

Параметры

  • <name> - имя компонента (например, "web-api-staging")
  • --limit <N> - ограничить количество записей
  • --no-cache - не использовать кеш

Примеры

# Список тегов развертываний для компонента
imgctl components tags web-api-staging

# Список тегов с ограничением количества
imgctl components tags web-api-staging --limit 10

# Список тегов без кэша (принудительное обновление)
imgctl components tags web-api-staging --no-cache

Команда автоматически извлекает репозиторий и образ из информации о компоненте. Используется двухуровневое кэширование: информация о компоненте кэшируется на 1 час, теги на 5 минут.

Параметры шаблона стека компонента

Три разных источника про PARAM — не путать:

Источник Что показывает
imgctl components get <name> → поле PARAMS Текущие задеплоенные значения стека
imgctl templates params <target> Что объявлено в шаблоне (компонент или stack@namespace)
imgctl templates params-changelog <component> […] История изменений PARAM по тегам (один или несколько компонентов)
imgctl templates changelog <component> Git-коммиты файла шаблона (любые правки .tpl)

Алиасы imgctl components params|params-changelog|template-history и imgctl stacks template — deprecated.

Команда components params — просмотр объявлений в шаблоне стека, к которому привязан компонент.

Доступные команды

  • imgctl components params <name> - параметры шаблона стека компонента

Параметры

  • <name> - имя компонента
  • --param <PATTERN> - фильтр параметров: точное имя (DB_HOST), подстрока (PASSWORD) или regex (~^CONFIG_)
  • --no-cache - не использовать кэш
  • --no-headers - не показывать заголовок
  • --output <FORMAT> - формат вывода (json, yaml)

Примеры

# Параметры шаблона компонента
imgctl components params web-api-staging

# Только параметры с PASSWORD в имени
imgctl components params web-api-staging --param PASSWORD

# Без кэша (актуальная версия шаблона)
imgctl components params web-api-staging --no-cache

# JSON для автоматизации
imgctl components params web-api-staging --output json

Таблица показывает: NAME, TYPE, DEFAULT (с цветовой подсветкой по типу), REQUIRED, DESCRIPTION. Столбец DEFAULT: boolean — жёлтый, port — циан, tag — подсветка Imagenarium-тега, password — маска ••••••.

История изменений параметров шаблона

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

Сравнение идёт внутри серии тега (STABLE_RELEASE_4.63, dev), а не по общему календарю: первый тег серии 4.63 сравнивается с последним тегом 4.62, следующие — с предыдущим тегом той же серии.

Доступные команды

  • imgctl templates params-changelog <name> [name …] - история изменений параметров шаблона (один или несколько компонентов)

Параметры

  • <name> — одно или несколько имён компонентов (не stack@namespace)
  • --since-days <N> - глубина в днях (по умолчанию 7)
  • --since <YYYY-MM-DD> - начало диапазона (переопределяет --since-days)
  • --since-tag <TAG> - начальный тег как baseline (все теги новее него входят в диапазон)
  • --since-version <VER> - stable ≥ VER и dev с фриза предыдущего релиза (последний stable до первого тега VER)
  • --param <PATTERN> - фильтр параметров: точное имя (DB_HOST), подстрока (PASSWORD) или regex (~^CONFIG_)
  • --summary - только итоговый diff за период (без построчного changelog)
  • --no-cache - не использовать кэш
  • --no-headers - не показывать заголовок
  • --output <FORMAT> - формат вывода (json, yaml)

Примеры

# Что менялось за последние 7 дней
imgctl templates params-changelog web-api-staging

# Несколько компонентов за один период (релиз → компонент → теги)
imgctl templates params-changelog web-api-staging oms-api-web --since-version 4.63

# За последние 30 дней
imgctl templates params-changelog web-api-staging --since-days 30

# С конкретной даты
imgctl templates params-changelog web-api-staging --since 2025-08-01

# С конкретного тега как baseline
imgctl templates params-changelog web-api-staging --since-tag STABLE_RELEASE_4.62__2025_01_01_12_00-abc1234

# Что изменилось в серии релиза 4.63
imgctl templates params-changelog web-api-staging --since-version 4.63

# История конкретного параметра
imgctl templates params-changelog web-api-staging --param DB_HOST

# Все параметры с PASSWORD в имени
imgctl templates params-changelog web-api-staging --param PASSWORD

# Regex: параметры начинающиеся на CONFIG_
imgctl templates params-changelog web-api-staging --param '~^CONFIG_'

# Только итог за период
imgctl templates params-changelog web-api-staging --summary

# За 14 дней (при интенсивном dev-потоке)
imgctl templates params-changelog web-api-staging --since-days 14

# JSON с полными данными
imgctl templates params-changelog web-api-staging --output json

Вывод в терминале — секции по релизу (4.62, dev, …); при нескольких компонентах внутри релиза — подзаголовок компонента (имя как в components list: база + приглушённый -namespace), затем тег, дата, автор и строки +/-/~. Сравнение внутри серии тега (без ложных +/- на границе stable, если изменение уже было в dev). С --param сначала один git log -S по шаблону — полный diff только для релевантных тегов (см. Note: в выводе). Предупреждения о неполном git — с -v. Частичные сбои по отдельным именам — в notes[] (CLI: строки Note:).

JSON-ответ (та же обёртка, что у templates changelog):

Поле Смысл
components[], stack, period список имён (даже для одного), стек, границы (since, since_ref, to_tag, to_date)
changelog[] шаги: kind=params_diff (tag, release, added/removed/changed; при нескольких компонентах — component) или kind=template_commit (commit)
summary net-эффект PARAM за период; у каждого параметра в added/removed/changed — поле components (где менялось)
tags_in_range, tags_analyzed тегов в периоде / пар сравнения (у changelog: commits / 0)
warnings[], notes[] неполный git, пропущенные пары; notes[] — «имя: причина» при ошибке по одному из targets

Работает только со стандартными Imagenarium-тегами (формат dev__YYYY_MM_DD_HH_MM-commit). Верхняя граница — текущий задеплоенный тег компонента.

Git-репозиторий стека: история строится из локального git-клона (полный список тегов и diff шаблонов; API не отдаёт старые релизные серии). Для корректного baseline нужны теги предыдущего релиза (например 4.62 при анализе 4.63) — при их отсутствии в clone будет предупреждение и урезанный baseline. Первый запуск может потребовать сеть (clone/fetch). Пустой changelog[] при успехе — «PARAM не менялись», не сбой git.

История изменений шаблона

Команда для просмотра коммитов, затрагивавших файл шаблона стека компонента — любые изменения: параметры, задачи, сервисы, env, порты, volumes, constraints, FreeMarker-логику и т.д.

В отличие от params-changelog (только PARAM), templates changelog показывает все коммиты в файле .tpl.

Доступные команды

  • imgctl templates changelog <component> — коммиты в шаблон за период

Параметры

  • <component> — имя компонента (не stack@namespace)
  • --since-days <N> — глубина в днях (по умолчанию 30); при отсутствии тегов старше периода — с самого старого тега в git
  • --limit <N> - макс. коммитов в выводе (по умолчанию 50)
  • --no-cache - принудительный git fetch перед анализом
  • --output <FORMAT> - формат вывода (json, yaml)

Примеры

imgctl templates changelog web-api-staging
imgctl templates changelog web-api-staging --since-days 90 --limit 100
imgctl templates changelog web-api-staging --since-days 2000 --limit 500
imgctl templates changelog web-api-staging --output json

Вывод — секции по релизу (как у params-changelog): hash, дата, автор, subject. JSON: kind=template_commit, поле commit. Алиас: imgctl components template-history (deprecated).

Прогрев кеша (служебно)

После «холодного» params-changelog (>2 с) кеш того же репозитория прогревается автоматически.

Ручной массовый прогрев (команда скрыта из help и TAB, но доступна):

imgctl templates cache-warm
imgctl templates cache-warm --repo my-repo --since-days 30

Алиас: imgctl components cache-warm (deprecated).

Интерактивная оболочка (REPL)

Команда для запуска интерактивной оболочки imgctl (REPL режим).

Доступные команды

  • imgctl shell - запустить интерактивную оболочку
  • imgctl shell <server> - запустить с указанием сервера

Возможности shell

  • Автодополнение: полное автодополнение команд, опций и имен ресурсов по Tab
  • История команд: сохранение истории между сессиями в ~/.imgctl_history
  • Цветовой промпт: динамический промпт с именем консоли и цветом из конфигурации
  • Фоновое обновление кэша: автоматическое обновление кэша в фоне для быстрого автодополнения
  • Быстрые команды: exit, quit, help, clear
  • Сохранение контекста: все команды выполняются в контексте shell

Параметры

  • <server> - имя сервера для использования (опционально)
  • Свертывающееся меню автодополнения не отображается
  • История команд работает между сессиями

Примеры

# Запуск shell с текущим сервером
imgctl shell

# Запуск shell с указанием сервера dev
imgctl shell dev

# Запуск shell с сервером stage
imgctl shell stage

Использование внутри shell

# Вход в shell (промпт содержит имя консоли из конфигурации)
$ imgctl shell
dev> 

# Выполнение команд внутри shell
dev> components list
dev> components get web-api-staging
dev> nodes list --filter STATUS=READY

# Использование автодополнения (Tab)
dev> components get web-api-<TAB>
# → web-api-staging web-api-production

# Быстрые команды
dev> help          # Показать справку
dev> clear         # Очистить экран
dev> exit          # Выйти из shell
dev> quit          # Выйти из shell

Особенности

  • Без выпадающего меню: автодополнение по Tab без визуального меню
  • Цветовой промпт: показывает имя консоли из конфигурации сервера
  • Фоновое обновление: кэш компонентов обновляется в фоне для актуального автодополнения
  • История команд: используйте стрелки вверх/вниз для навигации по истории
  • Контекст сервера: при указании сервера все команды выполняются в его контексте

Кэширование в shell

  • Компоненты кэшируются на 5 минут для быстрого автодополнения
  • Кэш автоматически обновляется в фоне
  • Принудительное обновление: используйте --no-cache внутри команд

MCP-сервер

MCP (Model Context Protocol) — открытый протокол интеграции AI-агентов с инструментами. imgctl mcp запускает FastMCP-сервер по stdio-транспорту, который позволяет Claude Desktop, Cursor, OpenCode и другим AI-агентам управлять контейнерной платформой Imagenarium напрямую из чата.

Запуск

imgctl mcp

Параметры

Параметр По умолчанию Описание
--transport stdio Транспорт: stdio (локально), sse или http (удалённо)
--host 127.0.0.1 Хост для sse/http-транспорта
--port 8080 Порт для sse/http-транспорта
--server все из конфига Имя стенда (можно указать несколько раз)
--refresh-interval 5 Интервал фонового обновления кэша в секундах

Выбор серверов (приоритет по убыванию):

  1. imgctl mcp --server prod --server staging — явные стенды
  2. imgctl --server prod mcp — глобальный --server (один стенд)
  3. imgctl mcp — все серверы из servers.json

Сервер по умолчанию — тот, у которого установлен флаг is_default (imgctl servers set-default), иначе первый из списка. Сервер работает в async-режиме: фоновый поток обновляет кэш каждые N секунд, поэтому все операции чтения (components_list, stacks_list и т.д.) возвращают данные мгновенно без ожидания сети.

Доступные инструменты (tools)

Инструмент Описание
components_list Список развёрнутых компонентов (фильтры, namespace, sidecar, limit)
components_get Детальная информация о компоненте по имени
components_start Запустить компонент (асинхронно)
components_stop Остановить компонент (асинхронно)
components_upgrade Обнаружение версий, план обновления или деплой — одиночный и массовый
components_tags Список доступных тегов для компонента (от новых к старым)
templates_get Полный шаблон (params, tasks, services, content); target: компонент или stack@namespace
templates_params Объявления PARAM в шаблоне; target: компонент или stack@namespace
templates_params_changelog История PARAM по тегам; targets: список имён компонентов (один = ["name"]); changelog, summary, components[]
templates_changelog Git-коммиты файла шаблона; target: только компонент
stacks_list Список стеков развёртываний (фильтры, namespace, limit)
stacks_get Детальная информация о стеке
stacks_deploy Задеплоить стек в namespace
nodes_list Список нод кластера (фильтры по STATUS, ROLE, AVAILABILITY)
nodes_get Детальная информация о ноде
registries_list Список реестров образов
repositories_list Список Git-репозиториев
logs_get Последние N строк логов компонента (по умолчанию 50, максимум 500)
servers_list Список настроенных серверов Imagenarium с URL и флагом дефолтного

components_upgrade поддерживает три режима:

  • Обнаружение (dry_run=True, без tag): текущий тег + последний доступный + флаг upgradable
  • План (dry_run=True + tag): preview изменений без выполнения
  • Деплой (tag, dry_run=False): одиночный (name) или массовый (namespace/filters)

Дополнительно при деплое:

  • redeploy=True — полный редеплой стека (undeploy + deploy + смена образа); требует явного подтверждения пользователя
  • params={"KEY": "value", "OLD_KEY": null} — переопределить параметры стека; null удаляет ключ; автоматически включает redeploy=True
  • при новых обязательных PARAM в шаблоне тега — ответ error: new_params_required и список new_params (только для одиночного name)

Параметры шаблона в MCP: components_get → PARAMS (задеплоено); templates_params / templates_get (target: компонент или stack@namespace) → объявления в шаблоне; templates_params_changelog (targets: ["имя", …], не stack@namespace) и templates_changelog (один компонент) → история по git-тегам образа. Для «что менялось с версии X» собирай targets через components_list с filters/columns, не полным перебором стенда (см. instructions MCP).

Формат ответов

Все инструменты возвращают данные в том же формате, что --output json в CLI: ключи в UPPER_CASE (NAME, STATUS, NAMESPACE и т.д.), вложенные объекты для ENV и PARAMS. Это обеспечивает единую конвенцию при работе вручную через CLI и через AI-агента.

Локальная настройка (один стенд, stdio)

Самый простой вариант: MCP-сервер запускается локально как дочерний процесс AI-агента.

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "imgctl": {
      "command": "imgctl",
      "args": [
        "--server",
        "production",
        "mcp"
      ]
    }
  }
}

Расположение файла конфигурации:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Если imgctl установлен в виртуальное окружение, укажите полный путь к исполняемому файлу:

{
  "mcpServers": {
    "imgctl": {
      "command": "/path/to/venv/bin/imgctl",
      "args": [
        "--server",
        "production",
        "mcp"
      ]
    }
  }
}

Удалённый сервер с несколькими стендами

Настройте серверы на удалённом хосте через imgctl servers add, затем запустите MCP-сервер. Без --server автоматически подключаются все настроенные стенды:

# Все серверы из конфига
imgctl mcp --transport http --host 0.0.0.0 --port 8080

# Или явно выбранные
imgctl mcp --transport http --host 0.0.0.0 --port 8080 \
  --server prod --server staging --server dev

Подключитесь из Claude Desktop или Cursor по URL (формат mcpServers):

{
  "mcpServers": {
    "imgctl": {
      "url": "http://remote-host:8080/mcp"
    }
  }
}

В OpenCode используйте type: "remote" (см. Настройка OpenCode ниже).

AI-агент видит список доступных серверов в системном промпте и передаёт нужный стенд через параметр server в каждом инструменте. Если server не указан — используется дефолтный стенд.

Настройка Cursor (локально)

Создайте .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "imgctl": {
      "command": "imgctl",
      "args": [
        "--server",
        "production",
        "mcp"
      ]
    }
  }
}

Настройка OpenCode

OpenCode подключает MCP через файл opencode.json в корне проекта (или глобально в ~/.config/opencode/opencode.json). Документация: MCP servers.

Локальный stdio (рекомендуется)

imgctl mcp запускается как дочерний процесс OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imgctl": {
      "type": "local",
      "command": ["imgctl", "--server", "production", "mcp"],
      "enabled": true
    }
  }
}

Если imgctl не в PATH, укажите полный путь к исполняемому файлу, например "/path/to/venv/bin/imgctl".

Переменные окружения Imagenarium (альтернатива --server):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imgctl": {
      "type": "local",
      "command": ["imgctl", "mcp"],
      "enabled": true,
      "environment": {
        "IMG_SERVER": "production",
        "IMG_USERNAME": "admin",
        "IMG_PASSWORD": "secret"
      }
    }
  }
}

Удалённый HTTP

Если MCP-сервер запущен на другой машине (imgctl mcp --transport http --host 0.0.0.0 --port 8080):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imgctl": {
      "type": "remote",
      "url": "http://remote-host:8080/mcp",
      "enabled": true
    }
  }
}

Проверка: opencode mcp list — сервер imgctl должен быть в списке. Инструменты MCP появляются с префиксом имени сервера (например imgctl_components_list).

Скилл

Скопируйте skills/imgctl/SKILL.md из репозитория в каталог скиллов OpenCode:

  • проект: .opencode/skills/imgctl/SKILL.md
  • глобально: ~/.config/opencode/skills/imgctl/SKILL.md

Либо подключите файл через instructions в opencode.json (если скилл лежит вне стандартных путей):

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["skills/imgctl/SKILL.md"]
}

Скилл для AI-агентов

Файл skills/imgctl/SKILL.md — компактный справочник всех команд CLI и MCP-инструментов. Скопируйте его в нужную папку агента:

  • Claude Code (проект): .claude/skills/imgctl.md в корне репозитория
  • Claude Code (глобально): ~/.claude/skills/imgctl.md
  • Cursor (проект): .cursor/skills/imgctl.md в корне репозитория
  • Cursor (глобально): ~/.cursor/skills/imgctl.md
  • OpenCode (проект): .opencode/skills/imgctl/SKILL.md
  • OpenCode (глобально): ~/.config/opencode/skills/imgctl/SKILL.md

Скилл содержит: команды CLI с примерами, синтаксис фильтров (~СУФФИКС=, ~ШАБЛОН~), описание MCP-инструментов и три режима components_upgrade.

Примеры использования с AI-агентом

После настройки AI-агент может выполнять запросы на естественном языке:

  • «Покажи все компоненты в namespace production со статусом RUNNING»
  • «Обнови web-api-staging до тега v2.1.0»
  • «Покажи последние 100 строк логов database-production»
  • «Какие теги доступны для компонента web-api-staging?»
  • «Останови компонент worker-staging»
  • «Какие параметры шаблона есть у web-api-staging и какие из них обязательные?»
  • «Что менялось в параметрах шаблона web-api-staging за последние 2 недели?»
  • «Когда появился параметр DB_HOST у web-api-staging?»
  • «Когда последний раз менялся шаблон web-api-staging?»
  • «Кто трогал шаблон за последний месяц?»

Заголовок консоли

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

Формат заголовка

᪣ Imagenarium: NEW PRE-PROD                                             v3.2.1
  • Левая часть: ᪣ Imagenarium: {consoleName} - название консоли из конфигурации
  • Правая часть: v{version} - версия системы
  • Цвет: Заливка цветом consoleColor из конфигурации сервера
  • Адаптивность: Цвет текста автоматически адаптируется под фон терминала (черный для светлых терминалов, белый для темных)
  • Ширина: Растягивается на всю ширину терминала
  • Совместимость: Автоматически определяет тип терминала и его цветовую схему

Управление отображением

Заголовок автоматически скрывается в следующих случаях:

# Отключение заголовка и заголовков колонок
imgctl components list --no-headers

# Программный вывод (JSON, YAML, TSV)
imgctl components list --output json
imgctl components list --output yaml
imgctl components list --output tsv

# Комбинированное использование
imgctl components list --no-headers --output json

Кэширование конфигурации

  • Конфиг консоли: Кэшируется на 24 часа для оптимизации производительности
  • Версия системы: Кэшируется на 1 час, но в заголовке консоли всегда получается актуальная версия
  • Fallback: При ошибках отображается заголовок по умолчанию

Использование в CI/CD

Docker образ для CI/CD

imgctl предоставляет готовый Docker образ для использования в CI/CD пайплайнах, что позволяет выполнять операции управления компонентами без установки Python окружения.

Получение Docker образа

# Официальный образ из GitLab Container Registry
docker pull registry.gitlab.com/koden8/imgctl:latest

# Или с Docker Hub (если опубликован)
docker pull your-org/imgctl:latest

GitLab CI/CD пример

Обновление компонентов в production

# .gitlab-ci.yml
stages:
  - deploy

deploy_production:
  stage: deploy
  image: registry.gitlab.com/koden8/imgctl:latest
  variables:
    IMG_SERVER: production
    IMG_USERNAME: $CI_DEPLOY_USER
    IMG_PASSWORD: $CI_DEPLOY_PASSWORD
  cache:
    paths:
      - .cache/imgctl/
  script:
    # Обновление компонента до новой версии
    - imgctl components upgrade my-app --to-tag $CI_COMMIT_TAG
  only:
    - tags
  when: manual

Примечание: Для ускорения работы в CI/CD рекомендуется использовать кеш GitLab CI для сохранения кеша imgctl между запусками. Кеш хранит клонированные Git репозитории и шаблоны, что значительно ускоряет повторные запуски.

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

# Подключение к серверу
IMG_SERVER=production                    # Имя сервера или URL
IMG_USERNAME=ci-user                     # Пользователь для CI
IMG_PASSWORD=secure-password             # Пароль (используйте GitLab Variables)

Безопасность

Используйте GitLab Variables для хранения паролей:

  • IMG_PASSWORD: secure-password (Masked)
  • IMG_USERNAME: ci-user (Protected)

Кэширование

imgctl использует SQLite-базу данных (~/.cache/imgctl/storage.db) для хранения кеша, настроек серверов и результатов анализа. WAL-режим обеспечивает конкурентный доступ.

Стратегия кэширования:

  • components list - TTL 5 секунд (быстрое обновление данных)
  • components get - TTL 5 секунд (быстрое обновление данных)
  • components start - поиск ID кэшируется на 1 час
  • components tags - информация о компоненте кэшируется на 1 час, теги на 5 минут
  • templates params / templates params-changelog — шаблоны кэшируются in-process (LRU, 1000 записей); Imagenarium-теги и commit-хэши иммутабельны и кэшируются без TTL; после первого git fetch автоматически загружаются шаблоны 20 последних тегов, поэтому повторные вызовы diff_templates на тех же тегах не делают subprocess
  • logs - поиск ID компонента кэшируется на 1 час
  • nodes, repositories, registries - без кэша (всегда свежие данные)

Параметр --no-cache:

Все команды, использующие кэш, поддерживают параметр --no-cache для принудительной инвалидации кэша и загрузки свежих данных:

# Принудительно загрузить свежие данные
imgctl components list --no-cache
imgctl components get web-api-staging --no-cache
imgctl components start web-api-staging --no-cache
imgctl components tags web-api-staging --no-cache
imgctl logs web-api-staging --no-cache

Управление кэшем:

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

Управление колонками

imgctl предоставляет гибкую систему управления отображаемыми колонками для всех команд list. Вы можете явно указать нужные колонки или модифицировать набор колонок по умолчанию.

Способы указания колонок

1. Явное указание (замена набором по умолчанию)

Указываете полный список колонок через запятую:

# Показать только имя и статус
imgctl components list --columns "NAME,STATUS"

# Несколько колонок
imgctl nodes list --columns "NAME,IP,ROLE,STATUS"
imgctl stacks list --columns "NAME,NAMESPACE,VERSION,STATUS,REPO"

2. Добавление/удаление колонок относительно набора по умолчанию

Используйте префиксы + для добавления и - для удаления:

# Добавить колонку REPLICAS к набору по умолчанию
imgctl components list --columns "+REPLICAS"

# Удалить колонку NAMESPACE из набора по умолчанию
imgctl components list --columns "-NAMESPACE"

# Добавить несколько колонок
imgctl components list --columns "+REPLICAS,+PORTS"

# Удалить несколько колонок
imgctl components list --columns "-UPDATED,-TAG"

# Комбинированное: добавить REPLICAS и удалить NAMESPACE
imgctl components list --columns "+REPLICAS,-NAMESPACE"

# Добавить STACK и REPLICAS
imgctl components list --columns "+STACK,+REPLICAS"

# Убрать UPDATED и STATUS
imgctl components list --columns "-UPDATED,-STATUS"

3. Колонки по части имени (~шаблон)

Иногда нужно вывести сразу несколько похожих столбцов (например все переменные, в имени которых есть PASSWORD), не перечисляя каждую. Для этого в списке после запятой указывают ~ и шаблон: подойдут все колонки из текущего набора, в имени которых есть совпадение с шаблоном (регистр букв не важен; если шаблон с ошибкой для «регулярного выражения», он обрабатывается как обычный текст). В режиме +/-: +~шаблон добавляет такие столбцы к набору по умолчанию, -~шаблон убирает их. Служебные поля _… и «дубли» вида env.*_raw / params.*_raw, когда уже есть основная колонка env.* / params.*, в подбор не попадают.

imgctl components list --columns "NAME,~PASSWORD"
imgctl components list --columns "+~PORT"

Доступные колонки по командам

Components

Колонки по умолчанию: NAME, IP, PORTS, TAG, UPDATED, STATUS

Доступные колонки:

  • NAME, NAMESPACE, STACK, IMAGE, TAG, IP, NODE, STACK_VERSION
  • STATUS, REPLICAS, PORTS, UPDATED, CREATED
  • REPO, COMMIT, ADMIN_MODE, RUN_APP
  • SHOW_ADMIN_MODE, OFF, VOLUMES, NETWORKS, LABELS
  • ENV, ENV.<переменная> (динамические переменные окружения)
  • PARAMS, PARAMS.<параметр> (параметры стека для строки компонента)

Nodes

Колонки по умолчанию: NAME, IP, ROLE, AVAILABILITY, STATUS

Доступные колонки:

  • NAME, IP, ROLE, AVAILABILITY, STATUS
  • DC, DOCKER_VERSION, TOTAL_MEMORY
  • SSH_PORT, SSH_USER, EXTERNAL_URL, ID

Stacks

Колонки по умолчанию: NAME, NAMESPACE, VERSION, STATUS

Доступные колонки:

  • NAME, NAMESPACE, VERSION, STATUS
  • REPO, COMMIT, TIME, TAG, PARAMS
  • COMPONENTS, PARAMS.<параметр> (динамические параметры)

Servers

Колонки по умолчанию: NAME, URL, USERNAME

Доступные колонки:

  • NAME, URL, USERNAME, DESCRIPTION, DEFAULT

Примеры использования

# Только имя и статус для быстрого просмотра
imgctl components list --columns "NAME,STATUS"

# Расширенный набор колонок
imgctl components list --columns "NAME,NAMESPACE,IMAGE,TAG,STATUS,REPLICAS,PORTS"

# Добавить REPLICAS к набору по умолчанию
imgctl components list --columns "+REPLICAS"

# Убрать TAG и NAMESPACE, оставить остальное
imgctl components list --columns "-TAG,-NAMESPACE"

# Полный набор для детального анализа
imgctl components list --columns "NAME,NAMESPACE,STACK,IMAGE,TAG,STATUS,REPLICAS,PORTS,UPDATED"

# Строки вывода без лишних деталей
imgctl components list --columns "NAME,IMAGE,TAG"
imgctl nodes list --columns "NAME,IP,STATUS"
imgctl stacks list --columns "NAME,NAMESPACE,STATUS"

# Показать переменные окружения для компонентов
imgctl components list --columns "+ENV"

# Показать конкретную переменную окружения
imgctl components list --columns "+ENV.DB_HOST,+ENV.DB_PORT"

Динамические колонки

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

Компоненты могут иметь динамические переменные окружения, доступные как отдельные колонки:

# Показать все переменные окружения
imgctl components list --columns "+ENV"

# Показать конкретные переменные
imgctl components list --columns "NAME,STATUS,+ENV.DB_HOST,+ENV.DB_PORT,+ENV.APP_NAME"

# Фильтрация по переменным окружения
imgctl components list --filter ENV.DB_HOST=localhost --columns "+ENV.DB_HOST"

Параметры стека (PARAMS)

У стека есть параметры деплоя; в stacks list они в колонках PARAMS и PARAMS.имя. Те же значения доступны в components list для каждой строки компонента (параметры общие для всего стека). Фильтры PARAMS~…, PARAMS.KEY=value работают так же, как для стеков.

# Показать все параметры (стеки)
imgctl stacks list --columns "+PARAMS"

# Показать конкретные параметры (стеки)
imgctl stacks list --columns "NAME,VERSION,+PARAMS.database,+PARAMS.version"

# Параметры стека в списке компонентов
imgctl components list --columns "NAME,STACK,+PARAMS"

# Конкретный параметр и фильтр
imgctl components list --columns "+PARAMS.database" --filter PARAMS~db

Сочетание с другими опциями

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

# Фильтр + выбор колонок
imgctl components list --filter STATUS=RUNNING --columns "NAME,STATUS,REPLICAS"

# Выбор колонок + JSON
imgctl components list --columns "NAME,STATUS" --output json

# Ограничение + колонки + фильтр
imgctl components list --limit 5 --columns "NAME,STATUS" --filter NAMESPACE=production

# Без заголовков + выбор колонок
imgctl components list --columns "NAME,STATUS" --no-headers

# YAML + выбор колонок
imgctl stacks list --columns "NAME,NAMESPACE,VERSION" --output yaml

Советы по использованию

  1. Быстрый просмотр: Используйте --columns "NAME,STATUS" для компактного вывода
  2. Добавление деталей: Используйте префикс + для добавления колонок к набору по умолчанию
  3. Минималистичный вывод: Используйте --columns "-TAG,-UPDATED" для упрощения
  4. Автоматизация: Комбинируйте с --no-headers --output json для скриптов
  5. Экспорт: Для программной обработки используйте фиксированный набор колонок

Примечание: Компоненты, начинающиеся с "monitor-", автоматически исключаются из вывода для упрощения отображения.

Форматы вывода

imgctl предоставляет комплексную систему форматирования вывода данных, обеспечивающую интеграцию с различными инструментами и системами.

Обзор поддерживаемых форматов

Система поддерживает следующие форматы вывода, оптимизированные для различных сценариев использования:

Формат Назначение Особенности
table Интерактивный просмотр Цветовое кодирование, адаптивная ширина
json Программная обработка Атрибуты в lowercase, структурированные данные
yaml Конфигурационные файлы Человекочитаемый формат, атрибуты в lowercase
tsv Экспорт без заголовков колонок Табуляция как разделитель, без заголовков
"{COLUMN}..." Пользовательские шаблоны Гибкое форматирование, синтаксис {NAME}

Детальное описание форматов

Табличный формат (по умолчанию)

  • Назначение: Интерактивный просмотр и анализ данных
  • Особенности:
    • Цветовое кодирование статусов и состояний
    • Адаптивная ширина под размер терминала
    • Визуальное выделение совпадений при фильтрации
    • Форматирование заголовков

JSON формат

  • Назначение: Программная обработка и интеграция с API
  • Особенности:
    • Атрибуты в lowercase для соответствия стандартам JSON
    • Полное удаление Rich markup для чистых данных
    • Структурированный формат для автоматизированной обработки
    • Совместимость с инструментами типа jq, yq

YAML формат

  • Назначение: Конфигурационные файлы и документирование
  • Особенности:
    • Человекочитаемый формат с отступами
    • Атрибуты в lowercase для стандартизации
    • Поддержка Unicode и специальных символов
    • Идеален для версионирования конфигураций

TSV формат

  • Назначение: Экспорт без заголовков колонок для автоматизированной обработки
  • Особенности:
    • Без заголовков колонок (только данные)
    • Табуляция как разделитель
    • Идеален для скриптов и автоматизации
    • Поддержка импорта в Google Sheets, LibreOffice

Пользовательские шаблоны

  • Назначение: Гибкое форматирование под специфические требования
  • Особенности:
    • Синтаксис {COLUMN} для простоты использования
    • Поддержка многострочных шаблонов с \n
    • UPPERCASE имена столбцов для консистентности
    • Полное удаление Rich markup в выводе

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

Сценарий 1: Программная обработка данных

# Получение данных в JSON формате для автоматизированной обработки
imgctl components list --output json --limit 5

# Фильтрация и обработка с помощью jq
imgctl components list --output json | jq '.[] | select(.status=="RUNNING")'

# Экспорт в файл для дальнейшего анализа
imgctl components list --output json > components.json

Сценарий 2: Конфигурационное управление

# Генерация YAML конфигурации для систем управления
imgctl stacks list --output yaml

# Создание конфигурационных файлов
imgctl servers list --output yaml > servers-config.yaml

Сценарий 3: Отчетность и аналитика

# Экспорт данных в TSV для автоматизированной обработки
imgctl nodes list --output tsv > infrastructure-report.tsv

# Создание отчетов с фильтрацией
imgctl components list --filter STATUS=RUNNING --output tsv > running-components.tsv

Сценарий 4: Пользовательские форматы вывода

# Простое форматирование для скриптов
imgctl components list --output "{NAME} - {STATUS}"

# Многострочные шаблоны для детальной информации
imgctl servers list --output "Server: {NAME}\nURL: {URL}\nDefault: {DEFAULT}"

# Комбинирование с фильтрацией
imgctl components list --filter NAMESPACE=production --output "{NAME}: {STATUS}"

Сценарий 5: Интеграция с системами

# Комбинирование фильтрации и форматирования
imgctl components list --filter STATUS=RUNNING --output json
imgctl stacks list --filter NAMESPACE=production --output yaml
imgctl nodes list --columns "NAME,IP,STATUS" --output tsv

Шаблоны (template формат):

Шаблоны используют синтаксис {COLUMN}, где COLUMN - имя столбца в UPPERCASE:

# Простой шаблон
--output "{NAME}: {STATUS}"

# Многострочный шаблон
--output "Component: {NAME}\nNamespace: {NAMESPACE}\nImage: {IMAGE}:{TAG}"

# С дополнительным текстом
--output "Component {NAME} in {NAMESPACE} is {STATUS}"

Фильтрация данных

Система фильтрации поддерживает следующие возможности:

  • Множественные фильтры: возможность применения нескольких условий одновременно
  • Визуальное выделение: автоматическая подсветка совпадающих результатов
  • Гибкие операторы: поддержка различных типов сравнения
  • Регулярные выражения: продвинутый поиск по шаблонам
  • Фильтры без полного имени колонки: когда колонка заранее неизвестна или их много — см. раздел ниже
  • Типизированные сравнения: автоматическое определение типов данных

Поддерживаемые операторы фильтрации

Оператор Описание Пример использования
= Точное совпадение STATUS=RUNNING
!= Не равно NAMESPACE!=test
~ Регулярное выражение NAME~database
> Больше (для дат/чисел) REPLICAS>1
< Меньше (для дат/чисел) UPDATED<2025-01-01
>= Больше или равно REPLICAS>=2
<= Меньше или равно UPDATED<=2025-12-31

Когда неизвестно точное имя колонки

Обычно пишут ИМЯ_СТОЛБЦА + оператор + значение (например NAME~^web- или STATUS=RUNNING). Дополнительно можно:

  1. Короткая запись «окончание имени» — ~конец=значение: в фильтре только одна тильда ~, и она в самом начале строки. Тогда ищется любая колонка, чьё имя заканчивается на указанный текст (без «магических» символов шаблона — это обычный хвост имени, например HOST подойдёт и к env.DB_HOST). После этого как обычно пишут =, !=, >=, ~ и т.д. Примеры: ~HOST=localhost, ~REPLICAS>=1.

  2. Полная запись «шаблон имени + условие» — ~часть_имени~…: между первой и второй ~ задаётся шаблон по полному имени колонки (как в регулярных выражениях); после второй ~ — значение и при необходимости оператор. Примеры: ~NAME~=точное-имя (точное равенство значения), ~env\..*PORT~8080. Если оператор после второй ~ не указан, к значению применяется тот же подход, что и в записи вида СТОЛБЕЦ~шаблон (поиск по шаблону в значении), например ~PASSWORD~secret.

Несколько --filter по-прежнему работают вместе как «и одновременно». Для переменных окружения и параметров стека (env.*, params.*) значение для сравнения берётся так же, как при обычных фильтрах по этим полям (по внутреннему «сырому» значению, а не по маске в таблице).

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

imgctl components list --filter "~HOST=localhost" --columns "+ENV.DB_HOST"
imgctl components list --filter "~PASSWORD~secret" --columns "NAME,~PASS"

Система визуального выделения совпадений

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

  • Оператор точного совпадения (=): выделяет весь текст при полном соответствии
  • Оператор регулярного выражения (~): выделяет только совпадающие фрагменты
  • Универсальность: работает со всеми типами столбцов (NAME, STATUS, NAMESPACE и др.) для всех команд (components, stacks, nodes и др.)
  • Цветовое кодирование: использует желтый цвет для оптимальной видимости
  • Сохранение базовой подсветки: основная подсветка статусов и имен сохраняется, совпадения фильтров подсвечиваются дополнительно

Примеры использования:

# Простые фильтры
imgctl components list --filter STATUS=RUNNING
imgctl components list --filter NAMESPACE=production
imgctl components list --filter NAME~database

# Исключение тестовых namespace
imgctl components list --filter NAMESPACE!=test

# Множественные фильтры
imgctl components list --filter STATUS=RUNNING --filter NAMESPACE=production

# Поиск по прокси (proxy компоненты)
imgctl components list --filter NAME~proxy

# Фильтрация по датам
imgctl components list --filter UPDATED>2025-01-01

# Фильтрация по числовым значениям
imgctl components list --filter REPLICAS>1

# Комбинирование с другими опциями
imgctl components list --filter STATUS=RUNNING --columns "NAME,STATUS" --limit 5

# Практические сценарии
imgctl components list --filter NAMESPACE=production --filter STATUS=RUNNING  # Все работающие компоненты в production
imgctl components list --filter NAME~api --filter NAMESPACE=production        # API компоненты в production
imgctl components list --filter STATUS=OFF                                 # Остановленные компоненты

# Примеры с подсветкой совпадений (в табличном выводе)
imgctl components list --filter NAME=database-production --columns NAME       # Подсветит "database-production"
imgctl components list --filter NAME~database --columns NAME               # Подсветит "database" в именах
imgctl components list --filter STATUS=RUNNING --columns NAME,STATUS       # Подсветит "RUNNING" в статусах
imgctl stacks list --filter NAME~api --columns NAME                        # Подсветит "api" в именах стеков
imgctl stacks list --filter STATUS=deployed --columns NAME,STATUS          # Подсветит "deployed" в статусах

Доступные колонки для фильтрации:

Список доступных колонок для фильтрации см. в разделе Управление колонками.

TTL кэширования

imgctl использует кэширование для ускорения работы:

TTL для команд:

  • components list - TTL 5 секунд (быстрое обновление данных)
  • components get - TTL 5 секунд (быстрое обновление данных)
  • components start - поиск ID кэшируется на 1 час
  • components tags - информация о компоненте кэшируется на 1 час, теги на 5 минут
  • templates params / templates params-changelog — in-process LRU без TTL для иммутабельных тегов
  • logs - поиск ID компонента кэшируется на 1 час
  • nodes, repositories, registries - без кэша (всегда свежие данные)

Параметр --no-cache:

Все команды, использующие кэш, поддерживают параметр --no-cache для принудительной инвалидации кэша и загрузки свежих данных:

# Принудительно загрузить свежие данные
imgctl components list --no-cache
imgctl components get web-api-staging --no-cache
imgctl components start web-api-staging --no-cache
imgctl components tags web-api-staging --no-cache
imgctl logs web-api-staging --no-cache

Управление кэшем:

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

Безопасность

imgctl реализует комплексные меры безопасности для защиты чувствительных данных и обеспечения безопасной работы с контейнерной платформой «Imagenarium».

Обзор безопасности

imgctl обрабатывает чувствительные данные, включая:

  • Cookies сессий для аутентификации
  • Кеш API запросов с потенциально чувствительной информацией
  • Конфигурацию серверов с учетными данными
  • Пароли для доступа к серверам

Все эти данные защищены многоуровневой системой безопасности.

Защита файлов данных

Расположение файлов

imgctl хранит данные в стандартных директориях согласно канонам операционных систем:

Linux/macOS:

  • Конфигурация: ~/.config/imgctl/
  • Кеш: ~/.cache/imgctl/

Windows:

  • Конфигурация: %APPDATA%/imgctl/
  • Кеш: %LOCALAPPDATA%/imgctl/cache/

Типы защищаемых файлов

Файл Содержимое Защита
servers.json Конфигурация серверов Права доступа + атомарная запись
cookies.json Cookies сессий Права доступа + атомарная запись
cache.json Кеш API запросов Права доступа + атомарная запись
cache_config.json Настройки кеширования Права доступа + атомарная запись

Меры безопасности

Права доступа к файлам

Директории:

  • 0o700 (rwx------) - только владелец может читать/писать/выполнять

Файлы:

  • 0o600 (rw-------) - только владелец может читать/писать

Атомарная запись файлов

  • Предотвращение повреждения файлов при сбоях
  • Исключение race conditions при одновременном доступе
  • Обеспечение консистентности данных
  • Использование временных файлов с последующим атомарным перемещением

Шифрование чувствительных данных

  • PBKDF2 с SHA-256 для генерации ключей
  • Fernet (AES 128 в CBC режиме) для симметричного шифрования
  • 100,000 итераций PBKDF2 для защиты от атак перебора
  • Уникальные ключи на основе данных пользователя и машины

Безопасное хранение паролей

  • Системный keyring для хранения паролей (macOS Keychain, Windows Credential Manager, SecretService) - используется автоматически если доступен
  • Автоматическое переключение на PlaintextKeyring из keyrings.alt.file при недоступности системного keyring
  • В контейнерах и окружениях без GUI:
    • Автоматически используется PlaintextKeyring (без пароля, без запросов)
    • Пароли хранятся в файле ~/.config/imgctl/keyring_pass.cfg (права доступа 600)
    • Защита обеспечивается правами файловой системы
    • Пароли сохраняются в base64-кодированном виде
  • Простота и надежность:
    • Минимальная зависимость от внешних библиотек
    • Автоматическое определение и использование доступного бэкенда
    • Работает везде: локально, в контейнерах, без дополнительных настроек

Рекомендации по безопасности

Для пользователей

  1. Регулярно обновляйте imgctl до последней версии
  2. Не передавайте файлы конфигурации другим пользователям
  3. Используйте сильные пароли для серверов
  4. Используйте параметр --no-cache при работе на общих машинах для принудительного обновления данных: 
    imgctl components list --no-cache
imgctl components get web-api-staging --no-cache

Для системных администраторов

  1. Мониторьте права доступа к директориям imgctl
  2. Настройте ротацию логов для отслеживания доступа
  3. Используйте SELinux/AppArmor для дополнительной защиты
  4. Регулярно проверяйте целостность файлов конфигурации

Проверка прав доступа

# Проверка прав доступа к директории кеша
ls -la ~/.cache/imgctl/
# drwx------ 2 user user 4096 Jan 15 10:00 .

# Проверка прав доступа к файлам
ls -la ~/.cache/imgctl/cache.json
# -rw------- 1 user user 1024 Jan 15 10:00 cache.json

Устранение проблем безопасности

Неправильные права доступа

Симптомы:

  • Ошибки доступа к файлам
  • Предупреждения о небезопасных правах

Решение:

# Исправление прав доступа к директории
chmod 700 ~/.cache/imgctl
chmod 700 ~/.config/imgctl

# Исправление прав доступа к файлам
chmod 600 ~/.cache/imgctl/*.json
chmod 600 ~/.config/imgctl/*.json

Поврежденные файлы

Симптомы:

  • Ошибки при загрузке конфигурации
  • Некорректная работа кеша

Решение:

# Удаление поврежденных файлов
rm ~/.cache/imgctl/cache.json
rm ~/.config/imgctl/servers.json

# Пересоздание конфигурации
imgctl servers add my-server --url https://example.com --username admin --password secret

Отладка проблем безопасности

# Включение подробного вывода для отладки
imgctl --verbose components list

# Проверка прав доступа
ls -la ~/.cache/imgctl/ ~/.config/imgctl/

# Проверка содержимого файлов (осторожно!)
file ~/.cache/imgctl/cache.json

Устранение неполадок

Проблемы с подключением

Ошибка: "Не удалось определить конфигурацию сервера"

# Решение: добавьте сервер
imgctl servers add dev --url http://your-server:5555 --username admin --password your-password
imgctl servers set-default dev

Ошибка: "Ошибка API: 401 Unauthorized"

# Решение: проверьте учетные данные
imgctl servers test dev
# Или обновите пароль
imgctl servers add dev --url http://your-server:5555 --username admin --password new-password

Ошибка: "Connection refused"

# Решение: проверьте URL сервера и доступность
curl -I http://your-server:5555

Ошибка: "No recommended backend was available" при сохранении пароля в контейнере

# Решение: imgctl автоматически использует PlaintextKeyring из keyrings.alt
# Все необходимые зависимости включены в пакет imgctl

# Проверьте что пароль сохранен:
ls -la ~/.config/imgctl/keyring_pass.cfg
# Файл должен существовать с правами 600

Проблемы с кэшем

Устаревшие данные в выводе команд

# Решение: принудительно обновите кэш
imgctl components list --no-cache
imgctl components get my-component --no-cache

Ошибка: "Компонент не найден в кэше"

# Решение: обновите кэш и повторите попытку
imgctl components list --no-cache
imgctl logs my-component --no-cache

Проблемы с логами

Логи не отображаются или показывают ошибку 404

# Решение: обновите кэш компонентов
imgctl logs my-component --no-cache

Медленная загрузка логов

# Решение: используйте фильтрацию или ограничение строк
imgctl logs my-component --lines 50
imgctl logs my-component --level ERROR

Проблемы с Bash Completion

Автодополнение не работает

# Решение: переустановите completion
./imgctl-completion.bash uninstall
./imgctl-completion.bash install
source ~/.bashrc

Автодополнение показывает устаревшие данные

# Решение: очистите кэш completion
rm -rf ~/.cache/imgctl/
./imgctl-completion.bash test

Отладка

Включите подробный вывод

imgctl --verbose components list

Проверьте конфигурацию

imgctl servers list
imgctl servers test dev

Bash Completion

imgctl поддерживает полное автодополнение для всех команд, параметров и имен ресурсов.

Установка completion

# Установить completion (по умолчанию в ~/.bashrc)
./imgctl-completion.bash install

# Установить в ~/.bashrc
./imgctl-completion.bash install --bashrc

# Установить в ~/.bash_profile
./imgctl-completion.bash install --profile

# Проверить установку
./imgctl-completion.bash test

# Удалить completion
./imgctl-completion.bash uninstall

# Показать справку
./imgctl-completion.bash help

Возможности completion

  • Команды и подкоманды: автодополнение всех команд
  • Параметры: все опции командной строки
  • Имена ресурсов: компоненты, стеки, ноды, серверы, репозитории, реестры
  • Колонки: для команд list с --columns
  • Кэширование: быстрая работа благодаря локальному кэшу
  • Работа в контексте сервера: через --server или переменные окружения
  • Скрытие служебных компонентов: компоненты, начинающиеся с monitor-

Примеры использования

# Автодополнение команд
imgctl <TAB>
# → servers nodes stacks components registries repositories logs

# Автодополнение компонентов
imgctl components get <TAB>
# → web-api-staging database-production ...

# Автодополнение параметров
imgctl components list --<TAB>
# → --limit --no-cache --columns --filter --no-headers ...

# Автодополнение с сервером
imgctl --server dev components get <TAB>
# → database-production cache-production ...

# Автодополнение с переменными окружения
IMG_SERVER=dev imgctl components get <TAB>
# → database-production cache-production ...

# Автодополнение колонок
imgctl components list --columns <TAB>
# → NAME NAMESPACE STACK IMAGE TAG STATUS ...

Кэширование

Completion использует кэширование для быстрой работы:

  • Кэш создается отдельно для каждого сервера
  • Данные кэшируются в ~/.cache/imgctl/<server_name>/
  • Кэш автоматически обновляется при необходимости
  • Поддерживает работу с переменными окружения IMG_SERVER, IMG_USERNAME, IMG_PASSWORD

Управление completion

./imgctl-completion.bash test      # Тестирование
./imgctl-completion.bash install   # Установка
./imgctl-completion.bash uninstall # Удаление
./imgctl-completion.bash help      # Справка

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for koden8 from gravatar.com koden8

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT License (non-commercial) / Commercial License)
  • Author: @koden8
  • Maintainer: @koden8
  • Tags docker , containers , orchestration , cli , imagenarium
  • Requires: Python >=3.8
  • Provides-Extra: dev
Classifiers

Release history Release notifications | RSS feed

This version

3.2.1

3.2.0

3.1.1

3.1.0

3.0.19

3.0.18

3.0.17

3.0.16

3.0.15

3.0.14

3.0.12

3.0.11

3.0.10

3.0.9

3.0.8

3.0.7

3.0.6

3.0.5

3.0.4

3.0.3

3.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imgctl-3.2.1.tar.gz (292.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

imgctl-3.2.1-py3-none-any.whl (256.5 kB view details)

Uploaded Python 3

File details

Details for the file imgctl-3.2.1.tar.gz.

File metadata

  • Download URL: imgctl-3.2.1.tar.gz
  • Upload date:
  • Size: 292.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.11.15

File hashes

Hashes for imgctl-3.2.1.tar.gz
Algorithm Hash digest
SHA256 e993b5ca6f331a7c1c0c34bebbfa5f2824d8213d71f14dd2a0ea4702dd8056e7
MD5 8f506ba427a83142fc95c9fe3cc0daac
BLAKE2b-256 ca939a7e9dd0ec62a3d9c3eb26854731ea9f3f4e91befd493e2d59e5b127e5cc

See more details on using hashes here.

File details

Details for the file imgctl-3.2.1-py3-none-any.whl.

File metadata

  • Download URL: imgctl-3.2.1-py3-none-any.whl
  • Upload date:
  • Size: 256.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.11.15

File hashes

Hashes for imgctl-3.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 93f8730628ab3e4f795c797ad32e25ae035c99428ddfdf50ff568c9fcc57ddf7
MD5 36701190aa4007ca58b8d91176e58475
BLAKE2b-256 22ac87b41d9a4cb09e9b00b883b7ce47e18982358055c01f93db062718f5543e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page