Skip to content

Eikon Image Deploy

Eikon is a storage and image deployment tool for Digital Rebar Provision (DRP) that automates deploying operating system images to bare metal in a repeatable, declarative way. The recommended approach is to use vendor-provided cloud images — the same images used in public clouds — converted for bare metal deployment.

Eikon supports two image deployment methods:

  • Raw disk images — a complete disk image written directly to the target device (dd-* types). Simpler to prepare; the partition layout is fixed in the image.
  • Rootfs archives — a filesystem archive extracted onto a custom storage configuration (tar-* types). More flexible; you define the partition layout, LVM, and RAID in the eikon/plan.

Image Considerations

Before deploying images with Eikon, review these requirements:

  • cloud-init / cloudbase-init — if using cloud-init or cloudbase-init for post-boot customization, the binaries must already be installed in the image at their default locations. If you provide a custom cloud-init/user-data on Windows, you must include the runcmd entry to start the DRP agent — see Cloud-Init Agent Startup.
  • Post-install tasks — if not using cloud-init, create custom DRP tasks to handle any OS configuration that would normally be done at first boot.
  • Drivers and early-boot packages — include all hardware drivers and storage controller modules in the image before capture. They cannot be reliably added during deployment.
  • Windows — the C:\curtin\ directory must be created with appropriate permissions in the image before capture. Eikon runs inside Sledgehammer (Linux) and cannot manage Windows filesystem permissions.
  • Debian/Ubuntu grub packages — install grub-efi-amd64 (UEFI) or grub-pc (legacy BIOS) and cache them before image capture. This is especially important for airgap deployments. Also remove /usr/lib/grub/grub-multi-install from the image — it causes problems during bootloader installation.
  • Image cleanup — Eikon does not clean up images. Either clean up the OS before capture or create custom post-deploy tasks.

Cloud-Init Agent Startup

Eikon injects the DRP agent configuration into the deployed image during deployment so the agent can connect back to DRP after first boot.

Linux Agent Startup

For Linux deployments, Eikon installs the DRP agent as a systemd service inside the deployed image during the deployment phase (via eikon-chroot-agent-install). The agent starts automatically on first boot via systemd — no runcmd entry in cloud-init/user-data is required.

Windows Agent Startup

For Windows deployments, Eikon writes /eikon-win-agent.ps1 to the deployed image. This script configures and starts the DRP agent on first boot. When cloud-init/user-data is not set, Eikon generates the following default cloudbase-init user-data to trigger the script:

YAML
#cloud-config
runcmd:
  - 'powershell -noexit -file /eikon-win-agent.ps1'

If you provide a custom cloud-init/user-data, you must include this runcmd entry. Without it, the DRP agent will not start after deployment and the machine will not reconnect to DRP.

Example of a custom cloud-init/user-data that preserves agent startup:

YAML
cloud-init/user-data: |
  #cloud-config
  runcmd:
    - 'powershell -noexit -file /eikon-win-agent.ps1'
    - 'your-custom-command-here'

Cloud Image Deployment

Vendor cloud images (AlmaLinux, Rocky Linux, Ubuntu, Debian) are the recommended image source. They are maintained by the distribution vendors, regularly updated, and already configured for cloud-init.

The general workflow is:

  1. Download the vendor cloud image (QCOW2 or raw)
  2. Convert or extract to a format Eikon supports
  3. Compress with zstd
  4. Upload to DRP file storage
  5. Reference the image in an eikon/plan profile

Required Tools

Bash
# RHEL/AlmaLinux/Rocky
dnf install qemu-img zstd libguestfs-tools

# Debian/Ubuntu
apt install qemu-utils zstd libguestfs-tools

Cloud Image Sources

Distribution Cloud Image URL
AlmaLinux 10 https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/AlmaLinux-10-GenericCloud-latest.x86_64.qcow2
Rocky Linux 9 https://dl.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2
Ubuntu 24.04 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
Debian 12 https://cdimage.debian.org/images/cloud/bookworm/latest/debian-12-nocloud-amd64.tar.xz

Preparing Raw Images

Raw images write the entire disk directly to the target device. The partition layout is whatever was in the cloud image — no additional storage configuration is needed.

AlmaLinux 10:

