Guides on ainfra

Lifecycle operations

Mon, 01 Jan 0001 00:00:00 +0000

Validate

ainfra validate path/to/document.yaml
ainfra validate path/to/document.json --format json

Validation reads a document but does not resolve secret references or run an infrastructure engine.

Check readiness

ainfra doctor
ainfra doctor --format json
ainfra doctor --input .ainfra/hetzner.input.yaml
ainfra doctor --environment development

The input-aware form also checks backend readiness for the intended environment.

Plan

ainfra plan TEMPLATE --input INPUT

For an initialized project, use the declared environment:

ainfra plan --environment development

Treat the plan as sensitive. Review resource ownership, addresses, firewall rules, image selection, and estimated cost. Apply only the returned plan ID:

Local validation

Mon, 01 Jan 0001 00:00:00 +0000

The repository intentionally runs its gates locally. It does not contain GitHub Actions workflow files.

Install security tools

The supported bootstrap installs pinned tools into the ignored .ainfra/tools/ directory:

scripts/bootstrap-security-tools

It installs:

Checkov 3.2.529 in an isolated uv tool environment;
Gitleaks 8.30.1, verified against its release checksum.

Checkov is isolated because its dependency constraints conflict with the project environment. Runtime version checks fail closed.

Run all gates

scripts/validate-all
scripts/test-all

The validation suite covers formatting, typing, contracts, OpenTofu, Ansible, repository policy, Rust Clippy and RustSec checks, Checkov, and Gitleaks. Rust 1.96.1 is pinned in rust-toolchain.toml; the aibox workspace installs Rust, Clippy, Rustfmt, and cargo-audit. Missing required tooling is a failure, not a skipped check.

Authoring templates

Mon, 01 Jan 0001 00:00:00 +0000

Read the template strategy first. This guide covers the concrete authoring workflow.

Choose adaptation or a new template

Adapt an existing template when the provider, resource topology, lifecycle, and security model remain the same. Typical adaptations include:

changing sizes, counts, locations, or opt-in networking through inputs;
adding another explicitly supported operating-system image;
extending an existing Ansible role;
adding a compatible output or capability already understood by ainfra.

Create a new template when the provider changes, the topology has different ownership or teardown behavior, the engine layout changes materially, or the existing template’s security promises would become misleading.