Base Images

This page discusses base image workflows in the Orka CLI. For more information about workflows with the Orka API, see Orka API Reference: Images.

On this page, you will learn how to:

• List the available base images.
• Add base images to the local Orka storage by generating, uploading or pulling files.
• Download a base image from Orka storage to your local machine.
• Use VMs to expand and enrich your collection of base images.

📘

Quick command summary

orka image [list / list-remote / upload / download / pull / generate]
orka image [commit / save]

🚧

Apple ARM-based Nodes Support

Orka 2.0 introduces Apple ARM-based nodes support which adds a new type of images. To deploy a VM on an Apple ARM-based node, you need to use any of the Apple Silicon images which have extension .orkasi and are marked as Apple Silicon in the image list. Supported operations for Apple Silicon images are: list, list-remote, pull, commit, save.

Read more about Apple ARM-based Support to see which commands and options are supported for VMs deployed on Apple ARM-based nodes.

A base image is an existing bootable disk image file stored in Orka and used exclusively for the creation of VM configurations. The actual storage for newly created VM configurations is based on a base image specified by the user.

Base images remain unchanged over time and can be used again and again for the creation of VMs and VM configurations.

Base images are stored as .img files in the Orka storage. Base images live in the Image Manager namespace and are shared across the same Orka environment. All users can access them and use them to create VM configurations.

List the available base images

Your Orka environment comes pre-configured with one or more base images that you can use to create VM configurations. MacStadium also maintains a remote repo with additional base images which you can pull into your Orka environment.

1. List the base images in the local Orka environment.

orka image list

2. List the base images in the remote repo.

orka image list-remote

Add a base image to the local Orka storage

📘

IMPORTANT

When prompted to set a name for your base image, set the .img extension.

Orka lets you pull remote base images, upload your own base image, and generate empty base images.

1. To upload your own base image, use this command:

orka image upload

OR

orka image upload --image <FILE_PATH> -y

2. To pull an image from the remote repo, run the following command.

orka image pull

OR

orka image pull --image <REMOTE_IMAGE> -y

3. To generate a new empty image, run the following command. Empty base images are useful when you want to attach additional storage to a VM or when you need to create a VM with an empty disk. You will then need to attach an ISO. See Working with ISOs .

orka image generate

OR

orka image generate --image <NAME> -q <SIZE> -y

OR

orka image generate --image <NAME> -q <SIZE> --json

Download a base image from Orka storage to your local machine

You may wish to download a base image, for backup purposes or to transfer the image to another environment. For example, it may be desirable to test a new image in a staging cluster and then upload that image to your production cluster.

📘

IMPORTANT

Make sure you have enough available disk space for the image on your local disk before beginning the download. Base images may be tens or hundreds of gigabytes in size.

To download a base image, run the following command:

orka image download

OR

orka image download --image <NAME> --output <FILE_PATH> -y

Create or update a base image from a deployed VM

📘

IMPORTANT

Always restart the VM before running save or commit because some settings (like enabling of SSH) do not persist if the VM is not restarted.

You can use a deployed VM to create a new base image or update an existing one (restrictions apply). Create a VM config with the base image and you will have a new container template that has all the software and configuration you require.

1. To create a new base image from an existing Orka VM, run the following command. The image name you specify needs to be unique.

orka image save

OR

orka image save -v <VM_ID> -b <NEW_IMAGE_NAME> -y

This operation stops the VM.

The command creates a new base image from the disk image of the source VM. The new base image has all the software installed and the configurations made to the VM on it.

2. To update a base image, run the following command. The base image must be in use only by this VM, and the VM must be running and non-scaled.

orka image commit

OR

orka image commit -v <VM_ID> -y

This operation stops the VM.

The command overwrites the base image in use by the VM. The modified base image has all the software installed and the configurations made to the VM on it.

👍

TIP

Enable SSH on an Orka VM, restart the VM, and save it as a new base image. Next, create a VM configuration from that base image. This way, you can quickly spin up new SSH-enabled Orka VMs.