Bash
curl -Lo alma10.qcow2 https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/AlmaLinux-10-GenericCloud-latest.x86_64.qcow2
qemu-img convert -O raw alma10.qcow2 alma10.raw
zstd alma10.raw -o alma10.raw.zst
drpcli files upload alma10.raw.zst as images/eikon/alma10.raw.zst

Rocky Linux 9:

Bash
curl -Lo rocky9.qcow2 https://dl.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2
qemu-img convert -O raw rocky9.qcow2 rocky9.raw
zstd rocky9.raw -o rocky9.raw.zst
drpcli files upload rocky9.raw.zst as images/eikon/rocky9.raw.zst

Ubuntu 24.04 (Ubuntu cloud images use a .img extension but are QCOW2 format):

Bash
curl -Lo ubuntu24.img https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
qemu-img convert -O raw ubuntu24.img ubuntu24.raw
zstd ubuntu24.raw -o ubuntu24.raw.zst
drpcli files upload ubuntu24.raw.zst as images/eikon/ubuntu24.raw.zst

Debian 12 (Debian distributes cloud images as a .tar.xz containing a raw disk):

Bash
curl -Lo debian12.tar.xz https://cdimage.debian.org/images/cloud/bookworm/latest/debian-12-nocloud-amd64.tar.xz
tar xf debian12.tar.xz
zstd disk.raw -o debian12.raw.zst
drpcli files upload debian12.raw.zst as images/eikon/debian12.raw.zst

Once uploaded, the raw image plan is minimal — just reference the disk and image:

YAML
eikon/plan:
  disks:
    - name: d0
      path: /dev/sda
      grub_device: true
      image:
        type: dd-zst
        url: "{{ .ProvisionerURL }}/files/images/eikon/alma10.raw.zst"

See the example-eikon-*-cloud-raw profiles in the eikon content pack for ready-to-use examples for each distribution.

Preparing Rootfs Images

Rootfs images let you define a custom storage layout (partition sizes, LVM, RAID) independent of what the vendor image uses. Use virt-tar-out from libguestfs-tools to extract the filesystem from a cloud image.

AlmaLinux 10:

Bash
curl -Lo alma10.qcow2 https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/AlmaLinux-10-GenericCloud-latest.x86_64.qcow2
virt-tar-out -a alma10.qcow2 / - | zstd -o alma10.tar.zst
drpcli files upload alma10.tar.zst as images/eikon/alma10.tar.zst

Rocky Linux 9:

Bash
curl -Lo rocky9.qcow2 https://dl.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2
virt-tar-out -a rocky9.qcow2 / - | zstd -o rocky9.tar.zst
drpcli files upload rocky9.tar.zst as images/eikon/rocky9.tar.zst

Ubuntu 24.04:

Bash
curl -Lo ubuntu24.img https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-tar-out -a ubuntu24.img / - | zstd -o ubuntu24.tar.zst
drpcli files upload ubuntu24.tar.zst as images/eikon/ubuntu24.tar.zst

Debian 12:

Bash
curl -Lo debian12.tar.xz https://cdimage.debian.org/images/cloud/bookworm/latest/debian-12-nocloud-amd64.tar.xz
tar xf debian12.tar.xz
virt-tar-out -a disk.raw / - | zstd -o debian12.tar.zst
drpcli files upload debian12.tar.zst as images/eikon/debian12.tar.zst

A rootfs plan defines the full storage layout. The image is extracted into the configured filesystems:

YAML
eikon/plan:
  disks:
    - name: disk1
      path: /dev/sda
      ptable: gpt
      grub_device: true
      partitions:
        - name: part1
          id: 1
          ptype: fat32
          size: 1G
          fs:
            name: fs1
            fstype: vfat
            mount: /boot/efi
        - name: part2
          id: 2
          ptype: ext4
          size: 1G
          fs:
            name: fs2
            fstype: ext4
            mount: /boot
        - name: part3
          id: 3
          ptype: ext4
          size: REST
          fs:
            name: fs3
            fstype: ext4
            mount: /
  images:
    - url: "{{ .ProvisionerURL }}/files/images/eikon/alma10.tar.zst"
      type: tar-zst

See the example-eikon-*-cloud-rootfs profiles in the eikon content pack for ready-to-use examples with more complex layouts (LVM, software RAID).

Windows Raw Images

Windows images must be raw disk images and are typically captured from a prepared VM rather than downloaded as cloud images. The plan format is simplified using the eikon/image-url and eikon/image-type params directly rather than a full eikon/plan:

