GuidesAPI Reference
Join the Mailing List

Storage: Add Disk to a VM

(Intel-only) How to create and attach an empty disk to a deployed VM.

Suggest Edits

๐Ÿ“˜

Orka 2.4.x content

This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.

๐Ÿ“˜

Known limitation

This guide is applicable only to Intel-based VMs.

For more information, see Feature Parity: Apple Hardware.

๐Ÿšง

Quick navigation

Before you begin: How does attached storage work | Current limitations
Prepare your storage: Create an empty disk | Upload an image | Pull an image
Attach the disk: Attach to a VM configuration | Attach during orka vm create | Attach during deployment
Complete the setup: Restart the VM | Format the disk

๐Ÿšง

Quick command summary

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

orka vm create-config -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -d <STORAGE> -y
orka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -d <STORAGE> -y
orka vm deploy -v <NAME> -d <STORAGE> -y

orka vm attach-disk -v <VM_ID> -d <STORAGE> -y

orka vm stop -v <NAME> -y && orka vm start -v <NAME> -y


POST /resources/image/generate
POST /resources/vm/create
POST /resources/vm/deploy
POST /resources/vm/attach-disk
POST /resources/vm/exec/stop
POST /resources/vm/exec/start

You can attach a non-bootable disk to a VM configuration or a VM to increase its storage. You can attach any non-bootable storage disk created with the image generate operation, uploaded with the image upload operation, or pulled from the remote repo with the image pull operation.

You can attach a disk to:

  • a VM configuration, when creating it
  • a VM when creating it
  • a VM during deployment
  • a deployed VM

How does attached storage work

When you attach a disk, you are referencing a non-bootable base image from the Orka image storage. Orka needs to preserve the state of its base images. To achieve this, the attach disk functionality creates an independent volume copy of the specified base image and attaches it to the VM. The base image becomes detached and the volume copy automatically persists as long as the respective VM lives. Your VM writes any changes to its independent writable copy and the initial base image remains unchanged.

To trigger this process, you need to shut down and restart the VM. After the initial restart to activate the attached storage, there is a 20-30 seconds delay created by the operating system. During that time, any new data intended for the added storage is stored in the RAM.

After the base image is detached, you can attach it to another VM.

Current limitations

  • You can attach disks only to Intel-based VMs. See Feature Parity: Apple Hardware.
  • You can attach only non-bootable storage disks created with orka image generate, uploaded with orka image upload, or pulled from the remote repo with orka image pull.
  • You cannot save any changes made to an attached storage to the originating base image in the Orka image storage.
  • You cannot create a new image from an attached storage.

Step 1a: Create an empty disk

Generate an empty, unformatted disk of ะฐ specified size:

orka image generate --image <STORAGE> --size <SIZE> -y

curl --location 'http://<ORKA_API_IP>/resources/image/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"file_name": "<STORAGE>",
	"file_size": "<SIZE>"
}'

Make sure to set the .img file extension for the image name.

You can set the size in k (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).

๐Ÿ“˜

Orka lists an unexpected size?

Orka lists generated empty storage disks with a fixed size of ~192k. When attached to a VM and formatted, the disk will appear with its correct size in the VM.

Step 1b: Upload an image

Upload a non-bootable disk from your local machine to the Orka image storage:

orka image upload --image <FILE_PATH> -y

curl --location 'http://<ORKA_API_IP>/resources/image/upload' \
--header 'Authorization: Bearer <TOKEN>' \
--form 'image=@"/path/to/file"'

Step 1c: Pull an image

  1. List the images available in the remote Orka storage: 
    orka image list-remote

    curl --location 'http://<ORKA_API_IP>/resources/image/list-remote' \
--header 'Authorization: Bearer <TOKEN>'
  2. Pull the image that you want to use: 
    orka image pull --image <REMOTE_IMAGE> -y

    curl --location 'http://<ORKA_API_IP>/resources/image/pull' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"image": "<STORAGE>"
}'

Step 2a: Attach the disk to a VM configuration

