Registering images in the Image Library

The image library holds Server Images and snapshots. When you create a new server with a particular Image, the build system retrieves the image from the Image Library. When you snapshot a server, the resulting image is recorded in the Image Library.

The actual image data is stored in Orbit, our object storage system. You can download your snapshots from Orbit using the SFTP service.

Registering a new image

Images are registered from any HTTP url. For example, to register the latest Arch Linux cloud image directly from their mirror:

$ brightbox image register --url https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2 -n "arch-latest" --arch=x86_64

id         owner      type    created_on  status    size  name                 
---------------------------------------------------------------------------------
img-8yeen  acc-xxxxx  upload  2023-01-03  creating  0     arch-latest (x86_64)
---------------------------------------------------------------------------------

When the download and registration is complete, the image goes from status creating to private:

$ brightbox image show img-8yeen
                id: img-8yeen
              type: upload
             owner: acc-xxxxx
        created_at: 2023-01-03T13:08Z
            status: private
              arch: x86_64
              name: arch-latest (x86_64)
      virtual_size: 2048
         disk_size: 512
            public: false
compatibility_mode: false
          official: false

And then it is available in the Orbit images container, named by the new images identifier (img-8yeen in this case). You can see it listed via the API now:

$ brightbox images list --status=private

id         owner      type      created_on  status   size   name
-----------------------------------------------------------------------------------------------------------------------
 img-8yeen  acc-xxxxx  upload    2023-01-03  private  2048   arch-latest (x86_64)
-----------------------------------------------------------------------------------------------------------------------

And it can be used to build servers in the usual manner:

$ brightbox server create -n "archlinux test" img-8yeen
Creating a 1gb.ssd (typ-w0hf9) server with image arch-latest (img-8yeen)

 id         status    type     zone   created_on  image_id   cloud_ip_ids  name
------------------------------------------------------------------------------------------
 srv-8gbi6  creating  1gb.ssd  gb1-a  2023-01-03  img-8yeen                archlinux test
------------------------------------------------------------------------------------------

Registration from Orbit

The registration system supports raw formatted (optionally compressed with lz4 or xv) and qcow2 formatted images, but has some limits about how long it will spend downloading and processing. So if you’re registering a larger image (more than ten gigabytes for a raw image and more than a couple of gigabytes for qcow2) we suggest downloading it yourself, converting to compressed raw, uploading to Orbit and registering it from there.

Orbit uses HTTP so it’s as simple as creating an authenticated temporary Orbit URL and using that for registration.

This is also the best option if you have a server image that you need to keep private and cannot provide via a public URL.

Compatibility mode

Brightbox Cloud Servers are created by default with what are called virtio devices. virtio devices allow for higher performance but require that the operating system have proper support for them.

If your operating system does not support virtio then it will not be able to access the network or disk devices.

Most modern Linux kernels have virtio support built-in, but many other operating systems, such as FreeBSD or Microsoft Windows, do not.

Compatibility mode disables virtio, which allows a broader range of operating systems to work without modification.

So to use compatibility mode, you set it on a particular image:

$ brightbox images update --mode=compatibility img-8yeen

From then on, any new servers created with this image are put in compatibility mode and will work without virtio drivers.

Image access

Uploaded images and snapshot images are private by default, which means only the account that owns them can list them or build servers from them.

If you make an image public, other Brightbox users can see them and build servers from them:

$ brightbox images update --public=true img-8yeen

Deprecated images

If you’ve got an image that is public and you release a new version of it, you’ll probably want to remove the old version. However, this may affect other users who might have hard-coded your image’s identifier into their build scripts. Rather than remove the old version, you can mark it as deprecated.

A deprecated image is still available for use to those who know the identifier, but it does not show up in image listings so shouldn’t invite any new users.

Deprecated images that you own still show up in your own listings, but are listed with the status deprecated.

Image Format

The registration service can handle raw format images, compressed raw images, or the qcow2 format. Raw images can be compressed with lz4 or xv.