YAML
Params:
  eikon/image-url: "{{ .ProvisionerURL }}/files/images/eikon/win2019.raw.zst"
  eikon/image-type: dd-zst
  eikon/install-dev: /dev/sda

See Creating Raw Images for instructions on capturing a Windows image.

Getting Started

This walkthrough deploys a cloud image using the pre-built example profiles included in the eikon content pack.

Prerequisites

  • DRP server v4.14 or later with the eikon and universal content packs installed
  • Target machine registered and discovered in DRP
  • Image uploaded to DRP file storage (see Cloud Image Deployment)

Raw Image Deployment Example

  1. Upload the AlmaLinux 10 raw image (see Preparing Raw Images)
  2. Navigate to the target machine in the DRP UX
  3. Go to the Editor tab
  4. Under Collections → Profiles, add the profile example-eikon-alma10-cloud-raw
  5. Under Workflow Management → Pipeline, select eikon-image-deploy
  6. Under Workflow Management → Workflow, select universal-image-deploy

The deployment will:

  • Boot into Sledgehammer
  • Write the raw disk image directly to /dev/sda
  • Configure the bootloader
  • Reboot into the deployed system

Rootfs Deployment Example

  1. Upload the Ubuntu 24.04 rootfs image (see Preparing Rootfs Images)
  2. Navigate to the target machine in the DRP UX
  3. Go to the Editor tab
  4. Under Collections → Profiles, add the profile example-eikon-ubuntu24-cloud-rootfs
  5. Under Workflow Management → Pipeline, select eikon-image-deploy
  6. Under Workflow Management → Workflow, select universal-image-deploy

The deployment will:

  • Boot into Sledgehammer
  • Create the partition layout defined in the profile
  • Extract the rootfs archive into the configured filesystems
  • Install and configure the bootloader
  • Rebuild initramfs and update /etc/fstab
  • Reboot into the deployed system

Common Issues

Image not found — verify the image path. The URL in the profile must match the path used during drpcli files upload. Check <drp-host>:8091/files/images/eikon/ to confirm the file is present.

Boot failure (UEFI/Legacy mismatch) — Eikon currently supports UEFI boot only. Ensure the target machine is configured for UEFI and that Secure Boot is disabled.

Machine does not come online — the deployed OS may not have network configured. Log in via console, enable networking, and restart the DRP agent:

Bash
systemctl restart drp-agent

Boot hangs after rootfs deployment — cloud images that include a bootcmd with a resume= argument (for hibernate/swap resume) may hang at boot because Eikon does not currently have a way to specify the resume device. Remove the resume= argument from the bootloader configuration or cloud-init bootcmd in the image before capture.

Understanding eikon/plan

The eikon/plan parameter defines the full storage and image deployment configuration. It is used for rootfs deployments and for raw deployments where you need to specify a target device explicitly.

Raw Image Plan

The minimal form — write a complete disk image directly to a device:

YAML
eikon/plan:
  disks:
    - name: disk-0
      grub_device: true
      path: /dev/sda              # or by-id: /dev/disk/by-id/wwn-0x5002...
      image:
        type: dd-zst              # dd-raw, dd-gz, dd-bz2, dd-xz, dd-zst
        url: "https://..."
        checksum: <sha256>        # optional but recommended

Rootfs Plan

Define the full storage layout — partitions, LVM volumes, RAID arrays — then apply the image:

YAML
eikon/plan:
  disks:                    # physical disks and partitions
  vgs:                      # LVM volume groups and logical volumes
  swraids:                  # software RAID arrays (mdadm)
  images:                   # OS images to extract

Use size: REST on a partition to consume all remaining space. Use ptype: LVM2_member to assign a partition to an LVM volume group.

LVM Example

YAML
eikon/plan:
  disks:
    - name: disk1
      path: /dev/sda
      ptable: gpt
      grub_device: true
      partitions:
        - name: part1
          id: 1
          ptype: vfat
          size: 1G
          fs:
            name: fs1
            fstype: vfat
            mount: /boot/efi
        - name: part2
          id: 2
          ptype: xfs
          size: 1G
          fs:
            name: fs2
            fstype: xfs
            mount: /boot
        - name: part3
          id: 3
          size: 17G
          ptype: LVM2_member
  vgs:
    - name: vg1
      pvs:
        - part3
      lvs:
        - name: lv1
          size: 14G
          fs:
            name: fs3
            fstype: xfs
            mount: /
        - name: lv2
          size: 1G
          fs:
            name: fs5
            fstype: swap
  images:
    - url: "{{ .ProvisionerURL }}/files/images/eikon/alma10.tar.zst"
      type: tar-zst
      checksum: <sha256>

