Concepts on ainfra

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.

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.

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/.

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.