How to Run CentOS Atomic Host on VirtualBox

In an increasingly containerized IT environment, tools and platforms that allow ease of container management and deployment are increasingly becoming popular. CentOS Atomic Host is a micro-OS that provides a platform whose purpose is to easily deploy and scale containers. It is created by Project Atomic, which is a Red Hat-sponsored organization. Comparable to CoreOS, it provides a software stack consisting of the Linux kernel and GNU tools, Docker, and Kubernetes. This tutorial will show how to test it out on VirtualBox on your Linux-based desktop system.

Obtain the CentOS Atomic Host

Navigate to the official Atomic Host download page.

Download Atomic Host

Download the CentOS-based image.

Convert Image to VirtualBox format

Since the image is in qcow2 format, we will use qemu-img to convert the file to a vdi image that VirtualBox can work with. In Ubuntu, qemu-img is provided by the qemu-utils package.

qemu-img convert -f qcow2 -O vdi filename-of-downloaded-imge.qcow2 converted-image-filename.vdi

Create a Metadata ISO

The Atomic Host image is designed to be run on a cloud infrastructure, so it relies on metadata from a metadata server to initialize the Operating System through cloud-init. This means that the hostname, user password, and other system components cannot be initialized by Virtualbox. This also means that we cannot log in or use the VM. Luckily, the Atomic Host image creators have configured the image to be able to pull metadata from an optical disk. We can use Virtualbox to serve metadata through an ISO file that is presented as a virtual optical drive to the Atomic Host VM.

In your working directory, create a file named meta-data, and insert the following contents:

instance-id: atomic-host001

Now, create a file named user-data:

password: atomic
ssh_pwauth: True
chpasswd: { expire: False }

- Insert your ssh public key here

Note that the line with the '#' at the start is not a comment; it is required as part of the syntax used by cloud-init.

With the necessary information in place in the files, create an ISO image that contains the two files:

genisoimage -output init.iso -volid cidata -joliet -rock user-data meta-data

Create Atomic Host Virtual Machine

With a ready VM image file and the required metadata ISO, you are now ready to create the Virtual Machine.
Run Virtualbox, and create a new Virtual Machine. For the Hard disk section, Choose "Use an existing virtual hard disk file", and click on the folder icon on the right to point to the Atomic Host image.

Virtualbox VM Creation Window

When the Virtual Machine has been created, right-click on it in the Virtual Machines list, and click on "Settings". Click on "Storage".

Virtual Machine Settings Window - Initial

You should see the "Empty" virtual disk drive. Click on it, then click on the optical disk icon towards the top right of the screen. Click on "Choose Virtual Optical Disk File" from the drop-down list. Navigate to and select your the metadata ISO that was created earlier.

Virtual Machine Settings Window

You are now ready to start your Atomic Host VM. Start it up. It will boot from the image file, and will automatically load the metadata from the virtual optical drive.

The CentOS Atomic Host Login Console

Note that in the image above, the system's hostname has already been changed to the local-hostname value that was set in the metadata ISO files. The default username is "centos". Use the password you gave in the metadata file.


We now have an Atomic Host that we can use for testing. After logging in through the console, you may want to find out its IP address with "ifconfig" to be able to work through SSH. As a starting point, the standard Docker commands suite, such as "docker", and the Kubernetes commands such as "kubectl" are available right off the gate. Enjoy!

Leave a Comment