Skip to content

Installing Astrolift

This page summarizes the install paths and points at the canonical runbooks. The runbooks live in astrolift-opscode because they walk Terraform + Helm files in that repo step-by-step.

At a glance

                          ┌─ AWS         → INSTALL-aws.md
Pick your cloud  ─────────┼─ GCP         → INSTALL-gcp.md
                          ├─ Azure       → INSTALL-azure.md
                          └─ vanilla k8s → INSTALL-k8s-native.md  (kind dev or bare-metal)

For the guided install into your own AWS account through the Calliope AI Deployment Manager, see Install by blueprint.

Prerequisites (all paths)

Tool Min version
Terraform 1.5 (1.9 used in CI)
Helm 3.16
kubectl 1.28
astro CLI latest

Cloud paths additionally need the cloud's CLI (aws / gcloud / az) and an account with provisioning permissions. See each runbook's prerequisites section.

Install flow (every path)

Placeholders throughout: <cloud> is aws, gcp or azure; <env> is dev, stg or prd (a directory under <cloud>/environments/); <base-zone> is the DNS zone you delegated to the install.

  1. Configure: edit aws/config.env (PROJECT, AWS_REGION, OWNER). run.sh reads <cloud>/config.env and falls back to defaults when the file is missing; only AWS ships one today.
  2. Bootstrap state: ./run.sh bootstrap aws <env> creates the S3 + DynamoDB backend and runs terraform init (all bootstraps every env). For GCP and Azure apply <cloud>/tf-backend/ by hand as the runbook describes; run.sh bootstrap refuses other clouds.
  3. Plan + review: ./run.sh validate, then ./run.sh plan <cloud> <env>. Read the plan; never apply blind. Directory not found means <cloud>/environments/<env> does not exist; check the spelling.
  4. Apply: ./run.sh apply <cloud> <env> provisions VPC, cluster, datastores, identity, registry, observability + backup wiring. Success check: terraform -chdir=<cloud>/environments/<env> output prints the cluster and datastore outputs.
  5. Verify: ./aws/scripts/cold-boot.sh <env> (AWS). The GCP and Azure runbooks name <cloud>/scripts/cold-boot.sh, but those helpers are not in the tree yet; STATUS.md tracks them. Verify by hand with the checks the runbook lists.
  6. Build the env file: ./aws/scripts/build-env.sh <env> pulls Terraform outputs + live secret values into aws/outputs/<env>.env, which the Helm install reads. Same AWS-only caveat as step 5.
  7. Helm install the control plane: helm install astrolift ./helm/astrolift -f ./helm/astrolift/values.<cloud>.yaml --set global.platformDomain=<base-zone>. Success check: kubectl get pods -l app.kubernetes.io/instance=astrolift -A shows the api, ui and worker pods Running.
  8. Register the cluster: open Clusters → Register cluster in the dashboard, then astro cluster bootstrap --cluster-slug <slug> --dry-run and the same command with --wait-timeout 10m to install the prerequisites, then Bring into management. The CLI has cluster bootstrap and keep-alive-agent operations (astro operator cluster) but does not expose registration as astro cluster register. Success check: helm -n astrolift-system list shows astrolift-prereqs deployed.
  9. Install the keep-alive agent: astro operator cluster install-agent --slug <slug> --request-file agent-install.json, then astro operator cluster agent-install-status --install-id <id> until it reports a confirmed heartbeat. See Install the cluster keep-alive agent.
  10. Deploy a first app: create a manifest with astro app init, register it with astro app register, then deploy a built image with astro app deploy --image-tag <ref> --wait. Success check: astro app show <app-slug>.

The runbooks in astrolift-opscode walk each step concretely. Run astro <command> --help against the CLI version distributed by the target control plane before copying commands into automation.

Multi-environment

Each cloud's <cloud>/environments/{dev,stg,prd}/ is independent; no cross-env state. Defaults follow a dev=light / stg=most / prd=full ladder for optional components. The toggle reference is in each cloud's variables.tf and summarized in INSTALL-aws.md § Toggle reference.

Multi-install (multi-region or multi-cloud)

A single Astrolift install owns one DNS zone + one database. To run in multiple regions or clouds, create independent installs, one per region/cloud, each with its own Terraform state, control plane, and cluster set. There is no master above them; cross-install coordination is per-flow.

What happens after install

  • The platform exposes the dashboard at https://<base-zone> (the global.platformDomain Helm value, or the ingress hostname you configured)
  • App developers register apps via the astro CLI or the dashboard; see Getting Started for the dev side
  • Tenant deploys land in <org>-<app> namespaces on the registered tenant cluster(s)
  • Logs / metrics / traces flow to whichever observability backend the install was configured for (per-tenant routing supported); dashboard metrics panels read the cluster's Prometheus, see Wiring metrics
  • Agent governance connects to Zentinelle with astro zentinelle connect --url <zentinelle-url> --code-stdin, or from inside the install with python manage.py connect_zentinelle --install --url <zentinelle-url> --code-env <ENV> --register-shared-clusters, which also registers every shared cluster's gateway. astro zentinelle status confirms the connection and each cluster's gateway

Status

See astrolift-opscode/STATUS.md for the canonical state map: what's complete, what's partial, what's stub. Read this before reporting "X is broken"; it might be a tracked TODO.