Creating your first VM

Prerequisites

1. You've installed the Anka Virtualization package
2. You've got an active license

1. Obtain the macOS installer

• 11.x.x (macOS Big Sur)
• 10.15.x (macOS Catalina)
• 10.14.x (macOS Mojave)
• 10.13.x (macOS High Sierra)
• 10.12.x (macOS Sierra)

1. If you have a pending upgrade to the next minor or patch version of Mac OS:
   • Within Preferences -> Software Update -> Advanced, make sure Download new updates when available is checked but Install macOS updates is not. While you're still within Software Update, click Update Now but do not install the next version (Restart) until after you've created the Anka VM or the Install .app under /Applications will be deleted.
   • You can also use the App Store to download the installer.
2. On Catalina, you can use softwareupdate: sudo softwareupdate --fetch-full-installer --full-installer-version 10.15.6
3. Have your local IT department provide a network volume or download links.
4. Use our Getting Started script, but run it with ./create-vm-template.bash --no-anka-create

As an alternative to the macOS installer, you can also use an iso

2. Create your VM

The Anka VM is pre-configured with a default administrative username anka and password admin. You can override this with ENVs: ANKA_DEFAULT_USER and ANKA_DEFAULT_PASSWD

Anka Develop license (default): While you can create as many VMs as you wish, the free Anka Develop license only allows you to run one VM at a time and will only function on laptops (Macbook, Macbook Pro, and Macbook Air).

Anka Build license:

1. When determining how many vcpus and ram your VM needs, you can divide the number of VMs you plan on running simultaneously within a host by the total virtual cores (vcpus) it has. So, if I have 12vCPUs on my 6core Mac Mini, and I want to allow 2 running VMs at once and not cripple the host machine, I will set the VM Template/Tag to have 6vcpus (12 / 2). However, with RAM, you'll need to allow ~2GB of memory for the Anka Software and host ((totalRAM / 2)-1).
2. Pushing and pulling your VM from the registry can be optimized by setting anka config chunk_size 2147483648 on the node you create your templates on. It must be set before you create the VM. More about the chunking feature

Using the Anka UI

1. Click on Create new VM
2. Choose the installer (will automatically search /Applications), or drop it into the window
3. Click on Options and set any non-default values you want
4. Please be patient while it's creating. This process can take up to half an hour.

Once the VM template is created, you will see it on the sidebar.

Using the Anka CLI

> sudo anka create --help
Usage: anka create [OPTIONS] VMNAME

  Creates a VM

Options:
  -m, --ram-size TEXT      Set the RAM size (including 'G' or 'M' on the end)
  -c, --cpu-count INTEGER  Set the number of CPU cores
  -d, --disk-size TEXT     Set the disk size when creating a new disk (including 'G' or 'M' on the end)
  -a, --app PATH           Path to the macOS installer .app
  -p, --pkg PATH           Include additional packages to be installed
  -s, --postinstall PATH   Include the script to run with root credentials on initial boot
  -P, --profile PATH       Include a configuration profile(s) to install alongside the macOS installation
  --interactive            Perform default interactive installation instead of the automated one
  --help                   Display usage information

sudo anka create --ram-size 8G --cpu-count 4 --disk-size 80G \
--app /Applications/Install\ macOS\ Catalina.app 10.15.6

Listing available VMs in the CLI

❯ anka list
+------------------------------------------------+--------------------------------------+--------------+------------------------+
| name                                           | uuid                                 | created      | status                 |
+================================================+======================================+==============+========================+
| 10.15.5 (base:port-forward-22:brew-git:gitlab) | c0847bc9-5d2d-4dbc-ba6a-240f7ff08032 | Jul 13 16:40 | suspended Sep 01 20:18 |
+------------------------------------------------+--------------------------------------+--------------+------------------------+
| 10.15.6                                        | 5bba6eea-202e-45ed-9567-d7f55090d049 | Sep 02 10:17 | stopped Sep 02 13:37   |
+------------------------------------------------+--------------------------------------+--------------+------------------------+
| 11.0.1                                         | 2bb1b152-9996-41d6-804a-a429973c13bc | Sep 01 18:45 | stopped Sep 02 14:28   |
+------------------------------------------------+--------------------------------------+--------------+------------------------+
| test                                           | 77f33f4a-75c3-47aa-b3f6-b99e7cdac001 | Sep 03 11:30 | running                |
+------------------------------------------------+--------------------------------------+--------------+------------------------+

Deleting a VM

Using the Anka UI

Using the Anka CLI

❯ anka delete test
are you sure you want to delete vm 77f33f4a-75c3-47aa-b3f6-b99e7cdac001 test [y/N]:

