Specs — Antfly Docs — Antfly Docs

This page summarizes the durable Cloud contracts that feed the website, SDKs, dashboard, and backend.

Source Files#

File	Purpose
`openapi.yaml`	Public Antfly Cloud Platform API contract used for generated website API docs and public SDK surfaces.
`specs/openapi/cloud/api.yaml`	Cloud service contract for hosted instance lifecycle, API keys, access control, backups, metrics, and billing.
`specs/openapi/cloud/billing.yaml`	Additional billing contract surface.
`specs/openapi/cloud/metrics.yaml`	Additional metrics contract surface.
`specs/openapi/cloud/users.yaml`	Additional users contract surface.
`internal/cloud/openapi.gen.go`	Generated Go types and server bindings for the Cloud service contract.
`pkg/cloudaf-client/oapi/client.gen.go`	Generated Go client for Cloud API consumers.
`ts/apps/www-antfly/scripts/generate-cloud-api-docs.js`	Generates the Cloud API reference under `/docs/cloud/api`.

Public vs Service Contract#

The website Cloud API reference is generated from the root openapi.yaml. That root contract is the public Cloud Platform boundary and intentionally excludes legacy SearchAF project routes.

The service contract in specs/openapi/cloud/api.yaml is the backend-owned source for Cloud instance behavior and generated Go bindings. Keep the two aligned when a new public Cloud feature ships.

Instance Modes#

CloudInstanceMode is the public deployment topology enum.

Mode	Description
`single`	One Antfly node. Split metadata and data node counts are ignored.
`replicated`	Separate metadata and data node groups for HA.

Instance Tiers#

CloudInstanceTier is the customer-facing package baseline used by billing and default resource selection.

Tier	Notes
`starter`	Entry package. Single-node only.
`standard`	General production baseline.
`pro`	Larger package baseline.

Instance Statuses#

CloudInstanceStatus describes lifecycle state.

Status	Meaning
`pending`	Instance row created; provisioning job queued.
`provisioning`	Managed runtime creation is in progress.
`ready`	Instance is available.
`updating`	Capacity or configuration update is in progress.
`degraded`	Runtime exists but health has drifted.
`suspended`	Instance is intentionally unavailable.
`deprovisioning`	Deletion cleanup is in progress.
`deleted`	Instance has been removed.
`failed`	Provisioning or reconciliation failed.

Node Config#

NodeConfig captures the billable and operational shape:

cpu
memory
metadata_nodes
data_nodes
metadata_storage
data_storage
replication_factor
reserved accelerator

For single, Antfly Cloud normalizes capacity to one Antfly node. For replicated, metadata and data node fields apply separately.

Documentation Generation#

The Cloud docs have two kinds of pages:

Hand-written pages under content/docs/cloud/*.mdx.
Generated API pages under content/docs/cloud/api/*.mdx.

Run docs generation from the website app when the OpenAPI specs change:

pnpm --dir ts/apps/www-antfly run generate-docs

The generator also updates the docs sidebar so the Cloud section appears alongside core Antfly, examples, API reference, ML/AI, and operator docs.