Introduction

Quickly upload any raw disk images into your Hetzner Cloud projects!

About

The Hetzner Cloud API does not support uploading disk images directly and only provides a limited set of default images. The only option for custom disk images is to take a snapshot of an existing server’s root disk. These snapshots can then be used to create new servers.

To create a completely custom disk image, users need to follow these steps:

Create a server with the correct server type
Enable the rescue system for the server
Boot the server
Download the disk image from within the rescue system
Write the disk image to the server’s root disk
Shut down the server
Take a snapshot of the server’s root disk
Delete the server

This is a frustratingly long process. Many users have automated it with Packer and packer-plugin-hcloud, but Packer introduces additional complexity that can be difficult to manage.

This repository provides a simple CLI tool and Go library to streamline the process.

Getting Started

CLI

Binary

We provide pre-built deb, rpm and apk packages. Alternatively we also provide the binaries directly.

Check out the GitHub release artifacts for all of these files and archives.

Arch Linux

You can get hcloud-upload-image-bin from the AUR.

Use your preferred wrapper to install:

yay -S hcloud-upload-image-bin

`go install`

If you already have a recent Go toolchain installed, you can build & install the binary from source:

go install github.com/apricote/hcloud-upload-image@latest

Docker

There is a docker image published at ghcr.io/apricote/hcloud-upload-image.

docker run --rm -e HCLOUD_TOKEN="<your token>" ghcr.io/apricote/hcloud-upload-image:latest <command>

Usage

export HCLOUD_TOKEN="<your token>"
hcloud-upload-image upload \
  --image-url "https://example.com/disk-image-x86.raw.bz2" \
  --architecture x86 \
  --compression bz2

To learn more, you can use the embedded help output or check out the CLI help pages in this repository.:

hcloud-upload-image --help
hcloud-upload-image upload --help
hcloud-upload-image cleanup --help

Go Library

The functionality to upload images is also exposed in the library hcloudimages! Check out the reference documentation for more details.

Install

go get github.com/apricote/hcloud-upload-image/hcloudimages

Usages

package main

import (
	"context"
	"fmt"
	"net/url"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"

	"github.com/apricote/hcloud-upload-image/hcloudimages"
)

func main() {
	client := hcloudimages.NewClient(
		hcloud.NewClient(hcloud.WithToken("<your token>")),
	)

	imageURL, err := url.Parse("https://example.com/disk-image-x86.raw.bz2")
	if err != nil {
		panic(err)
	}

	image, err := client.Upload(context.TODO(), hcloudimages.UploadOptions{
		ImageURL:         imageURL,
		ImageCompression: hcloudimages.CompressionBZ2,
		Architecture:     hcloud.ArchitectureX86,
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Uploaded Image: %d", image.ID)
}

hcloud-upload-image