Infra Lang
Write infrastructure once, compile it to Kubernetes, Compose, or GitHub Actions.
Current release: v1.0.1 — quality, performance & hardening (see CHANGELOG.md).
Infra Lang is an Infrastructure-as-Code DSL for DevOps engineers, SREs, and
platform teams. You describe your application — services, databases, queues,
secrets, and pipelines — in one declarative .infra file, and Infra Lang
compiles it to Kubernetes YAML, Docker Compose, Terraform HCL, or a GitHub
Actions workflow. Instead of hand-writing and maintaining the same app in four
different formats, you maintain one source of truth.
Quick demo
A single .infra file describes a service:
# app.infra
service api {
image: "myapp/api:v1.0.0"
replicas: 3
port 8080
health http("/health")
resources {
requests { cpu: 200m, memory: 256Mi }
limits { cpu: 1000m, memory: 512Mi }
}
}
Compile it to Kubernetes:
infra compile app.infra --target kubernetes
Infra Lang produces the matching Deployment and Service:
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: api
template:
spec:
containers:
- name: api
image: myapp/api:v1.0.0
ports:
- containerPort: 8080
name: port-0
resources:
requests: { cpu: 200m, memory: 256Mi }
limits: { cpu: 1000m, memory: 512Mi }
readinessProbe:
httpGet: { path: /health, port: 8080 }
---
apiVersion: v1
kind: Service
metadata:
name: api
spec:
selector:
app.kubernetes.io/name: api
ports:
- port: 8080
targetPort: 8080
The same file compiles to Docker Compose with no rewriting:
infra compile app.infra --target compose
A pipeline block compiles to a GitHub Actions workflow:
pipeline ci {
trigger { branches: ["main"] }
stages {
test: { runsOn: "ubuntu-latest" steps { t: { run: "pytest" } } }
}
}
infra compile app.infra --target github
Features
- 11 top-level resource types —
service,database,cache,queue,storage,network,secret,config,pipeline,environment,cluster. - 5 compilation targets — Kubernetes (17 resource kinds), Helm charts, Docker Compose, Terraform HCL (AWS/GCP/Azure), GitHub Actions.
- Compiler-grade validation — 30+ error codes with source locations and actionable hints; invalid configs fail before anything is emitted.
- Built-in security linter (SEC001–SEC010) and reliability linter
(REL001–REL014);
Error-severity findings block compilation. - A language server — context-aware completion, hover docs, live
diagnostics with links and related info, go-to-definition, find-references,
workspace symbols, symbol rename, signature help, document highlight,
semantic tokens, folding, formatting, and quick-fixes — all across every
.infrafile on disk. - A formatter, REPL, and diff engine —
infra fmt,infra repl, andinfra difffor reviewing changes. - Direct execution —
infra up/infra downapply and remove resources on a live cluster (kubectl apply/delete), Docker Compose (docker compose up/down), or Helm (helm upgrade --install/uninstall), with a--dry-runto preview commands. - Cost estimation —
infra costestimates the monthly cloud cost of a.infrafile (per-resource table,--jsonfor CI gates,--currency). - Visual infrastructure dashboard —
infra serve/infra uirender any.infrafile as an interactive, fully-offline HTML dashboard (see below). - Architecture insight reports —
infra explainrenders a deterministic overview (costs, dependencies & SPOFs, security, reliability, what-if scenarios) for humans (markdown/text) or AI agents (compact JSON). - Auto-fix for common findings —
infra doctor --fixsafely rewrites hardcoded secrets intosecret_storereferences and fills in missing memory limits, health checks, backups and graceful-shutdown hooks. - SBOM generation —
infra sbomemits SPDX 2.3 / CycloneDX 1.5 / markdown from the images your file already declares, with tag-mutability risk badges. - FinOps CodeLens — the language server shows cost, replica, warning and reliability-grade badges right above every block in your editor.
- Reusable pieces — template-string interpolation,
importwith cycle detection,extendsinheritance, 25+ stdlib functions and a prelude of shared constants.
Visual Infrastructure Dashboard (infra serve / infra ui)
Since 0.5.2 Infra Lang ships a local, zero-dependency dashboard that
renders any .infra file as a single self-contained HTML page:
infra serve app.infra # http://localhost:8080 (opens browser)
infra serve app.infra --port 9000 # custom port (loopback only)
infra serve app.infra --no-browser # serve without opening a browser
infra serve app.infra -e staging # preview an environment overlay
infra serve app.infra -o report.html # one-shot static export, then exit
infra ui app.infra # alias for `infra serve`
The dashboard shows the architecture DAG (services, databases, caches and
queues with depends_on edges), a FinOps cost report (monthly estimate
with a per-resource share chart), a live-drift panel and a switcher for
every environment overlay declared in the file. It inlines all CSS/JS — no
CDN, no external requests — and binds to 127.0.0.1 only.
Since 0.5.5 the same commands also compare two environments side by side (diff table with added/removed/changed rows and per-side cost estimates) and export the architecture DAG as a self-contained SVG:
infra serve app.infra --compare base prod # served compare page
infra serve app.infra --compare base prod -o cmp.html # static report
infra graph app.infra -o dag.svg # or: --format svg
base refers to the file without any overlay. The Architecture tab of the
dashboard additionally embeds a Download SVG button with the very same
document.
Since 0.5.6 the Drift tab can also probe the live state (read-only
kubectl / docker compose probes — the same engine as
infra doctor --check-drift --live):
infra serve app.infra --live-drift # k8s probe (kubectl)
infra serve app.infra --live-drift -t compose # Docker Compose probe
The panel renders IN-SYNC / DRIFTED badges with a per-field diff
table, or a readable failure badge (CLI TOOL MISSING, PROBE TIMEOUT, CLUSTER UNREACHABLE) when the tool or cluster is
unreachable — it never crashes the server.
Web Playground & In-Memory Web API (since 0.6.0)
The full compiler can run in your browser via WebAssembly (Pyodide) —
no installation, no server round-trip. The web/ directory ships a
static playground (host it on GitHub Pages/Vercel along with the
infra_lang-*-py3-none-any.whl): Monaco editor with .infra syntax
highlighting, example picker, one-click outputs for Docker Compose /
Kubernetes / Terraform, the architecture SVG and the visual dashboard, a
?code=<base64> share link, and an enterprise waitlist section.
The browser talks to infra.web_api — a pure in-memory API that also
works in any embedded Python (notebooks, serverless, CI bots):
from infra import web_api
result = web_api.compile_to_target(source, "compose") # success/files/errors
html = web_api.generate_ui_report(source) # dashboard (or compare)
svg = web_api.export_dag_svg(source) # architecture graph
ast = web_api.get_ast_json(source) # JSON-safe AST
web_api.list_examples() # hello_world, web_app, …
web_api never touches the disk, processes or a browser API — errors are
returned as data — so it is safe to embed anywhere.
Production & Enterprise: deploy, workspace, compliance, locking (since 1.0.0)
🚀 Safe deployments with infra deploy / infra rollback
Dry-run first, always: the default prints a structured plan (resources,
monthly cost, SEC*/REL* risks, exact commands) and touches nothing.
--apply executes through docker/kubectl/helm/terraform, verifies
the rollout and auto-rolls back to the last good snapshot on failure.
Every revision is recorded locally with its manifests:
infra deploy app.infra -t kubernetes # dry-run plan (default)
infra deploy app.infra -t compose --apply # execute + verify rollout
infra deploy app.infra -t k8s --apply --timeout 180
infra rollback app.infra # history table
infra rollback app.infra --to-revision r0001 # restore a revision
🗂 Multi-project workspaces
infra-workspace.yaml groups projects with per-project targets, global
policies (applied to every sub-project, no opt-out) and global
environment overlays (merged onto each project, workspace wins):
infra workspace init --template micro
infra workspace list # name / path / target / validation status
infra workspace check # batch validation, exit 1 on any error
infra workspace compile --project api -o dist/
🛡 Compliance audits (SOC 2 & CIS)
infra compliance app.infra # all standards, [PASS]/[FAIL]
infra compliance app.infra -s soc2 -f markdown -o audit.md
Every control is rendered with norm IDs (CC6.1 … , CIS 5.1.1 …), the
triggering SEC*/REL* codes, file locations, fix recommendations and a
Compliance Score (passed/total × 100); exit 1 on any violation.
🔒 Atomic state locking
WorkspaceLock("my_project", operation="deploy") guards
.infra-state/ mutations with an O_EXCL-atomic JSON lock file
(stdlib only; stale-owner detection via os.kill(pid, 0) / Windows
tasklist, auto-reclaim of stale locks). Stuck lock?
infra workspace unlock my_project (refuses live owners; --force only
when you are sure).
Insight & Intelligence: explain, CodeLens, auto-fix, SBOM (since 0.9.0)
🧠 Understanding Your Architecture
infra explain turns any .infra file into a deterministic insight report —
no AI/ML runtime, just the existing static analyzers plus templated prose:
infra explain app.infra # markdown report for humans
infra explain app.infra --format text # terminal-friendly plain text
infra explain app.infra --for ai # compact JSON + _meta/_summary
infra explain app.infra --sections cost,security
Seven sections: Overview (with top-3 cost drivers), Services (with an A–F reliability grade each), Dependencies (including single points of failure), Cost Breakdown (compute / storage / network / managed), Security Warnings, Reliability Report, and What-If scenarios (zone-failure blast radius, doubling replicas). The same report is one click away in the Web Playground's 🧠 Insight Report tab.
💰 See Cost & Risk Inline
The language server now answers "what does this cost and how risky is it?"
directly in your editor. A CodeLens badge above every service, database,
cache, queue, storage and environment block shows monthly cost,
replicas, SEC*/REL* warning counts and a reliability grade:
💰 $47.20/mo · ⚡ 3 replicas · 🔒 2 warnings · 📊 Grade: A
Fully configurable (infra.codelens.enabled, showCost, showSecurity,
showReliability, showEmoji), with an ASCII fallback for terminals.
Hover cards also carry a "💡 Insight" section per block.
🔧 Auto-Fix Common Issues
infra doctor --fix rewrites your file in place (keeping a
file.infra.bak backup by default), applying deterministic fixes for the
most common security & reliability findings:
| Code | Fix applied |
|---|---|
| SEC001 | hardcoded secret env → from secret "auto_secrets".VAR + generated secret_store |
| SEC003 | mutable :latest tag → inline FIXME comment (never guesses versions) |
| REL003 | missing memory limit → resources { limits { memory: 512Mi } } |
| REL004 | missing health check → health http("/health") { interval: 30s timeout: 5s } |
| REL006 | missing backup → backup { enabled: true schedule: "0 2 * * *" retention: 7d } |
| REL009 | multi-replica without graceful shutdown → lifecycle { preStop … } |
infra doctor app.infra --fix # apply all fixes (with backup)
infra doctor app.infra --dry-run # colored unified diff, no write
infra doctor app.infra --fix --only SEC001,REL003
infra doctor app.infra --fix --no-backup # live dangerously (or in git)
Round-trip guaranteed: untouched parts of your file print back byte-stable.
📋 Enterprise-Ready SBOM
infra sbom produces a Software Bill of Materials from the container images
your .infra file already declares — offline, deterministic, auditable:
infra sbom app.infra # markdown table + risk badges
infra sbom app.infra --format spdx-json # SPDX 2.3 JSON
infra sbom app.infra --format cyclonedx-json # CycloneDX 1.5 JSON
infra sbom app.infra --include-transitive # + best-effort base images
infra sbom app.infra --registry-check # best-effort availability probe
Every image is scored for tag mutability: :latest & friends → HIGH,
pinned tags → LOW, @sha256: digests → ZERO. Attach the SPDX or
CycloneDX output to releases, or diff the markdown in code review.
Interactive learning & playground (since 0.8.0)
Learn the language in your terminal — five guided lessons from a single service to network policies, with tasks verified by the real parser and validator:
infra learn # interactive walk-through
infra learn --list # the five lessons at a glance
infra learn --lesson 2 # show one lesson
infra learn my.infra --verify 2 # check your solution for lesson 2
Upgraded Web Playground (web/) — pick one of four architecture
templates (web app, microservices, cloud-native profile, cron
pipeline), watch the DAG Graph tab redraw live, then hit Download
All Manifests (.zip) to get Compose + Kubernetes + Terraform + Helm
outputs in a single archive — all inside the browser.
VS Code snippets — type infra- and complete network_policy,
secret_store, autoscale, schedule, disruption blocks or a schema
header in seconds.
Visualization & Schema export (since 0.7.1)
Native PNG architecture graphs — the dashboard's architecture DAG exports to PNG with a pure-Python Pillow drawing engine (dark theme, rounded node cards with image tags, arrowed edges — no Cairo, Graphviz or headless browser):
infra graph app.infra --format png -o graf.png # or just: -o graf.png
The dashboard served by infra serve / infra ui also offers one-click
Download SVG and Download PNG buttons on the architecture card —
payloads travel as data URIs, so saving is instant and offline.
JSON Schema of the DSL — editor/tooling integration via draft-07:
infra schema -o infra-schema.json # or stdout without -o
The schema covers every top-level block (service, database,
environment, network_policy, secret_store, …) with exact type
enums and documented properties.
Team Integration: CI comments, alerts, policies (since 0.7.0)
Everything a team needs around pull requests — at zero cost, no SaaS:
PR comments with cost delta & security — infra ci-comment renders a
Markdown report (changes, monthly cost delta vs --base, SEC*/REL*
findings) ready for gh pr comment, with CI gates:
infra ci-comment infra/app.infra --base /tmp/base.infra \
--max-monthly-cost 500 --fail-on-security # exit 1 when a gate fails
Or use the ready-made GitHub Action (see
docs/ci_integration.md):
- uses: TuviDev/infra-lang/.github/actions/infra-check@v0.7.1
with:
files: "infra/**/*.infra"
base-ref: origin/main
max-monthly-cost: "500"
fail-on-security: "true"
Alerts — Slack / Teams / Discord webhooks for budget overruns,
security violations and live drift, from flags or .infra-alert.yml
(never log full webhook URLs — they carry secrets):
infra alert infra/app.infra --webhook "$SLACK_WEBHOOK" --format slack \
--max-monthly-cost 500 --live-drift -t k8s -n default
Team policies — declarative infra-policy.yaml (budgets, no
hardcoded secrets in env, no :latest tags), enforced with stable
POLxxx codes:
infra policy-check infra/app.infra # auto-discovers ./infra-policy.yaml
infra policy-check infra/app.infra -p policy.yaml -f json
Static team dashboard — publish the visual dashboard as an offline site for GitHub Pages/S3, with JSON summary and append-only cost/drift history:
infra ui infra/app.infra --publish site/ # index.html + envs/ + data/
Try it in Codespaces
Click the button below to open this project in GitHub Codespaces:
No local installation needed — full dev environment in about 2 minutes (Python 3.12, Docker-in-Docker, kubectl/helm, Ruff/Mypy extensions).
Installation
pip install infra-lang
With the language server (recommended for VS Code):
pip install 'infra-lang[lsp]'
Verify:
infra --version
infra --help
Note: For the latest development version, install from Git:
pip install git+https://github.com/TuviDev/infra-lang.git
Requirements: Python 3.11+.
Getting started
Full documentation is hosted at TuviDev.github.io/infra-lang.
The fastest path is the 5-minute quickstart. In short:
- Write a
.infrafile (see the demo above). - Validate it:
infra validate app.infra - Compile to a target:
infra compile app.infra --target kubernetes - Inspect the output in
infra-out/, or preview with--dry-run. - Iterate with
infra fmt app.infraandinfra diff app.infra app2.infra.
There is also a guided tutorial and commented examples.
Supported targets
| Target | Command | What it generates |
|---|---|---|
| Kubernetes | -t kubernetes |
Deployments, Services, Ingress, StatefulSets, PVCs, ConfigMaps, Secrets, CronJobs, HPA, PDBs, NetworkPolicies, ResourceQuotas, Namespaces, RBAC, TopologySpreadConstraints |
| Helm | -t helm |
A complete chart: Chart.yaml, values.yaml, templates/, _helpers.tpl, .helmignore |
| Docker Compose | -t compose |
docker-compose.yml, .env.example, Makefile |
| Terraform | -t terraform |
main.tf, variables.tf, outputs.tf, providers.tf (AWS/GCP/Azure) |
| GitHub Actions | -t github |
.github/workflows/*.yml, dependabot.yml |
Not every resource type maps to every target — for example, pipeline compiles
only to GitHub Actions, and cluster only to Terraform. See the
support matrix for the
full mapping.
Documentation
The documentation is hosted at TuviDev.github.io/infra-lang.
| Doc | What it covers |
|---|---|
| Quickstart | 5-minute first run |
| Language spec | Full DSL reference (blocks, fields, error codes) |
| Support matrix | Which resources map to which targets |
| LSP / editor support | VS Code extension and language server |
| Known limitations | Honest boundaries of the project |
Contributing
Contributions are welcome. See CONTRIBUTING.md for how to set up a dev environment, add a backend or a grammar rule, and the coding standards (ruff, mypy). Please read our Security policy before reporting a vulnerability.
License
Licensed under the MIT License.
Infra Lang is inspired by the ideas behind Terraform, Score, and Pulumi: declarative infrastructure that is easy to read and hard to get wrong.
Metadata
Release files for infra-lang 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| infra_lang-1.0.1.tar.gz | 271.6 kB | Without provenance | Details for infra_lang-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| infra_lang-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for infra_lang-1.0.1-py3-none-any.whl |
Total release size: 597.4 kB
Release files / infra_lang-1.0.1.tar.gz
| Download URL | infra_lang-1.0.1.tar.gz |
|---|---|
| Size | 271.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ab22e183183aa16b424a7edfd516e06e630c8f91fbfbcc8ea3d65baf2ab9c40a
|
|
BLAKE2b-256 checksum How to use checksums |
153c6d1fad7bb255db5124225dcf4e0bea04d5530b85e8cbe29a8a05ddd02bd3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / infra_lang-1.0.1-py3-none-any.whl
| Download URL | infra_lang-1.0.1-py3-none-any.whl |
|---|---|
| Size | 325.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fa88bdbf5ff1608c6a324a71e103383706631128b565e2bfa02990abb09b0219
|
|
BLAKE2b-256 checksum How to use checksums |
8dcf360c3912696b7a355e68e44ec2282b3802494c89ae0eed529f5448659c7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for infra-lang 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.