Airgap Bundle Support

Images can be included in an offline deployment bundle using the --include-file flag:

Bash
drpcli airgap build \
  --platform=amd64/linux \
  --catalog=https://repo.rackn.io \
  --versions=v4.15.0 \
  --include-file=https://your-image-server/alma10.raw.zst::files/images/eikon

The --include-file flag takes <source-url>::<destination-path> — the destination path is relative to the DRP file store. If the filename is omitted from the destination, it is treated as a directory.

See Airgap Install for full airgap bundle documentation.

Authenticated Image Access

Basic Auth

Add credentials directly to the image URL:

Text Only
https://user:pass@my-image-server/image.tar.zst

To avoid storing credentials in plain text in the profile, use ParamExpand to inject them at render time:

YAML
images:
  - url: '{{ if .ParamExists "secure-basic-auth" }}https://{{ .ParamExpand "secure-basic-auth-param" }}@{{ regexReplaceAll "^https?://" .ProvisionerURL "" }}{{ else }}{{ .ProvisionerURL }}{{ end }}/files/images/eikon/alma10.tar.zst'
    type: tar-zst
secure-basic-auth-param: 'user:pass'

mTLS

Provide a client certificate, key, and optional CA cert as base64-encoded values:

Bash
eikon/tls-client-cert   # base64-encoded client certificate
eikon/tls-client-key    # base64-encoded client private key
eikon/tls-ca-cert       # base64-encoded CA certificate (to validate the server)

Creating Custom Images

Use this approach when you need to build images from scratch, incorporate proprietary software, or capture a system that has been configured manually. Cloud images are preferred when available.

Creating Rootfs Archives

Install your OS on a physical machine or VM, then capture the filesystem:

  1. Boot into the installed system
  2. Install compression tools:
    Bash
    # RHEL/AlmaLinux/Rocky
dnf install zstd

# Debian/Ubuntu
apt install zstd
  3. Create the tar archive from the root filesystem:
    Bash
    cd /
tar --exclude={proc,sys,tmp,dev,run,var/tmp}/* \
    --exclude={*.tar,root/post-install.log} \
    --numeric-owner \
    --acls \
    --selinux \
    --xattrs \
    --xattrs-include=* \
    -cvf my-rootfs.tar .
  4. Compress:
    Bash
    zstd my-rootfs.tar

Note

The following tar flags are used to preserve filesystem metadata:

  • --numeric-owner — preserves UIDs/GIDs
  • --acls — preserves Access Control Lists
  • --selinux — preserves SELinux contexts
  • --xattrs --xattrs-include=* — preserves extended attributes

Creating Raw Images

Direct disk capture — boot from external media and image the disk while it is not mounted:

Bash
dd if=/dev/sda | zstd -o my-image.raw.zst

Convert from a VM disk image:

Bash
# From QCOW2
qemu-img convert -f qcow2 -O raw disk.qcow2 system.raw

# From VMDK (VMware)
qemu-img convert -f vmdk -O raw "Virtual Disk.vmdk" system.raw

# From VDI (VirtualBox)
qemu-img convert -f vdi -O raw disk.vdi system.raw

# Compress the result
zstd system.raw -o system.raw.zst

Note

Building the OS in a VM first is the recommended approach for custom raw images. It avoids hardware-specific issues during capture and allows clean shutdown before imaging.

Windows raw images are built the same way — install Windows in a VM, configure as needed (including creating C:\curtin\ with appropriate permissions and installing cloudbase-init if required), shut down cleanly, then convert the VM disk:

Bash
qemu-img convert -f vmdk -O raw "Windows Server 2019.vmdk" win2019.raw
zstd win2019.raw -o win2019.raw.zst
drpcli files upload win2019.raw.zst as images/eikon/win2019.raw.zst

Additional Assistance

For support, open a Zendesk ticket with the following information:

  • Set rs-debug-enable: true on the machine to enable debug logging
  • Rerun the pipeline to capture detailed logs
  • Run drpcli support machine-bundle $UUID to collect a machine support bundle
  • Capture console output for any error messages visible during deployment