ainfra

Installation

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

The supported installer downloads only from the canonical GitHub release, verifies the release checksum before extraction, and installs to $HOME/.local/bin by default. It never invokes sudo.

curl --proto '=https' --tlsv1.2 --fail --location \
 --proto-redir '=https' \
 https://github.com/projectious-work/ainfra/releases/latest/download/install.sh \
 -o /tmp/ainfra-install.sh
sh /tmp/ainfra-install.sh

Review a downloaded installer before running it when that is required by your local security policy.

To install a specific stable version:

AINFRA_VERSION=0.1.0 sh /tmp/ainfra-install.sh

To select another unprivileged destination:

Architecture

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

Portfolio boundary

ainfra provisions and configures infrastructure targets. It hands a non-secret output contract to downstream systems:

InfrastructureTemplate + TemplateInput
 │
 ▼
 validation and policy
 │
 ▼
 OpenTofu plan and state
 │
 ▼
 Ansible host configuration
 │
 ▼
 InfrastructureOutput
 │
 ▼
 workload deployment

OpenTofu owns infrastructure desired state. Ansible owns host configuration. The ainfra wrapper validates contracts and visibly orchestrates those tools. Every wrapper operation has a documented direct-tool equivalent.

Branching strategy

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

ainfra uses separate long-lived lanes for stable maintenance and v0 development.

Long-lived branches

main represents the latest published stable release. Stable release tags are merged here after publication. It is the repository’s default branch.
v0.x-maintenance carries supported fixes for published v0 releases. Features are not backported unless explicitly approved.
v0.x-dev is the normal integration branch for v0 implementation. Feature branches and pull requests target this branch.
v0.x-pre-release receives selected promotions from v0.x-dev for alpha, beta, and release-candidate validation. Prerelease tags are created only here.
v0.x-release is promoted from the accepted prerelease state for general availability. Stable v0 tags are created here and then merged into main.

Promotion flow

feature branch
 → v0.x-dev
 → v0.x-pre-release
 → v0.x-release
 → main

Maintenance fixes begin on v0.x-maintenance. Promote a maintenance release through the same validation expectations, and merge any still-relevant fix forward into v0.x-dev.

CLI

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

ainfra init [--name NAME] [--template TEMPLATE]
 [--environment ENVIRONMENT] [--format text|json]
ainfra validate [<path-or-template>] [--input INPUT]
 [--format text|json]
ainfra doctor [--input INPUT | --environment ENV] [--format text|json]
ainfra plan [<template> --input INPUT | --environment ENV]
 [--destroy] [--format text|json]
ainfra apply [<template> --input INPUT | --environment ENV]
 --approve PLAN_ID
ainfra up --environment ENV --approve PLAN_ID --known-hosts FILE
 [--format json|yaml]
ainfra destroy [<template> --input INPUT | --environment ENV]
 --approve-destroy PLAN_ID
ainfra down --environment ENV --approve-destroy PLAN_ID
ainfra outputs [<template> | --environment ENV] --run PLAN_ID
 [--format json|yaml]
ainfra configure [<template> | --environment ENV] --run PLAN_ID
 --known-hosts FILE [--check]
ainfra status --environment ENV [--format text|json]
ainfra legacy inspect [--root PYTHON_REPOSITORY] [--format text|json]
ainfra inventory --output OUTPUT --destination DESTINATION

`init`

Initializes the current directory without contacting a provider or invoking OpenTofu or Ansible. It creates ainfra.yaml, ainfra.lock, and one example under environments/, then adds .ainfra/ to .gitignore.

Create and tear down a Hetzner environment

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

This tutorial creates a disposable Hetzner Cloud environment with the hetzner-kubernetes-baseline template and the ainfra CLI. It provisions one Debian 13 control-plane-capable host, a private network, firewall rules, and the operator SSH key registration. It then destroys every managed resource.

Cost and responsibility

The apply step creates billable Hetzner resources. Check current pricing and quotas in your Hetzner project before continuing. Keep the input, local state, plan records, token, and destroy procedure available until independent checks confirm that no managed resources remain.

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:

Quickstart

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

This guide takes you from an installed binary to a reviewed disposable- infrastructure plan. Applying the plan creates billable Hetzner resources, so the final apply and destroy commands remain explicit.

Prerequisites

A verified ainfra release from the installation guide
OpenTofu
Ansible
A Hetzner Cloud project token for live operations
An existing SSH public key

Install and validate

Check local readiness without changing infrastructure:

ainfra --version

Initialize a disposable project

Create a separate project and initialize it:

Contracts

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

All schemas use JSON Schema draft 2020-12 and reject unknown fields.

Contract	Source	Purpose
`InfrastructureTemplate/v1alpha1`	`schemas/template-manifest.v1alpha1.json`	Template engines, paths, capabilities, and invariants
`TemplateInput/v1alpha1`	`schemas/template-input.v1alpha1.json`	Non-secret operator intent and credential references
`InfrastructureOutput/v1alpha1`	`schemas/template-output.v1alpha1.json`	Stable, non-secret handoff to downstream systems
`ainfra.plan/v1alpha1`	`schemas/plan-record.v1alpha1.json`	Exact reviewed-plan binding for lifecycle authorization
`ainfra.plan/v1alpha2`	`schemas/plan-record.v1alpha2.json`	Project-bound lifecycle authorization
`ainfra.run/v1alpha2`	`schemas/run-record.v1alpha2.json`	Immutable run identity
`ainfra.run-event/v1alpha1`	`schemas/run-event.v1alpha1.json`	Append-only lifecycle evidence
`ainfra.status/v1alpha1`	`schemas/status.v1alpha1.json`	Sanitized local status output
`ainfra.legacy-inspection/v1alpha1`	`schemas/legacy-inspection.v1alpha1.json`	Read-only legacy evidence report

