Skopeo Wrapper

Python библиотека-обертка для утилиты skopeo с поддержкой парсинга прогресса операций.

Возможности

• 🚀 Парсинг прогресса: Извлечение информации о ходе выполнения операций skopeo
• 📦 Операции с образами: Копирование, инспекция, удаление образов
• 🔄 Callback-функции: Возможность отслеживания прогресса в реальном времени
• ⚡ Асинхронный мониторинг: Неблокирующий мониторинг вывода skopeo
• 🛡️ Обработка ошибок: Корректная обработка ошибок и исключений
• 🖥️ CLI интерфейс: Консольный интерфейс для быстрого использования
• 📊 Prometheus метрики: Полная поддержка метрик для мониторинга
• 🌐 HTTP сервер метрик: Встроенный сервер для экспорта метрик
• 📈 Grafana дашборды: Готовые дашборды для визуализации

Установка

Требования

• Python 3.7+
• Утилита skopeo (установлена в системе)
• Рекомендуется: skopeo версии 1.18+ для лучшей совместимости

Установка skopeo

Быстрая установка (рекомендуемая версия)

# Ubuntu/Debian
sudo apt update && sudo apt install skopeo

# CentOS/RHEL
sudo yum install skopeo

# Fedora
sudo dnf install skopeo

Установка skopeo 1.18 из исходников

# Установка зависимостей
sudo apt install -y golang-go libgpgme-dev pkg-config

# Скачивание и сборка
wget https://github.com/containers/skopeo/archive/refs/tags/v1.18.0.tar.gz
tar -xzf v1.18.0.tar.gz
cd skopeo-1.18.0
make bin/skopeo
sudo cp bin/skopeo /usr/local/bin/skopeo

Установка библиотеки

Из PyPI (когда будет опубликована)

pip install skopeo-wrapper

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

# Клонирование репозитория
git clone https://github.com/your-username/skopeo-wrapper.git
cd skopeo-wrapper

# Установка в режиме разработки
pip install -e .

# Или установка зависимостей
pip install -r requirements.txt

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

Python API

Базовое использование

from skopeo_wrapper import SkopeoWrapper, create_progress_callback

# Создание экземпляра
skopeo = SkopeoWrapper()

# Копирование образа с отображением прогресса
success, stdout, stderr = skopeo.copy(
    source="docker://docker.io/library/alpine:latest",
    destination="dir:/tmp/alpine_image",
    progress_callback=create_progress_callback(show_progress=True)
)

if success:
    print("Копирование завершено успешно!")
else:
    print(f"Ошибка: {stderr}")

Детальный мониторинг прогресса

from skopeo_wrapper import SkopeoWrapper, ProgressInfo

def detailed_progress_callback(progress: ProgressInfo):
    print(f"Этап: {progress.current_step}")
    print(f"Прогресс: {progress.parser.get_progress_percentage():.1f}%")
    
    if progress.current_blob:
        print(f"Текущий blob: {progress.current_blob.sha256[:12]}...")
        if progress.current_blob.size:
            print(f"Размер: {progress.current_blob.size} bytes")

skopeo = SkopeoWrapper()
success, stdout, stderr = skopeo.copy(
    source="docker://docker.io/library/ubuntu:22.04",
    destination="dir:/tmp/ubuntu_image",
    progress_callback=detailed_progress_callback
)

Операции с образами

# Инспекция образа
success, image_info, stderr = skopeo.inspect(
    image="docker://docker.io/library/alpine:latest"
)

if success:
    import json
    info = json.loads(image_info)
    print(f"Архитектура: {info['Architecture']}")
    print(f"ОС: {info['Os']}")

# Получение digest манифеста
success, digest, stderr = skopeo.get_manifest_digest(
    image="docker://docker.io/library/alpine:latest"
)

if success:
    print(f"Digest: {digest.strip()}")

CLI интерфейс

# Копирование образа
skopeo-wrapper copy docker://alpine:latest dir:/tmp/alpine --progress

# Инспекция образа
skopeo-wrapper inspect docker://ubuntu:22.04 --json

# Удаление образа
skopeo-wrapper delete docker://alpine:latest

# Получение digest манифеста
skopeo-wrapper manifest-digest docker://nginx:alpine

# Запуск сервера метрик
skopeo-wrapper metrics-server --host localhost --port 8000

# Просмотр метрик
skopeo-wrapper metrics --format prometheus

# Справка
skopeo-wrapper --help

Prometheus метрики

Базовое использование метрик

