Конфигурация `.hive.yml`¶

Файл .hive.yml — единственное, что нужно для работы с Hive. Он описывает ваш сервис.

Полный пример¶

name: my-service
namespace: my-team
port: 8080
path: .
healthPath: /healthz
lifecycle: standard
builder: paketo
context: ..
skipTest: false
env:
  - name: DATABASE_URL
    value: postgres://localhost/mydb
  - name: LOG_LEVEL
    value: info
testEnv:
  XM_PG_CONNECTIONSTRING: "Host=localhost"
scaling:
  minScale: 2
  maxScale: 20
customDomains:
  - api.example.com
storage:
  database: true
buildArgs:
  NODE_ENV: production
  GITHUB_TOKEN: ${GITHUB_TOKEN}

Справочник полей¶

Поле	Тип	Default	Описание
`name`	string	имя директории	Имя сервиса. Используется в URL, ArgoCD, registry
`namespace`	string	имя проекта из git remote	Kubernetes namespace для деплоя
`port`	int	`8080`	Порт, на котором сервис слушает HTTP
`path`	string	`.`	Путь к исходникам относительно `.hive.yml`
`healthPath`	string	`/`	Endpoint для health checks (startup, readiness, liveness)
`lifecycle`	string	`standard`	Lifecycle policy для probes. См. Lifecycle Policies
`builder`	string	`paketo`	Метод сборки: `paketo` (Cloud Native Buildpacks) или `docker` (Dockerfile)
`context`	string	(пусто)	Директория build context относительно директории сервиса. См. Build Context
`skipTest`	bool	`false`	Пропустить `hive test` и убрать test job из CI pipeline. См. Пропуск тестов
`env`	list	`[]`	Переменные окружения
`testEnv`	object	`{}`	Переменные окружения только для `hive test`. См. Тестовое окружение
`scaling`	object	`minScale: 1, maxScale: 10`	Параметры автоскейлинга Knative
`customDomains`	list	`[]`	Кастомные доменные имена, привязанные к сервису через Knative DomainMapping
`storage`	object	`{}`	Подключение хранилищ. См. Storage
`buildArgs`	object	`{}`	Аргументы сборки, передаются в Docker (`--build-arg`) или Buildpacks (`--env`)

Как резолвятся дефолты¶

`name`¶

Приоритет:

Значение из .hive.yml
Переменная окружения HIVE_SERVICE_NAME
Если .hive.yml в корне репозитория — имя проекта из git remote
Имя директории, содержащей .hive.yml

my-repo/
  services/
    auth-service/
      .hive.yml          # name → "auth-service" (имя директории)
  .hive.yml              # name → "my-repo" (имя проекта из git remote)

`namespace`¶

Приоритет:

Значение из .hive.yml
Переменная окружения HIVE_NAMESPACE
Имя проекта из git remote URL

Пример: для git@lab.xmonetize.net:infrastructure/hive/hive-examples.git namespace по умолчанию = hive-examples.

`port`¶

По умолчанию 8080. Используется для:

containerPort в Knative Service
health check probes (httpGet)
hive test (проверка при тестировании)

`healthPath`¶

По умолчанию /. Endpoint, который проверяют:

Startup probe — ждёт пока сервис стартует
Readiness probe — определяет готовность принимать трафик
Liveness probe — проверяет что сервис жив

Должен возвращать HTTP 2xx. Не обязательно что-то специальное — подойдёт любой endpoint.

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

Три способа задать env vars (в порядке приоритета):

1. CLI флаг `--env` (наивысший)¶

hive deploy --env DATABASE_URL=postgres://prod/db --env LOG_LEVEL=warn

2. Переменные окружения `HIVE_ENV_*`¶

export HIVE_ENV_DATABASE_URL=postgres://staging/db
hive deploy

Префикс HIVE_ENV_ убирается: HIVE_ENV_FOO → FOO.

3. `.hive.yml` (наименьший)¶

env:
  - name: LOG_LEVEL
    value: info
  - name: DATABASE_URL
    value: ${XM_PG_CONNECTIONSTRING}   # резолвится из окружения при deploy

Значения с ${VAR} подставляются из текущего окружения при запуске hive deploy (тот же синтаксис, что и в buildArgs).

