Reference

The reference gives the exact syntax of the Orchestration configuration file and pull request commands, the stategraph CLI, the Stategraph API, and the SQL language.

Configuration reference

Stategraph Orchestration reads its configuration from .stategraph/config.yml. Each page has defaults and examples:

  • access_control: who can run plan, apply, and the other commands
  • apply_requirements: what a pull request must meet before an apply runs
  • automerge: merge the pull request after all directories apply
  • batch_runs: the maximum number of workspaces per CI run
  • config_builder: generate the configuration at runtime with a script
  • cost_estimation: cost estimates with plan output
  • default_branch_overrides: which keys Orchestration reads from the default branch
  • definitions: YAML anchors for reusable configuration
  • destination_branches: which target branches start runs
  • dirs: tags, workspaces, and when-modified rules per directory
  • drift: drift detection and reconciliation schedules
  • enabled: turn Orchestration on or off for a repository
  • engine: the tool that runs plan and apply, and its version
  • hooks: commands and environment variables before and after workflows
  • Ignoring a directory: directories and files that never plan or apply
  • indexer: generate configuration from a repository analysis
  • lock_policy: when Orchestration locks a directory and workspace
  • notifications: what Orchestration posts back to the pull request
  • parallel_runs: how many runs execute concurrently
  • stacks: named groups of dirspaces with shared configuration and ordering
  • storage: where Orchestration stores plan files
  • Tag queries: the query language that matches directories and workspaces
  • tags: custom labels for matching and filtering
  • tree_builder: a custom script that defines the file tree and what changed
  • version: the configuration file format version
  • when_modified: autoplan and autoapply on file changes
  • work_manifests: how long a run has to call home before Orchestration aborts it as stale
  • workflows: the steps of a plan or apply

Pull request commands

Commands are pull request comments that start with stategraph:

CLI reference

The stategraph CLI imports state, plans and applies with Infrastructure as a Database, and queries your infrastructure. Start with CLI reference for installation and the common options.

  • User: identity and tenant membership
  • Capabilities: the default capability set and per-group capability rules
  • Import: one-step state and HCL import
  • States: create, list, import, export, query, and blast radius
  • Terraform: tf plan, tf apply, tf show, and tf mtx for multi-state transactions
  • Refactor: detect and apply HCL refactors
  • Transactions: transaction commands, including plan-time costs
  • SQL: query commands and schema discovery
  • Tenant: gap analysis for unmanaged resources
  • Cost: state and tenant cost, attribution, history, and billing sources
  • Security: scan history, findings, severity rollup, transaction impact, and re-scan
  • HCL: list addresses, evaluate expressions, convert HCL and JSON
  • Diagnostics: trace how your HCL evaluates locally
  • Config: stategraph.json attached files and ephemeral tfvars
  • Utilities: info and version

API

The Stategraph API is the REST API of Orchestration and Infrastructure as a Database. The overview covers the base URL, authentication, pagination, and errors. Each resource has its own page: users, user management, tenants, API keys, states, transactions, queries, cost, security, VCS installations, stacks, the key-value store, and the server.

Common endpoints:

  • GET /api/v1/whoami: current user information
  • GET /api/v1/mql: run an SQL query
  • GET /api/v1/tenants/{tenant_id}/states: list states
  • GET /api/v1/states/{state_id}/instances: list resource instances
  • GET /api/v1/states/{state_id}/costs: cost snapshot of a state
  • GET /api/v1/openapi: the OpenAPI schema

Other reference pages

Common environment variables

Required:

STATEGRAPH_UI_BASE=https://stategraph.example.com
DB_HOST=postgres
DB_USER=stategraph
DB_PASS=password
DB_NAME=stategraph

Optional:

STATEGRAPH_OAUTH_TYPE=google

For all variables, see Environment variables.

SQL quick reference

Basic query:

SELECT * FROM resources WHERE type = 'aws_instance'

Aggregation:

SELECT type, count(*) FROM resources GROUP BY type ORDER BY type

JSON access:

SELECT attributes->>'instance_type' FROM instances

See SQL Syntax.