Skip to content
Products
Platform
Developer Tools
Portal

Creating images

Last updated on

Introduction

Section titled “Introduction”

STACKIT Edge Cloud (STEC) provides you with an image for a supported platform. After you create the image, you are responsible for delivering it to your target system using a medium of your choice. This requires you to perform some preparation work to use the image in your specific setup.

The following sections describe the process for creating an image for the most common target platforms. If you need more specific information for your target system, refer to the official Talos documentation, which is linked in the references.

Concepts

Section titled “Concepts”

In the context of a bootable operating system, an image and a medium represent two distinct stages in the OS deployment process: the data format and the physical carrier that makes the data executable by hardware.

Image

Section titled “Image”

An image is a complete digital copy of the file system structure used for OS installation or booting. It contains:

  • Bootloaders (necessary to start the system)
  • OS system files
  • Additional setup tools (for installations or recovery environments)

However, an image file is not directly bootable by most hardware—it must be placed on a bootable medium first.

Medium

Section titled “Medium”

A medium is the physical or virtual storage device that actually allows a computer to boot from the image. It can be:

  • A USB flash drive or DVD into which the image has been written or “burned”
  • A virtual drive used by a hypervisor (for virtual machines)

Creating an image

Section titled “Creating an image”

You can create an image using the STACKIT Edge Cloud (STEC) UI or API.

Prerequisites

Before you begin, you need the following:

Steps

  1. In the Images section of the UI, click “Create Image”.

    STACKIT Edge Cloud web interface displaying the empty Images list. The main content area reads: "No images available. Please create your first image by clicking the 'Create Image' button." A large + Create Image button is visible above this text.

  2. Enter a name for the image, select an image version, choose an optional image overlay, and then click “Next”.

    STACKIT Edge Cloud web interface, showing the Create Image form. The form has fields for Image Name (pre-filled with foo-image), Image Version (selected as v1.10.5-stackit.v0.21.0), an Only Release Version checkbox, and Image Overlay (selected as None). A Next button is visible at the bottom right. The left navigation panel is dark gray, indicating the Images section is currently active under ASSETS.

  3. Select optional image extensions you require and click “Next”.

    STACKIT Edge Cloud web interface, showing the Create Image form on the step for configuring Image Extensions. A search bar is pre-filled with gpu. The list below shows three image extension options: siderolabs/amdgpu, siderolabs/nvidia-open-gpu-kernel-modules-lts, and siderolabs/nvidia-open-gpu-kernel-modules-production, each with a description and a radio button for selection.

  4. Enter optional kernel parameters for boot customization and click “Next”.

    STACKIT Edge Cloud web interface, showing the Create Image form on the step for configuring Kernel Parameters. A large text box is pre-filled with example parameters: talos.environment=http_proxy=http://proxy.example.com:8080 talos.environment=https_proxy=http://proxy.example.com:8080. Back and Next buttons are visible below the text box.

  5. Review your image configuration to verify that it is correct, then click “Create”.

    STACKIT Edge Cloud web interface, showing the Create Image form on the Review step. It lists the configured settings: Image Name (foo-image), Image Version (v1.10.5-stackit.v0.21.0), Image Overlay (None), Image Extensions (None), and Image Kernel Parameters (None). Back and Create buttons are available at the bottom.

  6. Your new image is created and now appears in the Images list.

    STACKIT Edge Cloud web interface, showing the Images list with one entry for foo-image. The image has a STATUS of Ready (indicated by a green circle and text) and was CREATED AT Jul 31, 2025 9:38 AM. Under the ACTION column, Download and Delete links are visible.

You can further customize your image with several optional, platform-specific settings. To learn more about these advanced options, see the advanced user guide:

You can get a list of all available image versions, overlays or extensions by querying the STACKIT Edge Cloud (STEC) image factory API. The following example shows how to retrieve a list of all available Talos images.

get available images

Terminal window
> INSTANCE_REGION="eu01"
> curl https://image-factory.edge.$INSTANCE_REGION.stackit.cloud/versions
[
 "v1.10.5-stackit.v0.20.0",
 "v1.10.5-stackit.v0.21.0",
 "..."
]

You can reuse a single image to boot multiple hosts, but be aware that all hosts will share the exact same configuration. Do not clone an existing VM or VM disk. Cloning can change the VM’s UUID, which is used to identify the node in both the STACKIT Edge Cloud control plane and the Edge Kubernetes cluster. If the UUID changes, the node loses its registered identity and can no longer connect (breaking cluster membership). Always provision new hosts by booting from an image. If you include host-specific settings—for example, a static IP address set via boot customization, every host booted from that image will use the same setting, which can cause network conflicts.

To safely reuse an image across multiple hosts, you must keep its configuration generic and avoid any host-specific modifications.

Downloading an installation image

Section titled “Downloading an installation image”

After you create the image, you need to download it in the correct format for your target platform.

Prerequisites

Before you begin, you need the following:

