HyperFleet API

The HyperFleet API is the data storage and status aggregation layer of the HyperFleet platform. It exposes a REST API for CRUD operations on customizable entities (e.g. Cluster, NodePool) backed by PostgreSQL.

The API is the source of truth for desired state of resources that live in remote clusters. It persists resource specs, increments generation on spec changes, and aggregates adapter-reported conditions into Kubernetes-style status.

It does not reconcile infrastructure or publish events itself. For that it collaborates with other HyperFleet components:

• Sentinel component polls the API for unreconciled resources and publishes a message for reconciliation actions
• Adapter component listens to events, performs actions needed to reconcile a resource and reports the status to the API.

Stateless design enables horizontal scaling. Adapters fetch full resource state from the API after receiving minimal CloudEvents (anemic events pattern).

Getting Started

Deploying to Kubernetes

For Helm-based deployment to staging, production, or partner environments, see the Deployment Guide — covers container images, Helm values, external databases, schema validation, monitoring, and production checklists.

Local Development

For setting up a local development environment, see the Development Guide — covers prerequisites, code generation, mock generation, database setup, running tests, pre-commit hooks, and development workflows.

Accessing the API

The service starts on localhost:8000:

• REST API: http://localhost:8000/api/hyperfleet/v1/
• OpenAPI spec: http://localhost:8000/api/hyperfleet/v1/openapi
• Swagger UI: http://localhost:8000/api/hyperfleet/v1/openapi.html
• Liveness probe: http://localhost:8080/healthz
• Readiness probe: http://localhost:8080/readyz
• Metrics: http://localhost:9090/metrics

# Test the API
curl http://localhost:8000/api/hyperfleet/v1/clusters | jq

API Resources

Clusters

Kubernetes clusters with provider-specific configurations, labels, and adapter-based status reporting.

Main endpoints:

• GET/POST /api/hyperfleet/v1/clusters
• GET/PATCH/DELETE /api/hyperfleet/v1/clusters/{id}
• POST /api/hyperfleet/v1/clusters/{id}/force-delete
• GET/PUT /api/hyperfleet/v1/clusters/{id}/statuses

NodePools

Groups of compute nodes within clusters.

Main endpoints:

• GET /api/hyperfleet/v1/nodepools
• GET/POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools
• GET/PATCH/DELETE /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}
• POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/force-delete
• GET/PUT /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses

Generic Resources

The API also supports generic resource types registered via the plugin system. Currently available:

• WifConfigs — GET/POST /api/hyperfleet/v1/wifconfigs, GET/PATCH/DELETE .../wifconfigs/{id}
• Channels — GET/POST /api/hyperfleet/v1/channels, GET/PATCH/DELETE .../channels/{id}
• Versions — GET/POST /api/hyperfleet/v1/channels/{parent_id}/versions, GET/PATCH/DELETE .../versions/{id} (child of Channel)

All resources support pagination, label-based search, and spec validation. Clusters and NodePools additionally support adapter status reporting. See docs/api-resources.md for complete API documentation.

Example Usage

# Create a cluster
curl -X POST http://localhost:8000/api/hyperfleet/v1/clusters \
  -H "Content-Type: application/json" \
  -d '{"kind": "Cluster", "name": "my-cluster", "spec": {...}, "labels": {...}}' | jq

# Search clusters
curl -G http://localhost:8000/api/hyperfleet/v1/clusters \
  --data-urlencode "search=labels.environment='production'" | jq

# Search reconciled clusters in a specific region
curl -G http://localhost:8000/api/hyperfleet/v1/clusters \
  --data-urlencode "search=status.conditions.Reconciled='True' and labels.region='us-east'" | jq

See docs/search.md for search and filtering documentation.

Documentation

Core Documentation

• API Resources - API endpoints, data models, and search capabilities
• Development Guide - Local setup, testing, code generation, and workflows
• Database - Schema, migrations, and data model
• Deployment - Container images, Kubernetes deployment, and configuration
• Configuration - Complete configuration reference (database, server, caller identity, adapters)
• Authentication - Development and production auth
• Logging - Structured logging, OpenTelemetry integration, and data masking
• Validation Schema - How to supply a custom OpenAPI schema for runtime spec field validation

Additional Resources

• PREREQUISITES.md - Prerequisite installation
• Search and Filtering - Guide to TSL query syntax, operators, and examples
• docs/continuous-delivery-migration.md - CD migration guide
• docs/dao.md - Data access patterns
• docs/testcontainers.md - Testcontainers usage

License

This project is licensed under the Apache License 2.0. See LICENSE for details.