{"id":36753845,"url":"https://github.com/openshift-hyperfleet/hyperfleet-api","last_synced_at":"2026-03-10T11:01:36.206Z","repository":{"id":320535877,"uuid":"1081817248","full_name":"openshift-hyperfleet/hyperfleet-api","owner":"openshift-hyperfleet","description":"HyperFleet API - Simple REST API for cluster lifecycle management. Provides CRUD operations for clusters and status    sub-resources. Pure data layer with PostgreSQL integration - no business logic or event creation. Stateless design enables    horizontal scaling. Part of HyperFleet v2 event-driven architecture.","archived":false,"fork":false,"pushed_at":"2026-03-04T16:30:21.000Z","size":13703,"stargazers_count":1,"open_issues_count":8,"forks_count":13,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T23:30:43.141Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openshift-hyperfleet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-23T10:30:16.000Z","updated_at":"2026-03-04T08:30:36.000Z","dependencies_parsed_at":"2026-03-10T11:01:20.837Z","dependency_job_id":null,"html_url":"https://github.com/openshift-hyperfleet/hyperfleet-api","commit_stats":null,"previous_names":["openshift-hyperfleet/hyperfleet-api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/openshift-hyperfleet/hyperfleet-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openshift-hyperfleet","download_url":"https://codeload.github.com/openshift-hyperfleet/hyperfleet-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T12:47:42.574Z","updated_at":"2026-03-10T11:01:36.182Z","avatar_url":"https://github.com/openshift-hyperfleet.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperFleet API\n\nHyperFleet API - Simple REST API for cluster lifecycle management. Provides CRUD operations for clusters and status sub-resources. Pure data layer with PostgreSQL integration - no business logic or event creation. Stateless design enables horizontal scaling.\n\n## Architecture\n\n### Technology Stack\n\n- **Language**: Go 1.24+\n- **API Definition**: OpenAPI 3.0\n- **Code Generation**: openapi-generator-cli\n- **Database**: PostgreSQL with GORM ORM\n- **Container Runtime**: Podman\n- **Testing**: Gomega + Resty\n\n### Core Features\n\n* OpenAPI 3.0 specification\n* Automated Go code generation from OpenAPI\n* Cluster and NodePool lifecycle management\n* Adapter-based status reporting with Kubernetes-style conditions\n* Pagination and search capabilities\n* Complete integration test coverage\n* Database migrations with GORM\n* Embedded OpenAPI specification using `//go:embed`\n\n### Project Structure\n\n```text\nhyperfleet-api/\n├── cmd/hyperfleet-api/          # Application entry point\n├── pkg/\n│   ├── api/                     # API models and handlers\n│   ├── dao/                     # Data access layer\n│   ├── db/                      # Database setup and migrations\n│   ├── handlers/                # HTTP request handlers\n│   └── services/                # Business logic\n├── openapi/                     # API specification source\n├── test/                        # Integration tests and factories\n├── docs/                        # Detailed documentation\n└── Makefile                     # Build automation\n```\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.24+**, **Podman**, **PostgreSQL 13+**, **Make**\n\nSee [PREREQUISITES.md](PREREQUISITES.md) for installation instructions.\n\n### Installation\n\n```bash\n# 1. Generate OpenAPI code and mocks\nmake generate-all\n\n# 2. Install dependencies\ngo mod download\n\n# 3. Build binary\nmake build\n\n# 4. Setup database\nmake db/setup\n\n# 5. Run migrations\n./bin/hyperfleet-api migrate\n\n# 6. Start service (no auth)\nmake run-no-auth\n```\n\n**Note**: Generated code is not tracked in git. You must run `make generate-all` after cloning.\n\n### Accessing the API\n\nThe service starts on `localhost:8000`:\n\n- **REST API**: `http://localhost:8000/api/hyperfleet/v1/`\n- **OpenAPI spec**: `http://localhost:8000/api/hyperfleet/v1/openapi`\n- **Swagger UI**: `http://localhost:8000/api/hyperfleet/v1/openapi.html`\n- **Liveness probe**: `http://localhost:8080/healthz`\n- **Readiness probe**: `http://localhost:8080/readyz`\n- **Metrics**: `http://localhost:9090/metrics`\n\n```bash\n# Test the API\ncurl http://localhost:8000/api/hyperfleet/v1/clusters | jq\n```\n\n## API Resources\n\n### Clusters\n\nKubernetes clusters with provider-specific configurations, labels, and adapter-based status reporting.\n\n**Main endpoints:**\n- `GET/POST /api/hyperfleet/v1/clusters`\n- `GET /api/hyperfleet/v1/clusters/{id}`\n- `GET/POST /api/hyperfleet/v1/clusters/{id}/statuses`\n\n### NodePools\n\nGroups of compute nodes within clusters.\n\n**Main endpoints:**\n- `GET /api/hyperfleet/v1/nodepools`\n- `GET/POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools`\n- `GET /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}`\n- `GET/POST /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses`\n\nBoth resources support pagination, label-based search, and adapter status reporting. See [docs/api-resources.md](docs/api-resources.md) for complete API documentation.\n\n## Example Usage\n\n```bash\n# Create a cluster\ncurl -X POST http://localhost:8000/api/hyperfleet/v1/clusters \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"kind\": \"Cluster\", \"name\": \"my-cluster\", \"spec\": {...}, \"labels\": {...}}' | jq\n\n# Search clusters\ncurl -G http://localhost:8000/api/hyperfleet/v1/clusters \\\n  --data-urlencode \"search=labels.environment='production'\" | jq\n\n# Search ready clusters in a specific region\ncurl -G http://localhost:8000/api/hyperfleet/v1/clusters \\\n  --data-urlencode \"search=status.conditions.Ready='True' and labels.region='us-east'\" | jq\n```\n\nSee [docs/search.md](docs/search.md) for search and filtering documentation.\n\n## Development\n\n### Common Commands\n\n```bash\nmake build               # Build binary to bin/\nmake run-no-auth         # Run without authentication\nmake test                # Run unit tests\nmake test-integration    # Run integration tests\nmake generate            # Generate OpenAPI models\nmake generate-mocks      # Generate test mocks\nmake generate-all        # Generate OpenAPI models and mocks\nmake db/setup            # Create PostgreSQL container\nmake image               # Build container image\n```\n\nSee [docs/development.md](docs/development.md) for detailed workflows.\n\n### Pre-commit Hooks\n\nThis project uses [pre-commit](https://pre-commit.io/) for code quality checks. See [docs/development.md](docs/development.md#pre-commit-hooks-optional) for setup instructions.\n\n## Documentation\n\n### Core Documentation\n\n- **[API Resources](docs/api-resources.md)** - API endpoints, data models, and search capabilities\n- **[Development Guide](docs/development.md)** - Local setup, testing, code generation, and workflows\n- **[Database](docs/database.md)** - Schema, migrations, and data model\n- **[Deployment](docs/deployment.md)** - Container images, Kubernetes deployment, and configuration\n- **[Authentication](docs/authentication.md)** - Development and production auth\n- **[Logging](docs/logging.md)** - Structured logging, OpenTelemetry integration, and data masking\n\n### Additional Resources\n\n- **[PREREQUISITES.md](PREREQUISITES.md)** - Prerequisite installation\n- **[Search and Filtering](docs/search.md)** - Guide to TSL query syntax, operators, and examples\n- **[docs/continuous-delivery-migration.md](docs/continuous-delivery-migration.md)** - CD migration guide\n- **[docs/dao.md](docs/dao.md)** - Data access patterns\n- **[docs/testcontainers.md](docs/testcontainers.md)** - Testcontainers usage\n\n## License\n\n[License information to be added]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api/lists"}