(Anka Build license + Cloud) Understanding VM Templates, Tags, and Disk Usage

This section mentions features (suspending, tagging, and registry push/pull) which are not available with a free Anka Develop license.

When using Anka to create a VM, it's best to think of the result as a VM “Template”. Post-creation from a macOS installer, Anka VM Templates contain the base/“vanilla” macOS installation.

You can create Templates using the anka create command or the Anka UI.

After a VM Template is created, you can use anka view and/or anka run commands to install and configure the system or whatever dependencies and software you need inside of the VM.

An example bash script that shows how to use anka run to instal dependencies.

You can then anka suspend to save the state of the VM. Suspending the VM allows for a fast boot time when running anka start.

Suspending the VM uses a fairly significant amount of disk (roughly the amount of memory you've given the VM Template). It may be better to use a “stopped” state instead to optimize disk space, especially if the Template will not be directly used and instead used for cloning new VM Templates.

It's very important that when you suspend from a started state the VM has fully booted and logged into a user. If you don't, the VM may be frozen or fail to boot. You can script this using anka run {VMTemplateName} sleep 60 or manually check with anka view to ensure it's in a good state.

You can then push the Template to your Anka Build Cloud Registry using anka registry push and set a Tag. Or, use anka registry push -l {vmNameOrUUID} -t {tag} to only create the Tag locally (useful if you don't have a registry yet and want to quickly switch between Tags/dependencies locally while testing).

Important: When you start a VM and make changes, your changes are added to a new layer on top of the existing ones. This means that when you modify a Template or Tag, then push to the registry, or even pull down a new Template or Tag to an Anka Node, you're sharing existing layers and saving disk space and bandwidth. It's important to think about which clone/tagging/layering approach is best for you and your company. Also, each Start of a VM will cause disk space to increase, even if you delete the older versions of your dependencies inside before installing the new. It's best to delete/revert a tag or Template and clone a fresh one when you need to upgrade dependencies.

Tags may not be the easiest and most flexible solution for you. If that's the case, we recommend using cloned Templates. You have two options:

1. Use anka clone without --copy (recommended): The new cloned Template will have no Tags, but will link to the layers/contents from the previous Template and active Tag's state. No new disk space will be used until you start and modify that new Template.
2. Use anka clone with --copy: The new cloned Template will have no Tags, and will copy all of the layers from the source VM Template and active Tag. This doubles the amount of disk space used.

When creating a clone without --copy, deletion of the first Template will not delete the contents of the second cloned Template. Anka CLI will intelligently know that the layers are still in use by the new Template.

Here is a diagram of this:

11.1.0 (stopped)  | 
                  | -> clone -> xcode12.3 (stopped) |
                  |                                 | -> clone -> project1 (with fastlane-v1.X) (suspended)
                  |                                 | -> clone -> project2 (with fastlane-v2.X) (suspended)
                  |
                  | -> clone -> xcode11.7 (stopped) -> clone -> project3 (suspended)

Note the “stopped” state of the first two cloned Templates. Suspended VMs come with a fairly large state file. Unless you plan on using the vanilla 11.1.0 or xcode Templates, the suspended fast booting is only a waste of space. However, you do typically want to suspend the Templates/Tags that your CI/CD and developers will use.

If you're interested in Infrastructure as Code to automate the creation of your Templates and Tags, you have several options:

1. Write scripts that:
   • Sequentially parse and execute commands from a data serialization language like JSON or YAML inside of the VM.
   • Or execute commands inside of the VM from within the script itself (example).
2. Use the Packer Builder: https://github.com/veertuinc/packer-builder-veertu-anka

Optimizing your VM

It's recommended that you disable Spotlight and CoreDuetD inside of the VM to eliminate services that are known to need high CPU:

sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.coreduetd.osx.plist 
sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.metadata.mds.plist

Re-pushing an existing registry tag

Only available for versions >= 2.3.1

On pushing to the registry, a tag is created. It will also be assigned a specific commit ID (not visible to users). Even if you modify the tag locally, such as adding port-forwarding, changes will not be pushed to the registry until you push with a different tag name.

Now, you can simply untag the VM locally and then push it with the same name (after deleting the VM template or reverting the tag):

Locally, this does not remove the current STATE of the tag from the VM. Your installed dependencies inside of the VM will remain as long as you don't pull or switch to a different tag.

anka registry pull -t tag2 VM
anka delete VM:tag2
anka modify VM add port-forwarding...
curl ... (delete or revert from registry)
anka registry push -t tag2 VM

What's next?

• Starting and Accessing your VM

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.