Base Images
How to list, pull, generate, upload, and update base images with the Orka CLI.
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 asApple 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.
- List the base images in the local Orka environment.
orka image list
- 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.
- To upload your own base image, use this command:
orka image upload
OR
orka image upload --image <FILE_PATH> -y
- To pull an image from the remote repo, run the following command.
orka image pull
OR
orka image pull --image <REMOTE_IMAGE> -y
- 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
orcommit
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.
- 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.
- 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.
Updated about 2 years ago