KEI/VyOS_CloudInit/imageBuild.md

Image was built using Debian 12, kernel 6.1.0-50-cloud-amd64, Docker version 29.6.1, build 8900f1d

Built date is 12/07/2026

Install docker

To install Docker, follow the installation tutorial available on the official Docker website

Prepare the VyOS builder container

First download the prerequisites and clone the repository

sudo apt update
sudo apt install git

git clone --branch rolling --single-branch \
    https://github.com/vyos/vyos-build.git

cd vyos-build

Then pull the docker image

sudo docker pull vyos/vyos-build:rolling

And then inside container edit the data/build-flavors/proxmox-cloud.toml file to include

image_format = "qcow2"

packages = [
    "cloud-init",
    "cloud-utils",
    "ifupdown",
    "qemu-guest-agent"
]

[boot_settings]
console_type = "ttyS"
console_num = "0"
console_speed = "115200"

Then add the Cloud-Init configuration

# Create the configuration directory
mkdir -p \
    data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d
    
# Select Proxmox-compatible data sources
cat > \
data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d/99-datasource.cfg \
<<'EOF'
datasource_list: [ NoCloud, ConfigDrive ]
EOF

#Disable generic Linux network configuration
cat > \
data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d/99-disable-network-config.cfg \
<<'EOF'
network:
  config: disabled
EOF

This prevents generic Cloud-Init from creating /etc/network/interfaces configuration that would conflict with VyOS configuration.

After that, add a live-build chroot hook

cat > \
data/live-build-config/hooks/live/19-cloud-init-qemu.chroot \
<<'EOF'
#!/bin/sh

set -e

echo "I: Configuring Cloud-Init"

systemctl enable cloud-init.service

rm -f /etc/network/interfaces.d/50-cloud-init

echo "I: Configuring QEMU Guest Agent"

systemctl enable qemu-guest-agent.service

exit 0
EOF

chmod +x \
    data/live-build-config/hooks/live/19-cloud-init-qemu.chroot

Thereafter, start the docker build container

sudo docker run --rm -it \
    --privileged \
    --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
    -v "$PWD":/vyos \
    -w /vyos \
    vyos/vyos-build:rolling \
    bash

Then we come to building the qcow disk image. In this example flag --disk-size 10 means that we are creating a 10 GB virtual disk.

sudo make clean

sudo ./build-vyos-image \
    --architecture amd64 \
    --build-by "yuru@shupogaki.org" \
    --disk-size 10 \
    proxmox-cloud

After the build completes, run the following command

find build -maxdepth 1 -type f \
    \( -name '*.qcow2' -o -name 'manifest.json' \) \
    -ls

to verify that it resembles the following text

build/vyos-1.x-rolling-YYYYMMDDHHMM-proxmox-cloud-amd64.qcow2

Errors

Missing --allow-downgrades flag

If you get the following error when building the qcow2 virtual disk

E: Packages were downgraded and -y was used without --allow-downgrades.
E: An unexpected failure occurred, exiting...

Re-clone the repository and follow the commands and text below

Then it means that during bootstrap, Debian installed its current openssl and libssl3 packages. After the VyOS rolling repository was enabled, APT selected VyOS-provided versions that it classified as downgrades.

To fix it, run the following command from the root of the cloned vyos-build repository and check the current line

grep -n -- '--apt-options' scripts/image-build/build-vyos-image

You shold see a result that looks simmilar to this

vyos_bld@93f129e939ac:/vyos$ grep -n -- '--apt-options' scripts/image-build/build-vyos-image
655:                --apt-options "--yes" \

This means in file scripts/image-build/build-vyos-image on line 655 a --yes --allow-downgrades flag is missing. You can add it manually, or run the following command

sed -i \
  's/--apt-options "--yes"/--apt-options "--yes --allow-downgrades"/' \
  scripts/image-build/build-vyos-image

After that, apply the fix for the second error and start from the begining

Missmatched shim package version

If you get the following error

The following packages have unmet dependencies:
 shim-helpers-amd64-signed : Depends: shim-unsigned (>= 16.1-2~deb12u1) but 16.0-1+vyos1 is to be installed
E: Unable to correct problems, you have held broken packages.
E: An unexpected failure occurred, exiting...
P: Begin unmounting filesystems...
P: Saving caches...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Traceback (most recent call last):
  File "/vyos/./build-vyos-image", line 810, in <module>
    build()
  File "/vyos/./build-vyos-image", line 721, in build
    cmd("lb build 2>&1")
  File "/vyos/scripts/image-build/utils.py", line 89, in cmd
    raise OSError(f"Command '{command}' failed")
OSError: Command 'lb build 2>&1' failed

First, re-clone the respository and run the following command

cat > \
data/live-build-config/archives/debian-shim.pref.chroot \
<<'EOF'
Package: shim-unsigned shim-signed shim-signed-common shim-helpers-amd64-signed
Pin: release o=Debian
Pin-Priority: 1001
EOF

Then also apply the fix for the --allow-downgrades problem, and after that start from the beggining