Steps

  1. Navigate to the Images section of the UI and click the “Download” button for your desired image.

    STACKIT Edge Cloud web interface, showing the Images list with one entry for foo-image. The image has a STATUS of Ready (indicated by a green circle and text) and was CREATED AT Jul 31, 2025 9:38 AM. Under the ACTION column, Download and Delete links are visible.

  2. For each media type, notice there are two download options:

    • UI download button: This button provides visual feedback in the UI and automatically renames the downloaded file to match the image name.
    • Direct link: This is a direct link to the STACKIT Edge Cloud (STEC) image factory. Because the image is built on demand, selecting this link will trigger a blocking HTTP call until the build is complete. This is expected behavior.

    STACKIT Edge Cloud web interface, showing the Images list. A modal window is open, presenting various image formats and architectures.

  3. For this example, select the first download button for your chosen media type. A loading indicator appears while your image is generated.

    The modal window titled "Download image" displays a progress indicator that says "Requesting image...".

  4. Once the image is generated, the download starts automatically.

    Note: Subsequent downloads of the same image will start immediately as long as the generated image is cached in the image factory. The cache is invalidated automatically when needed, and you cannot control this behavior.

    STACKIT Edge Cloud web interface, showing the Images list. A modal window titled Download foo-image is overlaid, displaying a download progress bar. The progress bar is 47% complete and shows that 158 MB of the file is currently being downloaded.

Selecting the correct image for a target

Section titled “Selecting the correct image for a target”

Select the image type and architecture that matches your target platform. Depending on your system, you may need to perform additional preparation steps to make an image bootable. For more information on these steps, see the guidance on preparing a medium.

For a full list of supported platforms and architectures, refer to the official Talos Linux documentation.

TargetTypeArchitectureBoot preparation
Bare-metal machineisoarm64/amd64 as requiredNone. Simply boot the generated iso image.
Virtual machines (excluding VMware)isoarm64/amd64 as requiredNone. Simply boot the generated iso image.
Virtual machines (VMware specific)vmwareamd64None. Simply boot the generated ova image.
Cloud machines (OpenStack)openstackamd64Review the OpenStack example.
Single board computers (Raspberry Pi)metal with overlayarm64Review the single-board computers example.

Preparing an installation medium

Section titled “Preparing an installation medium”

Depending on your target platform, you may need to prepare a bootable installation medium. This process can include steps such as:

  • Making the image bootable.
  • Writing the image to a boot device.
  • Uploading or attaching the boot device.

Because these steps are highly specific to your platform, this guide cannot cover every possibility. For detailed instructions, refer to your platform vendor’s documentation and the official Talos documentation on installation media.

The following sections provide common examples to help you get started.

Example for OpenStack

Section titled “Example for OpenStack”

For the purpose of this example we’ll use the STACKIT Compute Engine.

Prerequisites

Before you begin, you need the following:

  • A STACKIT Edge Cloud installation image (obtained by following the previous steps—openstack for amd64 in this example).
  • Tools: A generic Linux bash terminal with the STACKIT CLI and xz and (optionally) qemu-img.

Steps

  1. STACKIT Compute Engine expects certain image formats. The downloaded image is delivered as a raw disk image (img), compressed using xz. The first step is to decompress the image.

    Terminal window
    > unxz "openstack-amd64.raw.xz"
    > ls openstack-amd64.raw
    openstack-amd64.raw

  2. Convert the raw image to the qcow2 format (optional).

    Terminal window
    > qemu-img convert -f raw -O qcow2 "openstack-amd64.raw" "openstack-amd64.qcow2"
    

    ### Resize to the minimum required 32G using sparse allocation
    > qemu-img resize openstack-amd64.qcow2 32G
    

    ### Verify the image
    > qemu-img info openstack-amd64.qcow2
    > du -h openstack-amd64.qcow2

  3. Create a new STACKIT image from the downloaded image.

  4. Launch a new STACKIT VM using the image. Make sure that the disk has at least at least 32 GB in capacity (see common issues).

Example for single-board computers

Section titled “Example for single-board computers”

If you want to register a single-board computer (SBC), such as a Raspberry Pi, you need to select a matching overlay, such as the rpi_generic overlay for Raspberry Pi.

An image created with a specific overlay is not compatible with other types of SBCs. To support a different type of SBC, you must create a new image and select the correct overlay for that device.

Prerequisites

Before you begin, you need the following:

  • A STACKIT Edge Cloud installation image (obtained by following the previous steps—metal for arm64 in this example).
  • A matching overlay applied to the image.
  • A storage medium, e.g. a MicroSD Card, is attached to your computer.
  • Tools: Balena Etcher.

Steps

  1. The downloaded image is delivered as a raw disk image (img), compressed using xz. The first step is to decompress the image.

    Some tools like the Raspberry Pi Imager or Balena Etcher may do this automatically for you, so all you have to do is select the downloaded image as well as the target medium (e.g. MicroSD card). In this example we’re using Balena Etcher but the process with Raspberry Pi Imager is very similar.

    The Balena Etcher application interface for flashing an operating system image to a drive.

  2. Click “flash” to start the process of writing the downloaded image to your storage device.

    Screenshot of the Balena Etcher application during the image flashing process.

  3. Once the flashing is done you can remove your boot medium.

    Screenshot of the Balena Etcher application confirming a successful flash operation.

References

Section titled “References”