You can create and deploy a VM configuration with a disk already attached to it.

  1. To create the VM configuration with an attached disk, run:

    orka vm create-config -v <VM_NAME> -b <IMAGE> -c <CPU_AMOUNT> -C <vCPU_AMOUNT> -d <STORAGE> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
		   "orka_vm_name": "<VM_NAME>",
		   "orka_base_image": "<IMAGE>",
		   "orka_image": "<VM_NAME>",
		   "orka_cpu_core": <CPU_AMOUNT>,
		   "vcpu_count": <VCPU_AMOUNT>,
		   "attached_disk": "<STORAGE>"
}'

  2. When deploying the VM configuration, make sure that Orka has pre-populated the [Attached disk] field with the name of the disk as specified in the VM configuration.

    orka vm deploy -v <VM_NAME> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_NAME>"
}'

Although Orka does not prompt you to restart, make sure to go to Step 3 in this tutorial and restart the VM.

Step 2b: Attach the disk during orka vm create

This step is applicable only to the Orka CLI.

You can attach a disk during the creation of a VM with orka vm create:

orka vm create -v <VM_NAME> -b <IMAGE> -c <CPU_AMOUNT> -C <vCPU_AMOUNT> -d <STORAGE> -y

Although Orka does not prompt you to restart, make sure to go to Step 3 in this tutorial and restart the VM.

Step 2c: Attach the disk during deployment

To attach a disk to a VM during its deployment, run:

orka vm deploy -v <VM_NAME> -d <STORAGE> -y

Although Orka does not prompt you to restart, make sure to go to Step 3 in this tutorial and restart the VM.

Step 2d: Attach the disk to an existing VM

When attaching a disk to a VM, you need to specify the VM by ID.

  1. To get the ID of the VM, run:

    orka vm status -v <VM_NAME> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/status/<VM_NAME>' \
--header 'Authorization: Bearer <TOKEN>'

  2. To attach the additional storage, run:

    orka vm attach-disk -v <VM_ID> -m <MOUNT_POINT> -d <STORAGE> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/attach-disk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_ID>",
	"image_name": "<STORAGE>",
	"mount_point": "<MOUNT_POINT>"
}'

If this is your first attached disk for this VM, the mount point is sdc. If you've attached any other disks to this VM previously, increment the last letter of the suggested mount point as needed. For example, if this is your third attached disk, the mount point is sde.

Step 3: Restart the VM

You need to restart your VM for it to recognize the attached disk and for Orka to detach the respective base image (but preserve the volume copy and start writing to it). See How does attached storage work.

Make sure that you've completed the OS setup of your VM before you proceed.

  1. To get the ID of the VM, run:

    orka vm status -v <VM_NAME> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/status/<VM_NAME>' \
--header 'Authorization: Bearer <TOKEN>'

  2. Power off and then power back on the VM from the command line. Run the following commands separately:

    orka vm stop -v <VM_ID> -y && orka vm start <VM_ID> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/exec/stop' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_ID>"
}'

curl --location 'http://<ORKA_API_IP>/resources/vm/exec/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
	"orka_vm_name": "<VM_ID>"
}'

Step 4: Format the disk

If you have attached unformatted storage, your VM recognizes that there's storage attached but it needs to format it to be able to work with it.

You can format the disk by connecting to your VM via VNC and then following the OS prompts.

  1. To establish a VNC connection to your VM, you first need to get the VM's IP and VNC port:

    orka vm status -v <VM_NAME> -y

    curl --location 'http://<ORKA_API_IP>/resources/vm/status/<VM_NAME>' \
--header 'Authorization: Bearer <TOKEN>'

  2. Launch your VNC client and provide the VM's IP and VNC port. When prompted that the disk is unreadable, click Initialize.

    ๐Ÿ‘

    TIP: Not seeing this prompt?

    Restart the VM from the OS.

  3. In the Disk Utility dialog, select the disk that matches the size of the one you created and click Erase.

  4. Set a name, configure the format and scheme settings, and click Erase.

  5. When the operation completes, click Done and close the Disk Utility.

Your empty storage is now available for use.

See also

Updated 5 months ago

ยฉ 2019-2023 Copyright MacStadium, Inc. โ€“ Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.