Merge, не замена

Все три источника мержатся. CLI --env перезаписывает значения из HIVE_ENV_*, которые перезаписывают значения из .hive.yml. Подстановка ${VAR} происходит после merge.

Scaling¶

scaling:
  minScale: 1    # минимум реплик (0 = scale to zero)
  maxScale: 10   # максимум реплик

Knative автоматически масштабирует сервис в этих пределах на основе нагрузки.

Scale to zero

minScale: 0 означает, что сервис может быть остановлен при отсутствии трафика. Первый запрос после простоя будет с задержкой (cold start).

Кастомные домены¶

Вы можете привязать кастомные доменные имена к сервису через поле customDomains. Hive создаёт Knative DomainMapping для каждого домена и автоматически выпускает TLS-сертификаты через cert-manager.

name: my-service
namespace: my-team
customDomains:
  - api.example.com
  - app.example.com

Настройка¶

Добавьте домен в customDomains в .hive.yml
Создайте CNAME или A запись у DNS-провайдера, указывающую на внешний gateway (например, CNAME api.example.com → external-gateway.svcik.org)
Задеплойте через hive deploy — DomainMapping и TLS-сертификат будут созданы автоматически

TLS-сертификаты

TLS-сертификаты выпускаются автоматически через cert-manager. Первый запрос после добавления нового домена может занять до 60-120 секунд, пока сертификат выпускается.

Storage¶

Hive предоставляет управляемые хранилища для сервисов. Сейчас поддерживается PostgreSQL. Запрашиваешь хранилище в .hive.yml — Hive выделяет, управляет и передаёт креды в сервис через env vars.

PostgreSQL¶

storage:
  database: true

Что происходит при деплое:

Hive создаёт HiveComb CR (кастомный ресурс оператора hive-comb)
hive-comb выделяет в общем PostgreSQL-кластере:
Пользователя с именем сервиса
Базу данных с именем сервиса (dashes заменяются на underscores)
Сгенерированный пароль
Сохраняет креды в Kubernetes Secret {service-name}-db
Knative Service автоматически подключает Secret через envFrom — все переменные становятся доступны контейнеру

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

Сервис получает:

Переменная	Описание
`DATABASE_URL`	Полная строка подключения: `postgresql://user:pass@host:port/db`
`PGHOST`	Хост PostgreSQL
`PGPORT`	Порт PostgreSQL
`PGUSER`	Имя пользователя
`PGPASSWORD`	Пароль
`PGDATABASE`	Имя базы данных

Обе формы предоставлены — используй что удобнее: - Node.js / psycopg2 / SQLAlchemy обычно читают DATABASE_URL - psql / pg_dump читают PG*

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

name: my-api
port: 8080
storage:
  database: true
env:
  - name: LOG_LEVEL
    value: info

В коде:

# Python (psycopg2)
import os, psycopg2
conn = psycopg2.connect(os.environ["DATABASE_URL"])

// Node.js (pg)
import { Pool } from "pg";
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

Жизненный цикл¶

Создание: при первом hive deploy со storage.database: true — пользователь и база создаются за ~10-30 секунд.
Обновление: изменения в сервисе не пересоздают БД. Креды остаются теми же.
Удаление сервиса: по умолчанию БД сохраняется (deletionPolicy: Retain). Чтобы удалить — снеси HiveComb CR вручную через kubectl.

Данные сервиса не резервируются автоматически

Hive предоставляет хранилище, но ответственность за бэкапы на команде сервиса. Общий PostgreSQL-кластер имеет point-in-time recovery через CNPG, но логические бэкапы конкретной БД нужно делать самим.

Общий кластер

Все сервисы с storage.database: true пользуются одним PostgreSQL-кластером (управляется CloudNativePG). Изоляция — по пользователю и базе. Одна база = один сервис. Не ожидай cross-database JOIN'ов.

CronJobs¶

Hive может деплоить не только долгоживущие сервисы, но и периодические задачи (cron jobs). Укажите type: cronjobs и определите одну или несколько задач с независимыми расписаниями.

Поля¶

