Skip to main content

Module syntax

isoloom_spec

Module syntax 

Source
Expand description

The spec as an author writes it, version 1: one declaration per machine. A machine is os plus a catalogue service: or a custom app: (or the OS alone); per-target facts live in a top-level overrides:. Parsed once into types that can’t hold an invalid state, with every problem coded and placed (Problem). The plan lowers it into crate::model, the form the backends read, once per target.

Modules§

placeholder
The one placeholder grammar of the whole spec: {{ path }}, in the message, in an app’s templates and in a catalogue entry’s recipe and files. Isoloom fills every placeholder in when it generates (never Jinja2 or envsubst), so every CM tool installs the same bytes.

Structs§

AbsPath
An absolute path in the machine (/etc/app.toml), or a drive path on Windows (C:\inetpub\wwwroot).
App
A custom machine’s recipe.
ApplianceRecipe
A network appliance (app.appliance).
AptWord
An apt suite or component (bookworm, main, nginx).
Argv
A program and its arguments, run as they are (no shell): at least the program.
Build
The project’s own Dockerfile: its folder, or the folder with the file, stage and arguments.
CloudMachine
A machine’s image on a cloud.
CloudOverrides
On one cloud of cloud-vm.
Command
A machine’s own command: a text the shell runs, or a list run as it is, and the directory it runs in.
CommandStep
A command step: a command run once, behind its guard.
Copy
A copy step: a project file or folder copied into the machine as it is.
DockerNetwork
A network on Docker.
DockerOverrides
On the targets that run the Compose file.
EsxiOverrides
On ESXi.
ExternalMachine
An existing machine.
ExternalNetwork
An existing network on the target, by its name there.
ExternalOverrides
On the external target.
ExternalVolume
An existing volume on the platform, by its name there.
FieldPath
A field’s path in the spec: machines.web.ports.site.port, checks[2].http.
File
A file placed on a machine.
FileStep
A file step: a path made a folder, removed, made a link, or downloaded.
Firewall
A firewall step: ports opened in the OS’s own firewall, when one runs.
Group
A group: the machines in it, and the fields they share.
GroupName
A group’s name (www-data, or a Windows group such as Remote Desktop Users).
GroupStep
A group step: a local group, created or brought in line, never deleted.
Hardware
The hardware a machine asks for.
HealthPage
A page a healthcheck requests on the machine itself.
Healthcheck
When a machine counts as healthy, besides its ports answering: a command that succeeds, or a page that answers, tried at its own pace.
HttpsUrl
An https URL (https://nginx.org/keys/nginx_signing.key): every fetch goes over TLS.
Input
One input.
InputName
An input’s name: an environment variable’s (letters, digits and _, not starting with a digit), never starting with ISOLOOM_ (Isoloom’s own variables).
Inputs
The spec’s inputs, by name, in the order written.
KubernetesOverrides
On Kubernetes.
Machine
A machine of the environment.
Mode
A file’s permissions, octal, at most 0777.
NoForm
Why a machine has no form of a kind: the field that rules it out, why, and what to write.
OsRef
A known OS, as a machine’s os names it.
Overrides
The overrides, by target.
Package
A package to install: its name, and its version as its family’s package manager writes it (1.30.6-1~bookworm) when it is pinned. On Windows, a Windows feature (Web-Server).
PackageName
A package’s name, without its version (nginx, libapache2-mod-php), or a Windows feature’s (Web-Server).
PackageVersion
A package’s version, as its family’s package manager writes it (1.30.6-1~bookworm, 1:2.4.62-1, 1.30.6-r1).
Password
A user’s password in a step: a literal, which is lab content (it lands in generated files).
Port
A port a machine answers on.
PortName
A port’s name (site, dns-udp): how messages, checks and outputs refer to it (machines.web.ports.site.published). Lowercase letters, digits and dashes, from a letter, at most 31 characters.
Problem
One thing wrong with a spec.
ProjectPath
A file or folder of the project, relative to its folder, without .. (provision/web.sh; a folder ends with /, site/).
ProviderBoxes
Boxes for the providers the machine’s box has no build for.
ProxmoxMachine
A machine on Proxmox.
ProxmoxOverrides
On Proxmox.
ProxmoxVolume
A volume on Proxmox.
Repository
A repository step: a vendor’s package repository added to the machine’s package manager, its key pinned by the SHA-256 of its file. Its kind (apt, rpm or apk) is the OS family’s.
RepositoryKey
A repository’s signing key, pinned.
RepositoryName
A package repository’s name, in kebab case (nginx, pgdg): it names its source and key files.
ServiceRef
A catalogue service, with its version or without (postgres@16, nginx).
Services
Catalogue services on a machine and their settings.
Sha256
A SHA-256, as sha256sum prints it: 64 lowercase hex digits.
Shared
Shared machine fields, as written (checked where they land, in each machine).
Span
Where a field sits in the file: its line and column, both from 1.
Spans
Each written field’s place in the file, by its path.
Spec
An environment spec, as written. Field order is kept (machines start in the order written).
Template
A template step: a project file whose {{ path }} placeholders Isoloom fills in when it generates, so every CM tool installs the same bytes.
UnitName
A service’s unit name (nginx, php8.2-fpm, W3SVC): a systemd or OpenRC unit, or a Windows service, or a key of the daemon table.
Unresolved
A placeholder that names nothing the spec has, or can’t be read.
UserName
A user’s name (www-data, svc_backup, Administrator).
UserStep
A user step: a local user, created or brought in line, never deleted.
VagrantBox
The controller’s box on Vagrant.
VagrantMachine
A machine’s box on Vagrant.
VagrantOverrides
On Vagrant.
Version
The format version, 1: the only one.
Warning
A warning about a field of the spec.

Enums§

Code
The kind of problem: a stable, kebab-case code that tools and editors can key on.
EnvValue
An environment variable’s value: a fixed text (a number or a boolean read as its text), or a non-sensitive input’s value.
FileSource
Where a file’s contents come from.
FileState
What a file step makes of its path.
FirewallPort
A port a firewall step opens.
Form
How a machine is produced in one form.
Guard
How a step tells it already ran.
HealthProbe
What a healthcheck tries: a command, or a page.
Invocation
A command a step runs: a text the shell runs (sh -c; PowerShell on Windows), or a program and its arguments run as they are.
Kind
What a machine is, besides its OS.
Octets
A machine’s address on a network: one last octet, or several (the first the primary one).
PortProtocol
What a port speaks: TCP or UDP, and for TCP whether probes and checks speak HTTP or TLS.
PortRef
A port a healthcheck names: one of the machine’s ports by name, or a port number.
Publish
Whether and how a port is reachable from the user’s machine (loopback only).
Recipe
A recipe only a container has.
Service
A service step: a daemon enabled at boot and running (a VM), or run by the container (§3 of the configuration model).
Step
One step of the portable recipe. Steps install and configure: they run as root from the project copy at /opt/isoloom, with no network to the other machines and no inputs or secrets (on containers they run at image build time). What needs those goes in setup.
Tpm
A virtual TPM 2.0 (BitLocker, Windows Hello, measured boot).

Functions§

check
The spec’s problems, placed, in file order.
closest
The known name closest to word, when it is close (a typo).
container_form
The machine’s container form, or why it has none.
parse
Reads a spec from its YAML text: the spec, or its problems in file order.
placeholder_problems
The placeholders of text, written at place, that name nothing the spec has, in order: machine is the machine a template is for. Empty when each resolves.
reboots
Whether one of the machine’s steps restarts it (its inputs must outlive the boot).
vm_form
The machine’s VM form, or why it has none.

Type Aliases§

Problems
The problems of a spec, in file order.