ubuntu-autoinstall

Autoinstall is the configuration format for Ubuntu Server's Subiquity installer. A version: 1 document tells the installer how to partition, install, and configure the system unattended. This skill is authoring-led (produce a correct autoinstall config from a description) with a strong validation/debug path, aimed at unattended on-prem / air-gapped Ubuntu Server LTS installs.

Autoinstall nests the other two domains:

• its network: key is netplan v2 → use the ubuntu-netplan skill;
• its user-data: key is cloud-config for the installed system → use the

ubuntu-cloud-init skill;

• and the config is itself delivered via cloud-init NoCloud.

See The two delegation boundaries and Delivery.

Authoring workflow

1. Pick the delivery method (Delivery, below). Air-gapped → usually a NoCloud

seed on the ISO/USB or an HTTP seed.

1. Write the `version: 1` document. version is the only schema-required key, but

identity is required at runtime unless user-data: is present.

1. Set the air-gapped essentials — local mirror, proxy, offline fallback (see the

Air-gapped essentials section below for the exact keys).

1. Author `network:` as netplan v2 (ubuntu-netplan skill) and any installed-system

first-boot config under user-data: (ubuntu-cloud-init skill).

1. Validate with the subiquity repo's validate-autoinstall-user-data.py (see

Validation — the script ships in the installer source, not in this skill).

1. Boot with the `autoinstall` kernel keyword to skip the disk-wipe confirmation

for true zero-touch.

The two delegation boundaries (critical)

#cloud-config
# (1) top-level cloud-config here configures the EPHEMERAL installer environment
autoinstall:                  # processed by Subiquity → configures the TARGET system
  version: 1
  network:                    # (2) netplan v2  → ubuntu-netplan skill
    version: 2
    ethernets: { ... }
  identity: { ... }
  user-data:                  # (3) cloud-config → ubuntu-cloud-init skill
    # runs on the INSTALLED system's FIRST BOOT (not at install time)
    packages: [ ... ]

• `network:` is netplan v2 only. Default if omitted is DHCPv4 on en*/eth*.

match: inside ethernets accepts only name/macaddress/driver. (A rarely-used double-wrapped network: {network: {...}} form also validates; prefer the plain form.)

• `user-data:` is cloud-config for the installed system, merged with the

installer-generated user-data. Timing matters: users from identity are created during install; users defined in user-data are created on first boot. Supplying user-data makes identity optional — but then ensure a login path exists. Don't define the same user in both.

Delivery & the NoCloud seed

Autoinstall config reaches the installer in two families:

• Via cloud-init `#cloud-config` user-data — requires the #cloud-config first

line and the config nested under a top-level autoinstall: key.

• Directly on the install media as a file named autoinstall.yaml — here the

autoinstall: wrapper is optional (a bare version: 1 ... works). This wrapper acceptance for on-media files arrived in 24.04.

Precedence — the installer uses the FIRST that exists:

1. --autoinstall <path> CLI arg (empty string explicitly disables autoinstall)
2. kernel cmdline subiquity.autoinstallpath=...
3. autoinstall.yaml at the root of the install system
4. cloud-config-supplied run/subiquity/cloud.autoinstall.yaml
5. cdrom/autoinstall.yaml baked into the ISO

So kernel cmdline and on-media files outrank cloud-config.

NoCloud seeding (the on-prem workhorse — see the ubuntu-cloud-init skill for full NoCloud detail):

• HTTP seed: kernel cmdline autoinstall ds=nocloud-net;s=http://SERVER:PORT/,

serving user-data + meta-data (+ optional network-config) at that base URL.

• Volume seed (USB/ISO): build with cloud-localds seed.iso user-data meta-data;

cloud-init finds it by the cidata/CIDATA filesystem label. meta-data must exist (may be empty: touch meta-data).

• The bare `autoinstall` kernel keyword is separate from ds= — it suppresses

the interactive "Continue with autoinstall?" disk-wipe confirmation. True zero-touch needs both the config delivery and autoinstall on the cmdline.

