Skip to content
Products
Platform
Developer Tools
Portal

Creating images

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. Verify the currently available images of your STEC instance

    Terminal window
    > kubectl api-resources --api-group=edge.stackit.cloud
    NAME SHORTNAMES APIVERSION NAMESPACED KIND
    bootstrapkubeconfigs edge.stackit.cloud/v1alpha1 true BootstrapKubeconfig
    edgeclusters edge.stackit.cloud/v1alpha1 true EdgeCluster
    edgehosts edge.stackit.cloud/v1alpha1 true EdgeHost
    edgeimages edge.stackit.cloud/v1alpha1 true EdgeImage
    edgeimageschematics edge.stackit.cloud/v1alpha1 true EdgeImageSchematic
    edgemachines edge.stackit.cloud/v1alpha1 true EdgeMachine
    upgradeplans edge.stackit.cloud/v1alpha1 true UpgradePlan
    

    > kubectl get edgeimages.edge.stackit.cloud
    > kubectl explain EdgeImage.spec --recursive

  2. Create a EdgeImage manifest file. The schematic is defined by the chosen talosVersion.

    Terminal window
    cat << EOL > foo.yaml
    apiVersion: edge.stackit.cloud/v1alpha1
    kind: EdgeImage
    metadata:
    name: foo-image
    namespace: default
    spec:
    schematic: |
    customization:
    extraKernelArgs: []
    systemExtensions:
    officialExtensions: []
    overlay: {}
    talosVersion: vx.y.z-stackit.vX.Y.Z
    EOL

  3. Apply the created manifest to create a new image. The schematicId points to the specified configuration. When you upgrade a host created from this image, STEC uses the schematicId to build an updated image with the exact same configuration, including any selected extensions.

    Terminal window
    > kubectl apply -f foo.yaml
    

    > kubectl get EdgeImage
    NAME AGE
    foo-image 1m
    

    > kubectl describe EdgeImage/foo-image
    Name: foo-image
    Namespace: default
    API Version: edge.stackit.cloud/v1alpha1
    Kind: EdgeImage
    [...]
    Spec:
    Schematic:
        customization:
            extraKernelArgs: []
            systemExtensions:
            officialExtensions: []
        overlay: {}
    Talos Version: v1.10.5-stackit.v0.21.0
    Status:
        Artifacts:
            Artifacts:
                Architecture: amd64
            URL: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-amd64.iso
            Architecture: arm64
            URL: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-arm64.iso
            Type: iso
            [...]
        Ready: true
        Schematic Id:      9deb[...]4599

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. 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. Inspect the status of the image you created to find the image URLs.

    Terminal window
    > kubectl get EdgeImage/foo-image -o yaml | yq '.status'
    artifacts:
    - artifacts:
    - architecture: amd64
    url: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-amd64.iso
    - architecture: arm64
    url: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-arm64.iso
    type: iso
    - artifacts:
    - architecture: amd64
    url: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-amd64.raw.xz
    - architecture: arm64
    url: https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-arm64.raw.xz
    type: metal
    - [...]
    ready: true
    schematicId: 9deb[...]4599

  2. Select the URL for the image that matches your target platform.

    Terminal window
    > kubectl get EdgeImage/foo-image -o yaml | yq '.status.artifacts[] | select(.type=="iso").artifacts[] | select(.architecture=="amd64").url'
    https://image-factory.dev.edge.eu01.stackit.cloud/image/9deb[...]4599/v1.10.5-stackit.v0.21.0/metal-amd64.iso

  3. Download the image.

    Terminal window
    > curl $(kubectl get EdgeImage/foo-image -o yaml | yq '.status.artifacts[] | select(.type=="iso").artifacts[] | select(.architecture=="amd64").url') --output foo.amd64.iso
    % Total % Received % Xferd Average Speed Time Time Time Current
    Dload Upload Total Spent Left Speed
    100 531M 100 531M 0 0 5224k 0 0:01:44 0:01:44 --:--:-- 5333k
    

    > ls foo.amd64.iso
    foo.amd64.iso

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 documention 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 balenaEtcher application interface for flashing an operating system image to a drive. It shows three steps in a linear flow: an image file named metal-arm64.raw is selected, a target device named Lexar uSD...RDR Media (64 GB) is selected, and a prominent blue Flash! button is ready to be clicked to start the process. The image file size is indicated as 1.31 GB.

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

    Screenshot of the balenaEtcher application during the image flashing process. The left panel shows the progress of the operation. It lists the source image file as metal-arm64.raw (1.31 GB) and the target as Lexar u...R Media. A progress bar indicates Decompressing... 68%, with a current speed of 419.50 MB/s and an Estimated Time of Arrival (ETA) of 0m0s. The right panel is divided into 'Task' and 'Solution', showing the current task as Flash device with a spinning indicator, and the solution being balenaEtcher.

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

    Screenshot of the balenaEtcher application confirming a successful flash operation. The left panel displays a large "Flash Completed!" message. Below this, it indicates 1 Successful target with an effective speed of 38.1 MB/s. A green checkmark appears next to the image file name metal-arm64.raw. A large blue button labeled Flash another is visible at the bottom. The right panel shows the 'Task' as Flash device with a green checkmark next to it, indicating completion, and the solution is balenaEtcher.

References

Section titled “References”