Concepts overview
This section defines the vocabulary Grid uses end-to-end. Read it before authoring JSON or operating the console at scale.
Core ideas
| Concept | Meaning |
|---|---|
| Intent (desired state) | Git-tracked JSON that declares what should exist |
| Unit | One JSON file → one inventory identity → one engine root (Terraform workspace or workload release) |
| Engine | How a unit is realized — terraform or kubernetes (GitOps) |
| Project | Boundary / app slug (projects/<slug>/…) |
| Provider | Path segment and provider field — any catalog id, not a preferred cloud |
| Environment | Path segment and metadata.environment (development, staging, production, or custom) |
| Sync | Pull Git → upsert inventory → mark missing paths stale |
| Release | Plan / apply / destroy job with logs, audit, optional approval |
| Module bank | Versioned Terraform modules (grid-terraform) for the terraform engine |
| Archive | Generated instance Terraform next to intent — part of the exit ramp |
| Remote state | Shared Terraform state backend for terraform-engine units on a control plane |
| Catalog | Known subtypes per provider (CLI maturity + console flags) |
End-to-end path
Author JSON in Git
→ Sync into GRID_CONFIG_ROOT
→ Unit appears in Infrastructure (if console catalog allows)
→ Plan / apply release via the unit’s engine:
· terraform → plan/apply + remote state + archive/
· kubernetes → cluster GitOps
→ Optional metrics labeled with grid_unit_id
Deep dives
| Topic | Page |
|---|---|
| Path layout & samples | Desired-state layout |
| JSON fields, dependsOn, kinds | Unit JSON |
| Sync, stale, drift, ids | GitOps sync |
| Plan / apply / destroy | Release lifecycle |
| Modules & pins | Module bank |
| State + archive | Archive and remote state |
| In-cluster apps / Argo | Kubernetes workloads |
| Leaving without a black box | Exit ramp |
Design principles (why it feels this way)
- Path is identity. Renaming a file path changes how state, archive, and inventory are addressed unless you migrate deliberately.
- Reference, don’t merge.
dependsOnwires remote state (terraform); dependents remain separate applies. - Git delete ≠ cloud / cluster delete. Stale is an operator signal; destroy is explicit.
- Console flags ≠ CLI capability. The UI may hide a provider or engine that the CLI catalog already describes.
- Engines share Sync and RBAC. Terraform and Kubernetes workloads differ in how they apply, not in who owns intent.
- Host monitoring is separate. Prometheus runs beside Grid, not inside the Compose app containers.