Поле	Тип	Обязательное	Описание
`type`	string	нет	Тип нагрузки: `service` (по умолчанию) или `cronjobs`
`jobs`	list	да (если `type: cronjobs`)	Список определений cron-задач
`jobs[].name`	string	да	Имя задачи (уникальное в рамках сервиса)
`jobs[].schedule`	string	да	Cron-выражение расписания (например, `"/5 * * *"`)
`jobs[].command`	string	да	Команда для выполнения
`jobs[].args`	list	нет	Аргументы, передаваемые команде

Пример¶

name: my-workers
namespace: my-team
type: cronjobs
builder: docker
jobs:
  - name: sync-data
    schedule: "*/15 * * * *"
    command: python
    args: ["-m", "tasks.sync"]
  - name: cleanup
    schedule: "0 3 * * *"
    command: python
    args: ["-m", "tasks.cleanup"]
env:
  - name: DATABASE_URL
    value: ${DATABASE_URL}

Тесты пропускаются автоматически

При type: cronjobs стадия тестирования автоматически пропускается в CI pipeline. CronJobs не открывают HTTP-порт, поэтому стандартный hive test на основе health check неприменим.

Build Context¶

По умолчанию контекст сборки — директория сервиса (та, где лежит .hive.yml). Поле context позволяет это изменить — полезно в монорепо, когда Dockerfile ссылается на файлы за пределами директории сервиса.

name: kb-mcp
builder: docker
context: ..          # build context = корень репо (родитель директории сервиса)

Когда context отличается от директории сервиса, флаг -f Dockerfile передаётся автоматически, чтобы билдер нашёл Dockerfile.

Когда использовать

Типичный сценарий: общие библиотеки или конфиги лежат в корне репо, а Dockerfile делает COPY shared/ ./shared/. Без context: .. сборка упадёт, потому что эти файлы за пределами дефолтного build context.

Пропуск тестов¶

Если сервис невозможно протестировать без внешней инфраструктуры (база данных, сторонние API и т.д.), тестирование можно полностью пропустить:

skipTest: true

Когда skipTest включён:

hive test пропускает сервис
В CI pipeline нет test job — deploy зависит напрямую от build

Warning

Используйте с осторожностью. Пропуск тестов убирает страховку от деплоя сломанных сервисов. По возможности добавьте минимальный health endpoint, который стартует без зависимостей.

Тестовое окружение¶

Поле testEnv задаёт переменные окружения, которые передаются контейнеру во время hive test (через docker run -e KEY=VALUE). В продакшене они не используются — только при тестировании.

testEnv:
  XM_PG_CONNECTIONSTRING: "Host=localhost"
  API_KEY: "test-key"

Применение: сервису нужны определённые переменные (строки подключения, API-ключи) просто чтобы запуститься и пройти health checks.

Note

testEnv не влияет на env. Продакшен-переменные настраиваются отдельно через env, HIVE_ENV_* или --env.

Builder¶

builder: docker   # или "paketo" (по умолчанию)

Значение	Описание
`paketo`	Cloud Native Buildpacks — автоматически определяет язык по маркерным файлам (requirements.txt, package.json, go.mod и т.д.)
`docker`	Использует `Dockerfile` в директории сервиса. Обязателен для языков без поддержки Buildpacks (Rust, C, C++)

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

Аргументы, передаваемые при сборке в docker build --build-arg или pack build --env.

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

Имя аргумента сборки не обязано совпадать с именем CI-переменной:

buildArgs:
  XM_AI_APIKEY: ${XM_OPENAI_API_KEY}   # имя build arg ≠ имя CI-переменной

Здесь Dockerfile видит XM_AI_APIKEY, а значение берётся из переменной окружения XM_OPENAI_API_KEY в CI.

Резолв значений:

Формат	Поведение
`KEY: value`	Используется как есть
`KEY: ${VAR}`	Подставляется из `os.environ["VAR"]` в момент сборки. `KEY` и `VAR` могут отличаться
`KEY:` (пустое/null)	Целиком берётся из `os.environ["KEY"]`

Переопределение через CLI:

hive build --build-arg NODE_ENV=development --build-arg EXTRA_FLAG

Приоритет: CLI --build-arg > .hive.yml buildArgs

Конфигурация .hive.yml¶