Reference on ainfra

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.

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.

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.

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.

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.