Перейти к содержанию

CLI Reference

Установка

pipx install git+ssh://git@lab.xmonetize.net/infrastructure/hive/hive-api.git

Требуется Python 3.12+. Работает на Linux, macOS, Windows.

Нет pipx?

Установите: apt install pipx (Debian/Ubuntu), brew install pipx (macOS) или pip install pipx.

В CI

В CI пайплайнах используется Docker-образ lab.xmonetize.net:5050/infrastructure/hive/hive-api/cli:latest с предустановленным hive. Ручная установка не нужна.

DevContainer

hive-cli устанавливается автоматически из исходников при использовании Hive DevContainer.

hive init

Регистрирует репозиторий в Hive: создаёт deploy token в GitLab и добавляет репо в ArgoCD.

hive init <remote_url>

Аргументы:

Аргумент Описание
remote_url Git remote URL репозитория

Пример:

hive init git@lab.xmonetize.net:infrastructure/hive/my-service.git

Note

Обычно hive init вызывается один раз при создании проекта. После этого CI делает всё автоматически.

hive build

Собирает контейнер из исходников с помощью Cloud Native Buildpacks. Автоматически определяет язык (Go, Python, Java, .NET, Node.js и др.).

hive build [OPTIONS]

Флаги:

Флаг Короткий Default Описание
--all -a — Собрать все обнаруженные сервисы
--service -s — Собрать конкретный сервис по имени
--builder -b paketobuildpacks/builder-jammy-base Образ buildpack builder
--path -p . Путь к исходникам
--build-arg — — Аргумент сборки KEY=VALUE или KEY (из env). Можно повторять

Примеры:

# Собрать текущий сервис
hive build

# Собрать все сервисы в репозитории
hive build --all

# Собрать конкретный сервис
hive build --service auth-service

Docker daemon

hive build требует Docker daemon. В CI используется Docker-in-Docker (dind).

Выбор builder

Укажите builder: docker в .hive.yml для сборки через Dockerfile вместо Buildpacks. По умолчанию — paketo (Cloud Native Buildpacks). При builder: docker в директории сервиса должен быть Dockerfile.

Аргументы сборки

Build args можно задать в .hive.yml или через флаг --build-arg. Значения поддерживают динамическую подстановку из env:

buildArgs:
  NODE_ENV: production         # Статическое значение
  GITHUB_TOKEN: ${GITHUB_TOKEN} # Из переменной окружения
  CI_COMMIT_SHA:                # Целиком из env (как docker --build-arg KEY)

CLI --build-arg перекрывает значения из .hive.yml. Для Docker — передаётся как --build-arg. Для Buildpacks — как --env.

hive test

Запускает собранный контейнер и проверяет что health endpoint отвечает. Генерирует JUnit XML отчёт.

hive test [OPTIONS]

Флаги:

Флаг Короткий Default Описание
--all -a — Тестировать все сервисы
--service -s — Тестировать конкретный сервис
--timeout -t 30 Таймаут health check в секундах
--report -r hive-test-report.xml Путь для JUnit отчёта

Что делает:

  1. Пуллит собранный образ
  2. Запускает контейнер (docker run)
  3. Ждёт HTTP 2xx на health endpoint (poll каждые 2 секунды)
  4. Если ответ — pass. Если таймаут или контейнер упал — fail + логи контейнера
  5. Останавливает и удаляет контейнер

Пример:

# Тестировать текущий сервис
hive test

# Тестировать с увеличенным таймаутом
hive test --timeout 60

# Тестировать все сервисы
hive test --all

hive deploy

Деплоит сервис на платформу через Hive API → ArgoCD → Knative.

hive deploy [OPTIONS]

Флаги:

Флаг Короткий Default Описание
--all -a — Задеплоить все сервисы
--service -s — Задеплоить конкретный сервис
--env -e — Переменная окружения KEY=VALUE (можно повторять)
--bootstrap — — Деплоить напрямую в ArgoCD, минуя Hive API
--timeout -t 300 Таймаут деплоя в секундах

Bootstrap mode

Флаг --bootstrap используется для деплоя самого Hive API (или когда API недоступен). Он создаёт ArgoCD Application напрямую через ArgoCD API, без обращения к Hive API. Требует переменные ARGOCD_URL и ARGOCD_TOKEN.

Примеры:

# Задеплоить текущий сервис
hive deploy

# Задеплоить с переменными окружения
hive deploy --env DATABASE_URL=postgres://prod/db --env LOG_LEVEL=warn

# Задеплоить все сервисы
hive deploy --all

# Первый деплой (провижн сертификата может занять больше времени)
hive deploy --timeout 600

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

Переменная Описание
HIVE_API_URL URL Hive API
HIVE_API_TOKEN Bearer token для аутентификации
CI_REGISTRY_IMAGE Адрес образа в registry
CI_COMMIT_SHORT_SHA Тег образа (commit SHA)

hive list

Показывает все обнаруженные сервисы в репозитории.

hive list

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

Discovered services:
  helloworld-go       (port: 8080, path: helloworld-go)
  helloworld-python   (port: 8080, path: helloworld-python)
  helloworld-dotnet   (port: 8080, path: helloworld-dotnet)

hive ci

Генерирует .gitlab-ci.yml pipeline из обнаруженных .hive.yml файлов. Выводит YAML в stdout.

hive ci [OPTIONS]

Флаги:

Флаг Короткий Описание
--global -g Генерировать pipeline для всех обнаруженных сервисов
--environment -E Имя GitLab environment (например, staging, production)

Примеры:

# Генерировать для всех сервисов (stdout)
hive ci --global

# С привязкой к окружению — deploy jobs получат environment
hive ci --global --environment staging

# Сохранить в файл
hive ci --global -E production > child-pipeline.yml

Конфиг окружений

Когда указан --environment, Hive читает cli/environments.yaml и инжектит переменные окружения (HIVE_API_URL, HIVE_DOMAIN) напрямую в сгенерированный pipeline. Это единственный источник истины для конфигурации per-environment — не нужны GitLab environment-scoped variables (которые не пробрасываются в child pipelines). Без флага — используется захардкоженный staging URL (обратная совместимость).

Подробнее о CI — в разделе CI/CD Integration.