Skip to content

For Operators

These docs are for the team installing and operating an Astrolift platform — not the developers deploying apps onto it. App-developer docs live under Getting Started and the Dashboard sections.

New here? Start with the Quickstart for a source-based local evaluation or the shortest supported Kubernetes path. When something breaks, the Runbooks cover the failure modes by symptom. This page is the conceptual map; the install paths below point at the full Terraform + Helm runbooks.

What an Astrolift install looks like

A single Astrolift install is identified by its DNS zone + database. Inside one install, the control plane (api / ui / workers) scales horizontally for HA. You can run N independent installs across any region of any cloud. There is no master orchestrating across them — cross-install coordination is per-flow (federation, export/import) and never synchronous.

The install owns:

  • Its DNS base zone (e.g. myastrolift.net, astro.acme.com, platform.acme.internal — pick any FQDN you control)
  • Its control-plane datastore (Postgres + Redis)
  • Its provider-plugin set (AWS, GCP, Azure, vanilla k8s — any subset)
  • Its tenant clusters (one or many, registered after install)

Install paths

Cloud Status Runbook
AWS Runbook and Terraform tree shipped; read the live-validation caveats in STATUS.md INSTALL-aws.md
GCP Runbook and Terraform tree shipped; read the live-validation caveats in STATUS.md INSTALL-gcp.md
Azure Runbook and Terraform tree shipped; read the live-validation caveats in STATUS.md INSTALL-azure.md
Vanilla Kubernetes (kind / bare-metal / on-prem) Runbook shipped INSTALL-k8s-native.md

The runbooks live in astrolift-opscode and walk: prerequisites → IAM/identity bootstrap → state backend → Terraform plan/apply → Helm chart install → cluster registration → first tenant app deploy.

Repo + tooling layout

The infrastructure-as-code lives in astrolift-opscode:

astrolift-opscode/
├── aws/, gcp/, azure/         # per-cloud Terraform (tf-backend / environments / modules)
├── kubernetes/                # cloud-agnostic baseline installer
├── helm/
│   ├── astrolift/             # control plane chart
│   ├── astrolift-prereqs/     # umbrella chart for cluster operators (CNPG, Strimzi, Vault, Velero, ...)
│   └── tenant-telemetry/      # per-cloud fluent-bit + OTel values
├── ci-templates/              # reusable CI templates (GHA / GitLab / Buildkite)
├── gitops/                    # ArgoCD + Flux manifests
├── INSTALL-{aws,gcp,azure,k8s-native}.md
└── STATUS.md                  # canonical state map

Picking a path

  • You have an AWS account and want production: go to INSTALL-aws.md.
  • You want to try the platform locally before committing: go to INSTALL-k8s-native.md and follow the kind dev profile.
  • You're on bare-metal / on-prem / sovereignty-bound: same k8s-native runbook; skip the kind section, use your real cluster.
  • You want GCP or Azure: use the matching INSTALL-gcp.md or INSTALL-azure.md, and read STATUS.md before applying. The infrastructure is wired but the status file still identifies live-validation and helper-script gaps.

Operating concerns

After install:

  • Backups — Velero for cluster state + AWS Backup / Cloud SQL Backups / Recovery Services Vault for managed-service data; toggles per env in <cloud>/environments/<env>/variables.tf
  • Observability — Fluent Bit + OTel collector ship per-tenant metrics/traces/logs to the cloud's native backend (CloudWatch / Cloud Monitoring / Azure Monitor) or in-cluster Prometheus + Loki + Tempo. The dashboard's own metrics panels read the cluster's Prometheus directly: see Wiring metrics
  • Tenant isolation — namespaces per <org>-<app>, deny-by-default network policies, IRSA / Workload Identity / Federated Credentials for cloud API access
  • GitOps — optional; templates for ArgoCD or Flux ship in astrolift-opscode/gitops/. The platform writes the config repo when GitOps mode is enabled
  • Upgrades — coordinated via the parent astrolift metarepo's release tag. Use helm upgrade, not helm install, for an existing release, and review the Terraform plan before applying it.