Модуль XIX — собственный API и поверхность manage-as-code

Модуль XIX — не функция, прикрученная к движку, он и есть поверхность движка. Каждый другой модуль достигает внешнего мира через тот же первородный API, и веб-интерфейс — это слой представления над тем же самым контрактом, а не параллельным. Эта страница — справочник по тому, что эта поверхность раскрывает сегодня и как управлять control plane как кодом, с её реальными границами.

Контракт API

Движок говорит на одном REST API под /v1 (роутер chi, упрочнённый http.Server) и сфокусированном, замороженном gRPC-зеркале его (olivares.api.v1: информация о сервере, чтение/создание агента, проверка аудита, плюс стандартная служба health). gRPC — намеренное подмножество, а не полный паритет — новые эндпоинты сначала появляются в REST. Оба интерфейса прогоняют одну и ту же цепочку authenticate → resolve-tenant → authorize и отображают ошибки идентично, так что not-found неотличим от межарендаторского ресурса в любом интерфейсе.

REST-поверхность публикуется как контракт OpenAPI 3.1, отрисовываемый в справочнике API прямо из авторской схемы продукта. Этот документ — контракт-эталон для стабильной основной поверхности; маршруты модулей публикуются отдельным beta-документом — в справочнике маршрутов модулей (см. честные ограничения ниже). Та же функциональность также управляема из терминала — см. справочник CLI — потому что CLI — это движок, а не обёртка над ним.

Аутентификация и протокол

Аутентификация — это непрозрачные серверные bearer-токены, а не JWT. Токен снабжён префиксом цели (сессия против API-ключа); сервер сохраняет только публичный селектор и SHA-256 секрета и сравнивает секрет за постоянное время. Последствия, важные для рабочего процесса manage-as-code: токены немедленно отзываемы, не несут никаких заявлений или секретов и не добавляют поверхности атаки на крипто-разбор. API-токен привязан к (tenant, role) или является несвязанным учётным данным системного уровня; запрос, чей заголовок арендатора расходится со связанным токеном, отклоняется, никогда молчаливо не расширяется.

Manage-as-code: провайдер Terraform

Провайдер terraform-provider-olivares — это отдельный Go-модуль и чистый REST-клиент — он никогда не импортирует ядро движка или SDK коннекторов, держа большое дерево зависимостей провайдера вне цепочки поставок ядра. Сконфигурированный эндпоинтом, чувствительным API-токеном и опциональным арендатором, он управляет намеренно небольшим, объявленным набором объектов:

Вид	Имя	Управляет
resource	olivares_agent	определением агента в каталоге (полный CRUD + импорт)
resource	olivares_policy	объявлением политики управления
resource	olivares_agent_identity_binding	привязкой агента к нечеловеческой идентичности
resource	olivares_deployment	определением развёртывания (желаемое состояние, декларативное)
data source	olivares_policies / olivares_identities	представлениями только для чтения управляемого реестра
data source	olivares_access_edges	картой доступа R/RW и её дрейфом permitted-vs-observed
data source	olivares_deployment / olivares_server_info	определением развёртывания; метаданными движка

Это единственные ресурсы и источники данных, которые обслуживает провайдер. Объявление olivares_deployment записывает желаемое состояние в control plane — оно не касается инфраструктуры; путь apply принадлежит модулю VII и является швом с отказом по умолчанию.

Честные ограничения

• olivares_deployment объявляет; он не развёртывает. Ресурс пишет определение развёртывания через маршруты модуля VII. Живой apply/retire против реальной инфраструктуры — это шов с отказом по умолчанию, возвращающий 503, пока оператор не снабдит исполнителя — объявление развёртывания в HCL никогда не мутирует ваш estate.
• Стабильный OpenAPI — не весь протокол. Стабильная основная поверхность находится в опубликованном контракте (/openapi.json); маршруты модулей (например чтения карты доступа и дрейфа, а также маршруты управления и развёртывания, которые использует провайдер) публикуются отдельным beta-документом (/openapi.beta.json, справочник маршрутов модулей). Их формы на уровне полей живут в типизированных интерфейсах продукта, а не в стабильной схеме.
• gRPC — замороженное подмножество, а не полный API. Он зеркалит несколько операций read/create и аудита для первородной автоматизации; не предполагайте, что эндпоинт существует на gRPC, потому что он существует на REST.
• Поверхность провайдера мала намеренно. Четыре ресурса и пять источников данных — не весь API как IaC. Всё за пределами этого набора управляется через REST/CLI, а не объявляется в HCL сегодня.
• Лицензия — это аттестация, никогда не функциональный гейт. Продукт цел под своей лицензией; офлайн-проверка лицензии лишь записывает держателя и статус и никогда не отключает, не деградирует и не блокирует никакой запрос API или загрузку.

Безопасно по умолчанию

Обслуживающий движок безопасен по умолчанию: TLS включён (самоподписанный сертификат генерируется при первой загрузке, если ни один не предоставлен), привязка по умолчанию — localhost, а локальное прослушивание не является освобождением от авторизации. Свежая установка не имеет учётных данных — она чеканит одноразовый токен настройки в stdout и отказывает каждому защищённому эндпоинту, пока не создан первый администратор. Аудит — только-добавляемый и хеш-сцепленный, с подписанными Ed25519 контрольными точками, которые делают переписывание истории до контрольной точки криптографически обнаружимым.

Платформа событий (исходящая половина модуля XIX)

С тех пор как поставлена платформа событий (modules/eventing), поверхность модуля XIX также включает самообслуживаемые арендаторские подписки на события: типизированные подписки над каталогом событий шины (edge.observed, cost.sampled, finding.reported, audit.recorded, …) с надёжной доставкой at-least-once — повторы с откатом, очередь недоставленных сообщений и воспроизведение с курсора — к подписанному HMAC вебхуку или стоку SIEM. Модуль notify (XV) остаётся маршрутизатором предупреждений к снабжённым оператором назначениям; eventing — это платформа, обращённая к интегратору. Сопутствующий экспорт позы только для чтения (modules/posture-export) позволяет control tower опрашивать наземную позу истины продукта — граф доступа, дрейф, инвентарь, находки — только как refs/хеши/отношения, при этом сам экспорт аудируется.

Связанное

• Справочник API — отрисованный контракт OpenAPI 3.1 для основной поверхности.
• Политика стабильности API — версионирование, сигнализация устаревания/прекращения поддержки и окна поддержки для этой поверхности.
• Использование клиентских SDK — первородные клиенты Go/Python/TypeScript.
• Справочник CLI — та же функциональность из бинаря olivares.
• Управление control plane как кодом — руководство по провайдеру Terraform.
• Модуль VII — развёртывание — где olivares_deployment воздействует (шов 503).
• Каталог модулей — разделение Govern/Observe против Actuate.
• Честность и ограничения — что воздействует сегодня, а что нет.
• Обзор архитектуры — слой движка, на котором сидит эта поверхность.