Skip to content
Grada

IaC-Driven Diagnostic Context (Stateless CLI)

  • Status: Accepted
  • Date: 2026-09-19

Context and Problem Statement

Section titled “Context and Problem Statement”

To provide a seamless developer experience, the grada diagnose command needs to automatically fetch CloudWatch logs and ECS task failures without requiring the user to manually input their AWS Region, Cluster Name, or Log Group.

We needed a mechanism to persist or infer the deployment context locally so the CLI knows where to look for errors.

Decision Drivers

Section titled “Decision Drivers”
  • Statelessness: The CLI should avoid managing internal database files or proprietary local state files that can fall out of sync with actual infrastructure.
  • Single Source of Truth: Terraform is already the declarative source of truth for the project’s infrastructure.
  • Ecosystem Compatibility: Developers often delete node_modules or switch laptops; context retrieval must survive typical Git workflows.

Considered Options

Section titled “Considered Options”
  1. Local State File: Create a .grada/context.json file upon generation. (Rejected: creates state drift and pollutes version control).
  2. AWS Tag Querying: Use the AWS SDK to query all clusters for a specific tag. (Rejected: too slow, requires broad IAM ListClusters permissions, and fails if multiple environments exist).
  3. IaC Parsing (Stateless): Parse the generated terraform/main.tf to extract the AWS Region and infer the cluster name from the local directory structure.

Decision Outcome

Section titled “Decision Outcome”

Chosen Option: IaC Parsing (Stateless). The diagnose command reads the AWS Region directly via regex from terraform/main.tf and constructs standard AWS resource names based on the current working directory.

Positive Consequences

Section titled “Positive Consequences”
  • The CLI remains entirely stateless. If the Terraform files exist, the diagnostics work.
  • Enforces the architectural philosophy that the generated IaC is the ultimate source of truth.
  • Zero additional files are added to the user’s repository.

Negative Consequences

Section titled “Negative Consequences”
  • If a user manually alters the region string inside main.tf using non-standard formatting, the regex parser may fail to detect it, falling back to a default region.