Antfly Cloud separates control-plane state from managed Antfly runtime state. The control plane stores the desired product state, queues background jobs, and asks Kubernetes plus the Antfly operator to reconcile the running database.

Product Model#

The Cloud hierarchy is:

Organization
  -> Cloud instances
       -> Cloud API keys
       -> groups, grants, and row filters
       -> backups, restores, events, and metrics

Organizations own billing, members, invitations, audit logs, and management API keys. Instances own database runtime state, connection details, data-plane API keys, grants, backup schedules, and observability.

Source of Truth#

PostgreSQL is the source of truth for desired Cloud instance state:

• organization, name, slug, region
• lifecycle status
• tier and deployment mode
• node configuration
• Kubernetes namespace
• connection details
• provisioning timestamps and errors

Kubernetes is the reconciliation target. The control plane records the desired state, enqueues jobs, and reconciles namespaces, Antfly cluster custom resources, backup resources, and related runtime state.

Instance Lifecycle#

Instance creation validates access, slug shape, billing state, tier, mode, and node configuration. The backend stores a pending instance and queues provisioning. A worker then:

1. loads the instance and organization metadata
2. ensures the Kubernetes namespace exists
3. builds the operator spec from the persisted mode and node config
4. creates or updates the managed Antfly cluster
5. updates status and connection details

Deletion marks an instance for deprovisioning and queues cleanup. Scaling merges the allowed node_config changes and queues a scale job. Reconciliation jobs heal drift and update status.

Deployment Modes#

Antfly Cloud exposes two public deployment modes:

Single-node instances normalize node counts to one Antfly node. Replicated instances use split metadata and data node counts, storage, CPU, memory, and replication settings.

Proxy Path#

Application traffic goes through the Cloud proxy:

/cloud/v1/{instance_id}/...
  -> Cloud proxy
  -> Cloud API-key authentication
  -> table-aware policy gateway
  -> managed Antfly instance

The proxy gateway enforces table allowlists, operation allowlists, grants, and row filters before forwarding data-plane requests. Control-plane management endpoints stay under the organization and instance APIs.

Billing and Usage#

Billing is based on the requested instance shape and observed Cloud usage. The node configuration drives resource usage for CPU, memory, and disk. Committed-capacity billing records explain when capacity changes create charges, refunds, or no-op billing changes.

Backups and Observability#

Backups, restores, schedules, metrics, and events are first-class instance resources. Backups are tracked in the control plane and executed by background workers. Metrics and events are exposed through Cloud endpoints so customers can operate instances without direct Kubernetes access.