How to use custom Images with the IaaS-API

This tutorial guides you through the management of custom images with the Iaas-API.

Creating a custom Image

This guide explains how to create a new Ubuntu image, to begin, you have two main options:

1. Download a pre-made image from the official Ubuntu website
2. Manually create a custom image for your virtual machine

The choice depends on your specific requirements and level of customization needed. If you opt for manual creation, ensure you’re familiar with the process and have the necessary tools and knowledge to create a compatible image for your STACKIT environment. For more detailed information on creating images for other operating systems or using different methods, consult other documentations.

Convert an Image

If you have an image in a format that is not accepted by STACKIT, you can convert it to the raw format using Qemu. For more detailed information, please refer to the Qemu documentation.

Install qemu-img

sudo apt-get install qemu-utils

Convert the image

qemu-img convert -O raw not_supported_image new_image

Now you can continue with the image upload.

Upload an Image

Log in to the STACKIT CLI to authenticate and gain access to the IaaS API.

stackit auth login

Create the (queued) image

stackit curl -X POST -H "Content-Type: application/json" --data '{"active": true, "diskFormat": "<DISK_FORMAT>","name": "<IMAGE_NAME>"}' https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images

• "active": true - the Image is set to active
• <DISK_FORMAT> should be replaced with the format of your image (possible formats: “raw”,“qcow2”,“iso”)
• <IMAGE_NAME> sets the name for the new image

The command returns the Image ID and the Image Upload URL. The url is valid exclusive for that image and expires after a few hours. Upload can be done with any tool, in this example we use curl.

Upload image

curl -X PUT -H 'Content-Type: binary/octet-stream' --upload-file "<IMAGE_FILE>" "<IMAGE_UPLOAD_URL>" | cat

• <IMAGE_FILE>: has to be replaced with the path to the Image file you want to upload
• <IMAGE_UPLOAD_URL>: has to be replaced with target URL from the previous command

Share an image

An image can only be shared in the same organization.

Check if your created image is in the state “AVAILABLE”. You can e.g. get your imageID from the presented upload URL “https://image-upload.object.storage.eu01.onstackit.cloud/imageID”

Describe image

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>

Share an Image with projects

To share your image with one or more projects you need to fill in the project ids to which you want to share your image.

Share image with projects

stackit curl -X PATCH -H "Content-Type: application/json" --data '{"projects": ["<PROJECT_ID1","<PROJECT_ID2>"]}' https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>/share

To check the sharing status of an image use the following command.

Check sharing status

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>/share
Output:
{"parentOrganization":false,"projects":["<PROJECT_ID1","<PROJECT_ID2>"]}

Share an Image with an organization

Use the following command to share an image with an organization.

Share image with an organization

stackit curl -X PATCH -H "Content-Type: application/json" --data '{"parentOrganization": true}' https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>/share
-958a21445138/share Output:
{"parentOrganization":true,"projects":["<PROJECT_ID1","<PROJECT_ID2>",...]}

Remove an Image sharing

Remove an image sharing

To remove project sharing:
stackit curl -X PUT -H "Content-Type: application/json" --data '{"projects": []}' https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>/share
To remove organization sharing:
stackit curl -X PUT -H "Content-Type: application/json" --data '{"parentOrganization": false}' https://iaas.api.eu01.stackit.cloud/v1/projects/<PROJECT_ID>/images/<IMAGE_ID>/share

Use the image to create a VM

For the creation of the virtual Machine please refer to How to create a VM via IaaS-API to create the root disk and the VM.