Skip to content

API.md

Latest commit

 

History

History
158 lines (124 loc) · 4.63 KB

API.md

File metadata and controls

158 lines (124 loc) · 4.63 KB
Raw

HTTP API Reference

Served by ignite serve at the address configured in ignite.yaml's apiAddr (default 127.0.0.1:9091), or overridden with --api-addr.

All endpoints are unauthenticated except /webhook (HMAC-signed). If you expose this port beyond localhost, put it behind a reverse proxy or firewall rule — there's no built-in auth on the status/metrics endpoints.

GET /healthz

Liveness only: the process is up. Always returns 200 ok once the HTTP server has started, regardless of reconciliation state. Never flaps due to upstream Git or provider issues — use this for basic process supervision.

$ curl http://127.0.0.1:9091/healthz
ok

GET /readyz

Readiness: has the cluster converged at least once?

  • 200 ready — at least one reconciliation pass completed with no errors.
  • 503 with a explanatory body — no reconciliation has run yet, or the last one had errors.
$ curl -i http://127.0.0.1:9091/readyz
HTTP/1.1 200 OK
ready

GET /status

The full result of the most recent reconciliation pass, as JSON:

{
  "timestamp": "2026-07-08T18:40:43.19Z",
  "commit": "cd19b108eb1a9d104b8729f4b5b7a4cbf500df31",
  "clusterName": "demo-cluster",
  "mode": "aio",
  "hostMode": "systemd",
  "services": [
    {"name": "vault", "state": "active"},
    {"name": "vault-manager", "state": "active"},
    {"name": "etcd", "state": "active"},
    {"name": "coredns", "state": "active"},
    {"name": "redis", "state": "active"},
    {"name": "persys-scheduler", "state": "active"},
    {"name": "persys-gateway", "state": "active"},
    {"name": "compute-agent", "state": "active"},
    {"name": "mongodb", "state": "active"}
  ],
  "pools": {
    "default": [
      {
        "id": "f738af4be36365bd",
        "name": "default-mock-f738af",
        "pool": "default",
        "address": "10.99.0.1",
        "hardwareClass": "standard",
        "state": "Ready",
        "agentVersion": "latest",
        "message": "simulated provisioning complete"
      }
    ]
  }
}

services lists every service from the dynamic catalog (infra/docker/docker-compose.yml), with state meaning depending on hostMode: real systemctl is-active output for systemd, docker compose ps state for container, or "unknown (see VM directly: docker compose ps)" for vm mode (status isn't polled remotely in this release — SSH into the VM and check directly).

errors is present (an array of strings) if the last pass had problems.

GET /desired

The last-persisted desired state (the parsed Cluster manifest), as JSON. 404 if no reconciliation has run yet.

GET /actual

The last-persisted actual state (same shape as /status, but read from the state store rather than in-memory). 404 if no reconciliation has run yet.

GET /history

The last 100 reconciliation history events (bootstrap/reconcile/restore/ backup actions), most recent last:

[
  {
    "timestamp": "2026-07-08T18:40:37.88Z",
    "commit": "949a54b...",
    "action": "bootstrap",
    "success": true,
    "message": "bootstrap completed"
  }
]

GET /metrics

Prometheus text-exposition format:

# HELP ignite_uptime_seconds Time since the Ignite process started.
# TYPE ignite_uptime_seconds gauge
ignite_uptime_seconds 123.45

# HELP ignite_reconcile_total Total reconciliation passes attempted.
# TYPE ignite_reconcile_total counter
ignite_reconcile_total 42

# HELP ignite_reconcile_errors_total Total reconciliation passes that ended with an error.
# TYPE ignite_reconcile_errors_total counter
ignite_reconcile_errors_total 1

# HELP ignite_pool_nodes_ready Number of nodes in Ready state per compute pool.
# TYPE ignite_pool_nodes_ready gauge
ignite_pool_nodes_ready{pool="default"} 3

Point a Prometheus scrape config at this endpoint directly; no exporter needed.

POST /webhook

GitOps webhook receiver. Validates an HMAC-SHA256 signature and, on success, triggers an immediate out-of-cycle reconciliation pass.

  • Accepts GitHub's X-Hub-Signature-256: sha256=<hex-hmac> header format.
  • Also accepts GitLab's X-Gitlab-Token: <secret> header (direct comparison, no HMAC, matching GitLab's own webhook auth model).
  • 401 if the secret doesn't match (or is missing when one is configured).
  • 405 for non-POST methods.
  • 202 Accepted on success — reconciliation is triggered asynchronously, this endpoint doesn't wait for it to complete.

Configure the shared secret via ignite serve --webhook-secret <value> or the IGNITE_WEBHOOK_SECRET environment variable. If no secret is configured, signature verification is skipped entirely — only do this on a network you trust.

GET /version

{"service": "persys-ignite"}