• Quote the whole kernel -append '... ds=nocloud-net;s=...' — ; is a shell

metacharacter (and ends a GRUB statement).

Full delivery/seeding detail (precedence source, ISO remastering, the on-media "only the autoinstall key" rule) is in references/delivery-and-seeding.md.

Top-level schema (version 1) — quick reference

Only version is schema-required; unknown keys produce a warning in v1 (will be fatal in a future version). Common keys:

Full per-key reference (storage layouts, apt mirror-selection details, identity, ssh, command timing) is in references/schema.md.

Air-gapped essentials

refresh-installer:
  update: false                      # don't try to self-update from the snap store
proxy: http://proxy.internal:3128    # NOT applied to the geoip lookup
apt:
  geoip: false                       # disable geoip.ubuntu.com lookup (10s hang otherwise)
  preserve_sources_list: false
  mirror-selection:
    primary:
      - uri: "http://mirror.internal/ubuntu"
        arches: [amd64]
  fallback: abort                    # set explicitly; don't silently go offline-from-ISO
updates: security

• Wrapping primary inside mirror-selection enables Subiquity's mirror probing

(picks the first usable). A bare primary: list uses legacy curtin behavior.

• apt.fallback ∈ abort | offline-install | continue-anyway. The docs disagree

on the default — always set it explicitly. offline-install falls back to the ISO's seed; continue-anyway is not recommended.

• Snaps requiring the store fail offline — only ship snaps seeded on the ISO, or omit

snaps:. source.id: ubuntu-server-minimal reduces footprint.

storage (quick)

storage:
  layout:
    name: lvm                  # lvm | direct | zfs | hybrid
    password: LUKS_PASSPHRASE  # LVM + LUKS
    sizing-policy: all         # use whole VG ('scaled' default leaves snapshot room)

Pick a disk with match: {ssd: true} / {serial: ...} / {size: largest}. For advanced partitioning use a curtin config: action list (when layout is present, config is ignored). See references/schema.md.

Validation & debugging

# validate-autoinstall-user-data.py ships in the subiquity SOURCE repo — it is NOT
# bundled in this skill. Get it with: git clone https://github.com/canonical/subiquity
# && cd subiquity && make install_deps. Run from that checkout, NEVER as sudo:
python3 scripts/validate-autoinstall-user-data.py user-data            # #cloud-config-wrapped
python3 scripts/validate-autoinstall-user-data.py --no-expect-cloudconfig autoinstall.yaml
cloud-init schema -c user-data                                         # validate the cloud-config body

Install logs live in /var/log/installer/; the delivered autoinstall (with password hash) is saved to /var/log/installer/autoinstall-user-data. Full validation workflow, the JSON schema location, and common pitfalls are in references/validation-and-debugging.md.

Common pitfalls

• Missing #cloud-config header, or a misspelled autoinstall: key → the installer

goes interactive instead of crashing.

• In the on-media autoinstall.yaml, no other top-level keys may sit beside

autoinstall: — it's fatal. (The #cloud-config delivery is the opposite: top-level cloud-config configures the installer env.)

• late-commands run in the installer environment; the target is at /target.

Use curtin in-target -- <cmd> to run inside the installed system.

• interactive-sections: '*' (string) fails schema — use ['*']. If any interactive

section is set, reporting is ignored.

• Quote the password hash and the kernel -append string.
• Don't pin a kernel: together with oem.install: true (conflicting requirements).

Reference files

• references/schema.md — full top-level key reference: storage layouts & curtin

actions, apt mirror-selection, identity/ssh, command timing, all keys. (Has a TOC.)

• references/delivery-and-seeding.md — delivery precedence, NoCloud seeds, ISO/USB,

HTTP serving, zero-touch, the on-media rules.

• references/validation-and-debugging.md — the validator script, JSON schema, logs,

pitfalls, and 24.04-vs-26.04 version notes.

• references/examples.md — minimal config + a complete air-gapped server install.