Compatibility

The apiVersion is locked through the v1 series. An incompatible v2 requires a full migration rather than silent coercion.

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.

Security model

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

Assumptions

Cloud credentials, state, plans, private keys, generated inventories, and provider logs may contain sensitive information. The local operator environment is trusted to hold short-lived credentials; the repository and ordinary output documents are not secret stores.

The model reduces accidental exposure and unsafe defaults. It does not turn an untrusted workstation or compromised provider account into a trusted one.

Invariants

Operators supply public SSH keys; ainfra never creates private keys.
Root login and password SSH are prohibited.
SSH host-key checking is mandatory.
Management ingress is private by default.
Public IPv4 allocation is opt-in.
Private networks use narrow RFC1918 ranges and reject broad management ranges.
Non-disposable environments require encrypted, locked, recoverable remote state with TLS and access control.
Providers, collections, roles, images, and scanners are pinned.
Standard outputs contain references to credentials, never their contents.
Destructive operations name their exact reviewed destroy-plan ID and require explicit approval.

Layered verification

Layer	What it proves
JSON Schema	Document shape, version, enums, and unknown-field rejection
Policy checks	Cross-field security invariants
OpenTofu validation	Provider configuration and expression correctness
Checkov	Known infrastructure-policy findings
Gitleaks	Repository secret patterns
Plan assertions	The proposed resource graph matches safety expectations
Ansible checks	Syntax, lint, check mode, and idempotence
Disposable live test	Provider behavior and end-to-end teardown

No single layer is treated as complete proof. Live Hetzner verification is the final cost-bearing gate and requires explicit approval.

Project configuration and locking

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

An ainfra project separates committed intent from local operational state:

my-infrastructure/
├── ainfra.yaml
├── ainfra.lock
├── environments/
│ └── development.yaml
└── .ainfra/

ainfra.yaml names the project, selects one built-in template, and maps environment names to TemplateInput files. Those files hold non-secret provider, topology, network, access, and state intent. Credentials remain external references such as HCLOUD_TOKEN.

ainfra.lock is generated by ainfra init and should normally be committed. It pins the template source, name, manifest version, and SHA-256 digest of the complete embedded template. Normal project validation never rewrites it.

Templates

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

ainfra embeds its built-in templates in the release binary. Their reviewed source remains under templates/; each directory contains an ainfra-template.yaml manifest and a template-specific README.

Template	Source	Purpose	Status
`hetzner-kubernetes-baseline`	`templates/hetzner-kubernetes-baseline`	Private-networked, hardened Debian 13 hosts prepared for a later Kubernetes installation	Initial validated template

The binary does not currently use an external registry or download templates at runtime. Clone the repository only when you want to inspect or adapt source.

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.

Hetzner Kubernetes-ready baseline

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

The baseline provisions one control-plane-capable Debian 13 host and optional workers on a narrow private network. It does not install Kubernetes.

OpenTofu creates:

a project-owned private network and subnet;
a narrowly scoped firewall;
registrations for operator-supplied SSH public keys;
Debian 13 servers;
public IPv4 or IPv6 attachments only when explicitly enabled.

Ansible configures:

secure SSH daemon policy;
nftables host firewall policy;
unattended security updates;
persistent journal and audit configuration;
Kubernetes-ready operating-system prerequisites.

Networking

Public IPv4 and IPv6 are independent and disabled in the standard input. Disabling IPv4 means no billable public IPv4 resource or attachment may exist. The generated inventory prefers private management addresses.

State and secrets

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

State

Non-disposable environments must use a capability-validated remote backend providing encryption at rest, locking, version recovery, TLS, and access control. S3-compatible services qualify only after integration tests prove those capabilities.

Local state is limited to inputs explicitly marked disposable and produces a prominent warning. The wrapper does not provision, repair, or silently migrate a backend.

Backend configuration stays outside version control. The repository ignores local state, plans, .terraform/, and .ainfra/.

Acceptance matrix

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

Requirement	Evidence
Versioned strict contracts	Schema and positive/negative fixture tests
Visible wrapper commands	CLI, runner, lifecycle, and adapter tests
No template hardcoding	Contract-driven discovery and fixtures
Pinned Hetzner template	Provider lock, image enum, validation
Secure SSH and keys	Schema, policy, plan, and host tests
Safe state	Backend capability validation
Secret-free output	Strict schema, redaction, Gitleaks
Local validation gates	`scripts/validate-all`, `scripts/test-all`
Standalone Rust product	No Python package; installed-shell no-tool test
Disposable lifecycle	Approved live apply, idempotence, and teardown
Clear portfolio boundaries	README and architecture review
No unsafe donor behavior	Negative policy and plan tests
No GitHub workflows	Repository-policy test

Every release criterion maps to an automated local check or documented manual verification with sanitized evidence. A claim without one of those forms of evidence remains unverified.

Template strategy

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

An ainfra template is a versioned, self-contained infrastructure implementation behind a common contract. Templates share lifecycle and safety rules, but keep provider-specific OpenTofu, host configuration, and operational documentation together.

Why templates exist

The template boundary separates three concerns:

The ainfra wrapper owns discovery, contract validation, reviewed-plan binding, sanitized outputs, and ownership-scoped destruction.
A template owns provider resources, host configuration, supported images, capabilities, and provider-specific defaults.
The operator owns the selected template, non-secret intent, credential references, reviewed plan, and explicit lifecycle approvals.

This lets a template evolve without hiding OpenTofu or Ansible. Every engine working directory remains directly usable and inspectable.