Skip to content

Machine Provisioning

Overview

Provisioning is the process of installing an operating system onto a machine. Durantic provisions machines by streaming an OCI (Docker) image directly to disk, then applying a cloud-init configuration generated from the machine's assigned roles.

The entire process is automated. Once you trigger provisioning, the agent handles image download, disk partitioning, filesystem extraction, configuration injection, and reboot — no manual intervention required.

Bootstrap Methods

Before you can provision a machine, it needs to connect to the control plane. There are three ways to bootstrap a machine.

The fastest way to bring a machine under management. Run a single command on the target machine:

curl -sfL https://api.durantic.io/install.sh | DURANTIC_TOKEN=<your-token> bash -

The token is a JWE-encrypted, stateless credential generated from the dashboard. No server-side state is stored for the token itself.

Bootstrap via CLI

ISO Image

For machines where you have physical or virtual console access:

  1. Download the Durantic ISO from the dashboard.
  2. Boot the machine from the ISO.
  3. The machine displays a 6-character approval code on screen.
  4. Enter the approval code in the dashboard to approve the machine.

This method works well when you cannot run arbitrary commands on the machine before provisioning.

Bootstrap via ISO

PXE / Network Boot

For fleet deployments where you manage a PXE infrastructure:

  1. Download the vmlinuz file from the dashboard (custom kernel.org 6.18 LTS with embedded initramfs).
  2. Configure your PXE server to serve this file.
  3. Pass the bootstrap token as a kernel parameter.

This method is reusable — configure it once and boot as many machines as you need. The same token works for all machines until it expires.

Bootstrap via PXE

Bootstrap Token

Bootstrap tokens control how machines authenticate with the control plane during initial registration.

Setting Options
Default lifetime 10 minutes
Extended lifetimes 1 day, 7 days, 30 days, 90 days, 365 days
Reusability Reusable until expiration

A single token can bootstrap multiple machines. This is especially useful with the PXE method for fleet deployments where many machines boot with the same token.

The Provisioning Process

When you trigger provisioning, the agent executes the following steps in order:

Step Description
Image Inspection The agent connects to the OCI registry, verifies the image manifest, and determines the layers to download.
Bootloader Streaming Layer 0 of the OCI image — a compressed raw disk containing bootloaders — is streamed directly to the target disk.
Partition Resize The agent resizes the root partition to fill the available disk space.
Layer Extraction Remaining OCI layers (layer 1 and above) are extracted onto the root filesystem. This is typically the longest step, as it contains the full operating system.
Cloud-Init Configuration The merged cloud-init configuration from all assigned roles is written to disk so it executes on first boot.
Agent Injection The Durantic agent binary and its configuration are installed into the new filesystem so the machine reconnects to the control plane after reboot.
Sync and Reboot Disk buffers are flushed and the machine reboots into the newly installed operating system.

Monitoring Progress

The Provisions tab on a machine's detail page shows real-time provisioning progress.

Provisions tab

Each provisioning run displays:

  • Status — The current state (queued, in progress, completed, or failed).
  • Percentage — Overall progress as a percentage.
  • Current Step — Which step of the provisioning process is currently executing.
  • Timestamps — When provisioning started and, once finished, when it completed.

OCI Images

Durantic uses standard Docker/OCI images as operating system packages. This means you can build, tag, push, and pull OS images using familiar container tooling.

An OCI image used for provisioning has a specific layer structure:

Layer Contents
Layer 0 Compressed raw disk image containing bootloaders and partition table
Layer 1+ Full operating system filesystem (packages, configuration, kernel)

Images can be hosted in any OCI-compatible registry — Docker Hub, GitHub Container Registry, Google Artifact Registry, or a self-hosted registry.

Image Management

Images are managed as first-class entities in Durantic. Each Image stores:

  • Name — A human-readable identifier, unique per account.
  • OCI Image URL — The registry path (e.g., ghcr.io/durantic/ubuntu:24.04).
  • Registry Auth — Optional credentials for private registries.

There are two types of images:

Type Description
Official Durantic-provided images visible to all accounts. Cannot be modified or deleted.
Account-scoped Custom images created by your team, visible only within your account.

Image Resolution

When provisioning, Durantic resolves the OCI image through a priority chain:

  1. Role image — If the machine has a role with an assigned image, that image is used.
  2. Account default image — If no role specifies an image, the account's default image is used.

Only one role per machine may specify an image. Configure images and the account default under Organization settings in the dashboard.

Re-Provisioning

You can re-provision a machine at any time to reinstall or change its operating system:

  1. Navigate to the machine's detail page.
  2. Open the Provisions tab.
  3. Click Provision.
  4. Confirm the action.

The machine reboots into the installer environment and the provisioning process begins again. Any data on the machine's disk will be overwritten.

Kexec Acceleration

When re-provisioning, the agent uses kexec to skip the BIOS/UEFI POST and GRUB boot stages. Instead of a full reboot cycle (which can take minutes on server hardware), the agent loads the installer kernel directly from the running system. This significantly reduces the time between triggering provisioning and the installer starting.

Kexec is disabled by default for maximum hardware compatibility. You can enable it per machine via the API (PATCH /api/provisioning/machines/{uuid} with "kexec_installer": true) for faster provisioning on hardware without GPU compatibility issues. Keep kexec disabled for NVIDIA GPU machines where loaded drivers interfere with the kexec process.

Installer Experience

The Durantic installer boots a custom Linux kernel with the installer environment embedded directly inside it. This means:

  • No separate initrd download — everything needed is in a single file
  • Broad hardware support — AWS ENA, GCP gVNIC, Azure Hyper-V, VMware, NVMe, and more are all built-in
  • TUI-first flow — the installer shows a text-based UI immediately upon boot, displaying network discovery, DHCP progress, and bootstrap status in real time

For machines without a display (headless servers, cloud VMs with serial console only), the installer automatically detects headless mode and routes all output to the serial console.

Boot into Installed System

The agent also uses kexec after installation completes, booting directly into the newly installed system without a full reboot. Additionally, the control plane can send a BootInstalledSystem event to kexec from a maintenance environment back into the installed system — useful for firmware updates or diagnostics without re-provisioning.