antalos documentation · Architecture
Astro Starlight reads Markdown from docs/ through site/src/content.config.ts. The static build is copied into an unprivileged NGINX image and published by GitHub Actions. Two stateless NGINX replicas serve the image on port 8080 behind a Kubernetes Service and Traefik. cert-manager manages docs-tls.
Component boundaries
- Build
- docs/ + site/
- Astro -> image in GHCR
- Delivery
- Argo CD -> Deployment
- 2 NGINX replicas
- Read
- Service <- Traefik HTTPS
- Reader / static search index
State and recovery contract
Content, CSS, components, navigation, and build definitions live in Git. The serving pods have no application database. Preserve the source repository and access to published images for recovery.
Availability and failure behavior
Availability classification: replicated static serving tier with placement-compatible rolling updates.
This is an interpretation of the checked-in configuration, assuming the declared replicas are healthy, separated as intended, and their required dependencies are reachable. It is not a live-health result or a completed failure drill.
What supplies redundancy
| Component | Declared layout | Mechanism |
|---|---|---|
| NGINX | 2 stateless replicas; required host anti-affinity | The Service routes to ready copies of the same image. |
| Persistent state | None in serving pods | Pages and search assets are reconstructed from Git and the built image. |
| Eviction | PDB minimum 1 | A voluntary eviction should retain a healthy serving pod. |
| Rollout | maxSurge 0; maxUnavailable 1 | Replaces one replica at a time within the two existing eligible worker slots. |
How a failure is handled
The surviving NGINX pod serves new requests after endpoint detection/routing converges. No database promotion or volume restoration is required. The failed node does not contain the only copy of the site source or published image.
Failure scenarios
| Failure | Expected behavior and remaining dependency |
|---|---|
| One main worker | One pod can continue serving. However, hard anti-affinity prevents the lost replica from simply joining the survivor on the same node; availability returns to full redundancy only when another eligible placement is available. |
| RTX worker only | The app has no dedicated RTX dependency, but its ordinary pods do not automatically tolerate the quorum taint. Spare capacity on a tainted node is not automatically usable surge capacity. |
| A second failure before recovery | Outside the stated single-failure envelope; assess remaining data copies, quorum, endpoints, and capacity before further maintenance. |
An RTX worker VM failure is not the same as an RTX Proxmox host failure. The latter also removes its control-plane VM and the configured API address. Read the physical failure-domain explanation before making a whole-host HA claim.
Upgrades and voluntary maintenance
The rollout frees one occupied worker slot before scheduling its replacement, avoiding the former third-slot surge requirement. A failed replacement leaves one old ready replica serving while operators inspect image pulls or readiness.
What prevents a stronger HA claim
Ingress, DNS, network, and API-driven endpoint updates remain shared dependencies. The shared website image-refresh CronJob polls GHCR every minute and triggers a rollout when the selected mutable tag changes digest. It uses a pod-template annotation rather than taking ownership of the image field. Registry or refresh-Job failure delays delivery while existing pods continue serving. The recorded digest is rollout intent; actual pod image IDs establish which image is running.
What would improve the availability contract
Retain commit-tagged images for rollback and exercise real requests during one-node maintenance. Monitor refresh Jobs, rollout readiness, and public delivery separately.
These statements describe the checked-in design, not live rollout evidence. The shared availability reference explains election, replication, durability, recovery time, and shared dependencies; the manifest links below identify this service’s source.
Configuration ownership
apps/docs/ owns this service’s Kubernetes resources. Hostnames, addresses, versions, node names, and volume sizes belong in apps/variables.yaml. Runtime settings stored in a product database need that product’s backup and administration procedure.
Continue
Read the deployment guide for dependency order, initial credentials, and integration work. The official documentation explains the upstream product; the topology above describes this repository.