When provisioning Linux instances in modern cloud environments or deploying embedded IoT devices en masse, administrators frequently encounter the “golden image” problem. You create a minimal, pristine OS image (e.g., 2 GB in size) to flash onto a 500 GB NVMe drive. Upon first boot, the operating system is constrained to the 2 GB partition, wasting 498 GB of hardware. Historically, solving this required fragile, imperative bash scripts injecting fdisk, parted, or resize2fs commands into the early boot sequence (often via cloud-init or rc.local). These scripts are highly prone to failure if disk geometry changes. To resolve this organically, systemd introduced systemd-repart, a declarative partition table provisioner that automatically grows, formats, and manages GPT partitions during the early initramfs boot phase.
The Architecture of systemd-repart
systemd-repart operates entirely on the declarative state model. Rather than writing a script that issues raw sector manipulation commands, you define the desired end-state of the GUID Partition Table (GPT).
The daemon executes incredibly early in the boot process (often before the root filesystem is even remounted read-write). It interrogates the physical block device (e.g., /dev/sda or /dev/nvme0n1) and compares the current GPT layout against your declarative configuration files located in /etc/repart.d/ or /usr/lib/repart.d/.
If the physical disk is larger than the defined partitions, systemd-repart mathematically calculates the free sectors and safely expands the partition table to fulfill the declarative policy. It can grow the root partition to fill the remaining disk, create a dedicated swap partition based on a percentage of physical RAM, or automatically format a new data partition with an XFS or ext4 filesystem, all without human intervention.
Authoring Declarative Partition Policies
Configuration files utilize standard systemd INI syntax and are processed in alphabetical order.
To configure systemd-repart to automatically expand the root partition to consume all available unallocated space on the drive, create a file named /etc/repart.d/50-root.conf:
[Partition]
# Match the partition by its GPT Type UUID.
# 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 is the Discoverable Partitions Specification (DPS) UUID for the x86-64 Linux root filesystem.
Type=root-x86-64
# Instruct the daemon to expand this partition
Weight=100
Format=ext4
GrowFileSystem=yesIn this configuration, systemd-repart locates the existing root partition. Because Weight=100 is specified and there are no competing definitions, it dynamically allocates 100% of the free sectors to this partition. The GrowFileSystem=yes directive ensures that not only does the GPT boundary expand, but the underlying ext4 filesystem is dynamically resized to match.
Provisioning Secondary Partitions
The true power of systemd-repart lies in its ability to conditionally provision secondary storage volumes upon first boot, ensuring identical infrastructure across thousands of deployments.
Assume your golden image requires a dedicated, encrypted partition for container storage (e.g., /var/lib/docker). You can instruct repart to carve out exactly 50 GB of space, format it with btrfs, and encrypt it utilizing LUKS2.
Create /etc/repart.d/60-containers.conf:
[Partition]
# The generic Linux data partition UUID
Type=linux-generic
# Define the exact size boundary
SizeMinBytes=50G
SizeMaxBytes=50G
# Define the filesystem format
Format=btrfs
# Enable native LUKS encryption
Encrypt=key-file
KeyFile=/etc/cryptsetup-keys.d/container.key
# Set a persistent GPT partition label
Label=container-storageWhen the image boots on a new server, systemd-repart detects that the container-storage partition does not exist. It instantly identifies 50 GB of contiguous free space, creates the GPT entry, applies the LUKS2 encryption wrapper utilizing the specified key, and formats the inner volume with Btrfs.
Testing the Configuration
Because manipulating partition tables is inherently dangerous, systemd-repart includes a robust dry-run capability. Before deploying your image, you can execute the daemon interactively against a loopback image file or a secondary disk to visually confirm the mathematical calculations:
systemd-repart --dry-run=yes /dev/sdbThe output provides a detailed JSON or tabular representation of exactly how the disk geometry will be modified. By adopting systemd-repart, Linux engineers eliminate fragile shell scripts and achieve mathematically precise, automated disk provisioning that scales seamlessly from Raspberry Pis to enterprise cloud infrastructure.