from skopeo_wrapper import SkopeoWrapper

# Создание с включенными метриками (по умолчанию)
skopeo = SkopeoWrapper(enable_metrics=True)

# Выполнение операций
success, stdout, stderr = skopeo.copy(
    source="docker://alpine:latest",
    destination="dir:/tmp/alpine"
)

# Получение метрик
metrics = skopeo.get_metrics()
print(metrics)

Запуск сервера метрик

from skopeo_wrapper import start_metrics_server

# Запуск сервера метрик
server = start_metrics_server(host='localhost', port=8000)
print(f"Метрики доступны по адресу: {server.get_url()}/metrics")

# Остановка сервера
server.stop()

Детальное отслеживание операций

from skopeo_wrapper import SkopeoWrapper, OperationTracker

skopeo = SkopeoWrapper(enable_metrics=True)

# Использование OperationTracker для детального отслеживания
with OperationTracker("copy", skopeo.metrics, 
                     source="docker://alpine:latest",
                     destination="dir:/tmp/alpine") as tracker:
    
    # Имитация обработки blob'ов
    tracker.add_blob(1024000)  # 1MB
    tracker.add_blob(2048000)  # 2MB

Доступные метрики

• skopeo_operations_total - Общее количество операций по типам и статусам
• skopeo_operation_duration_seconds - Время выполнения операций
• skopeo_blobs_processed_total - Количество обработанных blob'ов
• skopeo_blob_size_bytes - Размеры blob'ов
• skopeo_active_operations - Текущие активные операции
• skopeo_operation_errors_total - Количество ошибок по типам
• skopeo_source_operations_total - Операции по типам источников
• skopeo_destination_operations_total - Операции по типам назначений

API Reference

SkopeoWrapper

Основной класс для работы с skopeo.

Методы

• copy(source, destination, progress_callback=None, timeout=None) - Копирование образа
• inspect(image, progress_callback=None, timeout=None) - Получение информации об образе
• delete(image, progress_callback=None, timeout=None) - Удаление образа
• get_manifest_digest(image, progress_callback=None, timeout=None) - Получение digest манифеста

Параметры

• source/destination/image - URL образа или путь
• progress_callback - Функция для обработки прогресса
• timeout - Таймаут операции в секундах

ProgressInfo

Информация о прогрессе операции.

Атрибуты

• operation - Тип операции
• current_step - Текущий этап выполнения
• current_blob - Информация о текущем blob
• manifest_written - Манифест записан
• signatures_stored - Подписи сохранены
• error - Сообщение об ошибке
• completed - Операция завершена

BlobInfo

Информация о blob-объекте.

Атрибуты

• sha256 - SHA256 хеш blob
• size - Размер в байтах
• status - Статус обработки

SkopeoMetrics

Класс для управления Prometheus метриками.

Методы

• record_operation_start(operation) - Записывает начало операции
• record_operation_end(operation, success, start_time, ...) - Записывает завершение операции
• record_error(operation, error_type) - Записывает ошибку операции
• record_blob_processed(operation, blob_size) - Записывает обработку blob'а
• get_metrics() - Возвращает метрики в формате Prometheus
• get_metrics_dict() - Возвращает метрики в виде словаря

OperationTracker

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

Методы

• add_blob(blob_size) - Добавляет информацию о blob'е

MetricsServer

HTTP сервер для экспорта метрик Prometheus.

Методы

• start() - Запускает сервер
• stop() - Останавливает сервер
• is_running() - Проверяет статус сервера
• get_url() - Возвращает URL сервера

Примеры вывода

Копирование образа (skopeo 1.18)

🔍 getting_signatures: 10.0%
📦 copying_blob: 50.0%
   (blob: af6eca94c810...)
📦 copying_config: 75.0%
   (config: 392fa14dddd0...)
📝 writing_manifest: 90.0%
✅ Операция завершена успешно

Копирование образа (старые версии)

🔍 getting_signatures: 10.0%
📦 copying_blob: 50.0%
   (blob: 2d35ebdb57d9... 1234567 bytes)
📝 writing_manifest: 85.0%
🔐 storing_signatures: 95.0%
✅ Операция завершена успешно

Инспекция образа

🔍 getting_signatures: 10.0%
✅ Операция завершена успешно

Примеры метрик Prometheus

Базовые метрики операций

# HELP skopeo_operations_total Общее количество операций skopeo
# TYPE skopeo_operations_total counter
skopeo_operations_total{operation="copy",status="success"} 15
skopeo_operations_total{operation="copy",status="error"} 2
skopeo_operations_total{operation="inspect",status="success"} 8

