MAAS × LXD

MAAS × LXD: A Narrated CLI Tutorial

This is a step-by-step, hand-holding tutorial for building a modern MAAS lab powered entirely by LXD VM hosts. Every chapter explains what you are doing, why you are doing it, and the MAAS terms involved.

Who this is for

Operators, SREs, homelab builders, and curious engineers who want to stand up MAAS quickly and learn the concepts as they go.

Prerequisites

Ubuntu 22.04+ on your MAAS controller box. sudo privileges. Basic shell familiarity. A network you control (or a dedicated lab VLAN) for DHCP.

What you will build

A single-box MAAS Region+Rack controller, one LXD VM-host, and a set of composed VMs that you commission and deploy entirely from the CLI.

Chapters

  1. Install MAAS (snap), configure Postgres, and initialize Region+Rack
  2. Create an API key, log in with a profile, set DNS forwarders, and sync images
  3. Prepare the LXD host: API, trust, and a bridge
  4. Register the LXD VM-host (pod) in MAAS
  5. Compose VMs with the resources you want
  6. Create an IP range and enable DHCP on the untagged VLAN
  7. Commission, tag, and deploy Ubuntu with cloud-init
  8. Turn JSON into readable tables with jq
  9. Customize storage layouts with the CLI
  10. Create bridges, bonds, and VLANs; link subnets
  11. Organize with pools, zones, and tags
  12. Add operator notes and metadata
  13. Dynamic annotations with jq

Glossary (you will see these terms often)

Region controller
The API/DB brain of MAAS; stores state and serves the UI/API.
Rack controller
The worker agent that handles DHCP/TFTP/Power control close to machines.
Fabric
A layer-2 domain in MAAS. A fabric contains one or more VLANs.
VLAN
A broadcast domain within a fabric. The untagged VLAN is usually the default.
Subnet
An IP CIDR attached to a VLAN. Can be managed (DHCP) or unmanaged.
VM-host (pod)
An LXD or libvirt host that MAAS uses to compose virtual machines.
Commission
The process of discovering hardware, testing, and preparing a machine.
Deploy
Install an OS image onto a machine with optional cloud-init customization.