Module defaults 

Defaults: settings that aren’t the spec’s business but a person’s or a team’s, in layers, the last one winning:

1. built in (the image table in crate::images, each cloud’s region in its generator),
2. the user’s file, $ISOLOOM_HOME/defaults.yml (~/.isoloom/defaults.yml),
3. the project’s file, isoloom.defaults.yml next to the spec (committed: the team’s),
4. environment variables ISOLOOM_<KEY>, __ standing for a dot (ISOLOOM_CLOUD__AWS__REGION),
5. the command line, -s defaults.<key>=<value>.

Mappings deep-merge, so a file that sets one region leaves the others alone. The same -s without the defaults. prefix overrides the spec itself (-s machines.web.vm.os=ubuntu@24.04), for one run.

images:                 # the image table (see Images): OS images, the access machine
  os: { debian-12: { vagrant: my-org/debian-12 } }
  access: { docker: kalilinux/kali-rolling, vm: kali }
vagrant:
  provider: libvirt     # `isothrum up` passes --provider
cloud:
  aws: { region: eu-west-1 }
  azure: { region: westeurope }

Structs

Cloud

One cloud’s entry in the defaults’ cloud: section.

Defaults

The typed defaults, once the layers are merged. Unknown keys are errors.

Layer

One layer’s contribution: where it came from, and what it set.

Resolved

The merged defaults with, for every leaf, the layer that set it last.

Sources

What a project’s defaults are read from: the project, the --images table, its profile, the command’s -s and the host it runs on.

Vagrant

The defaults’ vagrant: section.

Constants

BUILTIN_REGIONS

Each cloud’s built-in region, as its generator writes it. A test keeps them equal.

PROJECT_FILE

The project-level file, next to isoloom.yml.

Functions

apply_to_files

Applies the defaults that change generated files: each cloud module’s region default. (Images are applied to the spec before generating; vagrant.provider at run time.)

builtin

What the built-in layer holds, for isoloom defaults --system: the clouds’ regions (the image table is documented on its own page and read from the code).

from_env

ISOLOOM_CLOUD__AWS__REGION=x -> ("cloud.aws.region", "x"). Only the defaults’ sections are read (ISOLOOM_HOME, ISOLOOM_DERIVED and the publish variables mean other things).

leaves

Dotted paths of every leaf of a value.

load

Reads every layer for a project: the user’s file, the project’s, the profile, --images, the host’s ISOLOOM_* variables, then the -s overrides.

merge

Deep-merges from into into: mappings key by key, anything else replaced.

override_spec

The spec’s YAML with -s key=value overrides applied (keys without the defaults. prefix), before it is parsed: machines.web.vm.os=ubuntu@24.04, networks.lab.internet=false.

override_spec_with

override_spec with base (a profile’s spec) deep-merged first.

parse_set

key=value of a -s.

resolve

Merges layers in order; later ones win leaf by leaf.

scalar

A value as YAML would read it (3 a number, true a boolean, else text).

set_region

The module text with its variable "region" default replaced.

user_file

The user’s defaults file, in Isoloom’s home on host.