# HELP skopeo_operation_duration_seconds Время выполнения операций skopeo в секундах
# TYPE skopeo_operation_duration_seconds histogram
skopeo_operation_duration_seconds_bucket{operation="copy",le="0.1"} 0
skopeo_operation_duration_seconds_bucket{operation="copy",le="0.5"} 2
skopeo_operation_duration_seconds_bucket{operation="copy",le="1.0"} 8
skopeo_operation_duration_seconds_bucket{operation="copy",le="+Inf"} 15
skopeo_operation_duration_seconds_sum{operation="copy"} 12.5
skopeo_operation_duration_seconds_count{operation="copy"} 15

Метрики blob'ов

# HELP skopeo_blobs_processed_total Общее количество обработанных blob'ов
# TYPE skopeo_blobs_processed_total counter
skopeo_blobs_processed_total{operation="copy",status="success"} 45
skopeo_blobs_processed_total{operation="copy",status="error"} 3

# HELP skopeo_blob_size_bytes Размер blob'ов в байтах
# TYPE skopeo_blob_size_bytes histogram
skopeo_blob_size_bytes_bucket{operation="copy",le="1024"} 5
skopeo_blob_size_bytes_bucket{operation="copy",le="10240"} 12
skopeo_blob_size_bytes_bucket{operation="copy",le="1048576"} 28
skopeo_blob_size_bytes_bucket{operation="copy",le="+Inf"} 45
skopeo_blob_size_bytes_sum{operation="copy"} 2.5e+08
skopeo_blob_size_bytes_count{operation="copy"} 45

Активные операции

# HELP skopeo_active_operations Количество активных операций skopeo
# TYPE skopeo_active_operations gauge
skopeo_active_operations{operation="copy"} 2
skopeo_active_operations{operation="inspect"} 0

Мониторинг и визуализация

Grafana дашборды

В проекте включен готовый дашборд Grafana для визуализации метрик skopeo-wrapper:

# Импорт дашборда в Grafana
# Файл: examples/grafana_dashboard.json

Дашборд включает:

• Общую статистику операций
• Время выполнения операций
• Количество обработанных blob'ов
• Размеры blob'ов
• Активные операции
• Типы источников и назначений
• Алерты и ошибки

Prometheus конфигурация

Пример конфигурации Prometheus для сбора метрик:

# Файл: examples/prometheus.yml
scrape_configs:
  - job_name: 'skopeo-wrapper'
    static_configs:
      - targets: ['localhost:8000']
    scrape_interval: 5s
    metrics_path: /metrics

Алертинг

Настроенные правила алертинга для мониторинга:

# Файл: examples/skopeo-wrapper-alerts.yml
- alert: SkopeoHighErrorRate
  expr: rate(skopeo_operation_errors_total[5m]) > 0.1
  for: 2m
  labels:
    severity: warning

Тестирование

Базовые тесты

python -m pytest tests/

Тесты метрик

python -m pytest tests/test_metrics.py -v

Тесты для skopeo 1.18

python tests/test_skopeo_118.py

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

python examples/basic_usage.py
python examples/advanced_usage.py
python examples/metrics_usage.py

Тесты включают:

• Копирование образов с различными типами прогресса
• Инспекцию образов
• Обработку ошибок
• Специальные тесты для skopeo 1.18
• Полное покрытие метрик Prometheus

Ограничения

• Skopeo не предоставляет детальную информацию о прогрессе загрузки blob'ов
• Прогресс рассчитывается приблизительно на основе этапов операции
• Размер blob'ов не всегда доступен в выводе skopeo
• В skopeo 1.18 отсутствует этап "Storing signatures"
• Парсинг прогресса основан на анализе stderr, что может быть нестабильным

Разработка

Установка в режиме разработки

git clone https://github.com/your-username/skopeo-wrapper.git
cd skopeo-wrapper
pip install -e ".[dev]"

Запуск тестов

pytest tests/ -v

Форматирование кода

black skopeo_wrapper/ tests/ examples/
flake8 skopeo_wrapper/ tests/ examples/

Лицензия

MIT License

Вклад в проект

Приветствуются pull request'ы и issue'ы для улучшения библиотеки.

Changelog

1.0.0

• Первоначальный релиз
• Поддержка skopeo 1.18
• CLI интерфейс
• Парсинг прогресса операций
• Полная документация