Getting Started with Anka

Anka comes in two tiers, Anka Flow and Anka Build. Anka components are written in various languages. See the table below:

Tier Component Language Description
Both Core Hypervisor C, C++ The underlying hypervisor technology, built using native macOS virtualization frameworks.
Both anka Python The command-line-utility included with Anka. Enables direct or automated workflows.
Both ankaview ObjC macOS UI viewer application for viewing the VM video.
Both Guest Add-ons C++ Paravirtual disk and network drivers that enable high performance in Anka VMs.
Anka Build only Controller & Registry Go Anka’s REST API service for provisioning on-demand virtual machines and virtual machine storage appliance for distributing VMs to CI or developers.
Anka Build only Jenkins plugin Java Jenkins plugin written for working with Anka Controller for on-demand provisioning.
Anka Build only TeamCity plugin Java TeamCity plugin written for working with Anka Controller for on-demand provisioning.
Anka Build only GitLab CI Intg GO GitLab CI Runner for Anka Build (https://github.com/veertuinc/gitlab-runner).

The latest release can be found via the Anka Releases page.

Anka Package - Installation and Upgrade on Mac hardware

Installing Anka (anka binary)

Installing the Anka Hypervisor binary is remarkably simple, just download and run the .pkg installer on all build, test and developer machines. The Anka Flow binary includes the Core hypervisor, anka guest Add-ons. The Anka Build binary package includes an additional Controller node agent.

Note In order to create VMs with nested feature enabled, select nested virtualization checkbox in Customizations while installing Anka through the GUI method.
If using command line, use the following command sudo installer -applyChoiceChangesXML nanka.xml -pkg AnkaBuild-1.4.3.104.pkg -target /.

After running the installer package, anka is found at /usr/local/bin/anka.

Verify the installation by running anka version command.

After install, if the users want to, they can change the location of this default Anka install location link manually.

Execute sudo mv /usr/local/bin/anka /to/any/other/location/.

Verify the installation by running anka version command.

View all settings for Anka installation on the host with anka config -l command.

anka config [OPTIONS] [PARAM]

  Manage Anka configuration

Options:
  -l, --list   List value parameter(s)
  -r, --reset  Reset value of parameter(s)
  --help       Show this message and exit

Licensing

Get started with Anka Flow or Anka Build with a 30 Day Trial license. Trial license can be obtained for multiple mac machines at www.veertu.com. Trial license is issued for Anka Build Enterprise tier, so you can experience all the features during the POC. Anka Flow is only supported on developer mac machines - Macbook Pro, Macbook Air and iMac.

Anka Build commercial license is available in two tiers.

  • Anka Build Basic
  • Anka Build Enterprise

Anka Commercial license is an yearly license subscription and is priced per core. As an example, if you want to setup an Anka Build cloud on 5, 6-core mac minis, then you will purchase Anka Build license subscription for quantity 30 cores. Contact Veertu support for more details on pricing.

Activating License

Use anka license to activate and manage your 30 day trial or paid license. Anka license activate relies on the http_proxy-environment-variables to reach out to Anka license activation server.

anka license --help
Usage: anka license [OPTIONS] COMMAND [ARGS]...

  licensing commands

Options:
  --help  Show this message and exit.  [optional]

Commands:
  accept-eula  accept EULA (root privileges)
  activate     activate license key (root privileges)
  remove       removes the current license (root privileges)
  set          set license created by ankalic (root...
  show         show info about the current license
  validate     validates the current license

To activate license execute sudo anka license activate <licensekey>

Version

You can view Anka’s version on your machine by running the following command anka version.

Now, you are ready to create and run macOS VMs. Refer to Creating VMs section of the documentation.

Upgrading Anka (anka binary)

Download the latest version of Anka package (.pkg) and stop all running VMs. Before upgrading, you will also need to force stop any suspended VMs with the anka stop -f vmname command.

Execute the following command to upgrade guest addons in existing VMs to the current release.

anka stop -f vmname
anka start -u vmname
Preparing update configuration
Installing updates
Suspending
update succeeded

Your VM is now upgraded. Push it to registry with a new tag and refer to the new tag in your build pipeline, Jenkins Plugin.

Note -> Post version 1.2, you will not have to upgrade your VMs with every Anka upgrade, unless the guest addons are changed. If an upgrade is required, you will see the following in addons version field when you start the VM.

anka start -v build12
+-----------------------+--------------------------------------+
| uuid                  | eb278926-1d95-11e8-ac36-003ee1cddd4c |
+-----------------------+--------------------------------------+
| name                  | build12 (v6)                         |
+-----------------------+--------------------------------------+
| description           | test3                                |
+-----------------------+--------------------------------------+
| cpu_cores             | 18                                   |
+-----------------------+--------------------------------------+
| ram                   | 8G                                   |
+-----------------------+--------------------------------------+
| hard_drive            | 40 GB (11.5 GB on disk)              |
+-----------------------+--------------------------------------+
| addons_version        | 1.2.0.85 (update recommended)        |
+-----------------------+--------------------------------------+
| status                | running                              |
+-----------------------+--------------------------------------+
| vnc_connection_string | vnc://:admin@207.254.51.228:5901     |
+-----------------------+--------------------------------------+
| view_vm_display       | anka view build12                    |
+-----------------------+--------------------------------------+

Update the guest addons with anka start -u VMNAME command.

If you are not able to upgrade the guest add-ons tool using the anka start -u vmname command, then you have a very old version of guest addon tools on your VM. You will first need to manually update them. Contact Veertu support.

Registry and Controller - Installation and Upgrade

Installation on Linux

Registry and controller are packaged in a single package (anka-controller-registry-XXX.tar.gz), which containes two docker containers for registry and controller. Registry and Controller runs on Ubuntu 16.0.4. For non-Docker based installation, contact support@veertu.com.

Ports Information

CI system calls the Anka Controller over http or https, default port 8090. Anka Controller doesn�t communicate with Anka Build nodes. Nodes communicate with controller through Beanstalk Queue service(installed as part of controller) on port 11300. The default port for Anka registry is 80.

Linux Installation Instructions

Move the tar file to a directory where you want the containers to run. Uncompress the tar package.

For Docker-based registry installation, first edit the docker-compose.yml included in the package with path location where you will store registry VMs. Change /Users/administrator/Desktop/registryvm to your VM storage path location.

volumes:
      - `/Users/administrator/Desktop/registryvm:/mnt/vol`	  

In docker-compose.yml you can also edit the port mapping. The default is set to port 80. Change the first part before the colon in the line below to your specific port no. For example "82:80"

ports:
       - `"80:80"`

For Docker-based controller installation, edit the ENV REGISTRY_ADDR variable in the anka-controller.docker file to point to IP of your registry.

ENV REGISTRY_ADDR       http://xx.xxx.xxx.xxx

Execute the following commands

sudo docker-compose build
sudo docker-compose up -d

Execute docker ps -a to check if the anka controller and anka registry containers are up and running. Attach to the registry container and verify the registry version.

docker exec -it <registry containerid> bash
anka-regctl -v

The Controller and Registry services of Anka Build Cloud can also run on Mac hardware. This setup is not recommended for production setup of Anka Build. However, for a quick POC, you can configure all Anka Build software components on Mac hardware.

Follow these steps to configure Registry and Controller on Mac hardware.

The anka-controller-registry-mac-X.X.XX package installs Controller as a Docker Container on the Mac and Registry as a Mac application.

  • Step 1 - Download and Install docker for Mac.
  • Step 2 - Download the Controller/registry package for Mac (anka-controller-registry-mac-X.X.XX) from Anka Build download page.
  • Step 3 - cd to anka-controller-registry-mac-X.X.XX directory.
  • Step 4 - Go to anka-controller.docker file and replace the ENV REGISTRY_ADDR variable value of http://10.10.10.10 with your Mac IP address.
  • Step 5 - Execute sudo sh install.sh. This will install the container and registry for Mac.
  • Step 6 - Go to browser and connect to http://localhost:8090. You will see the Anka Build Cloud portal.
  • Step 7 - Default location of VM storage in Mac Registry is /Library/Application\ Support/Veertu/Anka/registry/

To Uninstall, follow these steps.

  • Step 1 - Delete all Vms stored in the Registry. Go to /Library/Application\ Support/Veertu/Anka/registry/ and delete all directories.
  • Step 2 - To Uninstall Mac registry, execute the following command sudo launchctl unload -w /Library/LaunchDaemons/com.veertu.anka.registry.plist.
  • Step 3 - Remove Controller container with docker-compose down command.

Registry and Controller - Changing configuration

For Linux based Registry and Controller setup

Go to the directory where Controller and Registry containers are running. Execute the following command to stop the containers.

sudo docker-compose down

Make necessary changes in the docker-compose.yml and/or anka-controller.docker files. Start the containers with following command.

Execute the following commands

sudo docker-compose build
sudo docker-compose up -d

Upgrading Registry & Controller

For Linux based Registry and Controller setup

Kill the existing registry and controller containers with the following command.

sudo docker-compose down

Download the new controller-registry package. Decompress it.

Edit the docker-compose.yml included in the package and enter the storage path to registry VMs volume.

volumes:- 
`/Users/administrator/Desktop/registryvm:/mnt/vol`

Edit the ENV REGISTRY_ADDR http://xx.xxx.xxx.xxx in anka-controller.docker file to point to your registry address.

Execute following commands to start the docker containers.

sudo docker-compose build
sudo docker-compose  up -d

For Mac based Registry and Controller setup

  • Download the new anka-controller-registry-mac-X.X.XX package from the Anka Build download page on the Mac.
  • cd to anka-controller-registry-mac-X.X.XX directory.
  • Stop the running Controller Container sudo docker-compose down
  • Execute sudo sh install.sh. This will install the latest container and registry for Mac.
  • Go to browser and connect to http://localhost:8090. You will see the Anka Build Cloud portal.

Controller Management Portal UI

Starting Anka version 1.2 release, a new web UI service was added to the controller module. This is a Anka Build Controller Management portal. When you install controller, it gets automatically installed. You can access it by going to your controller IP - http://xx.xxx.xxx.xxx:8090. See Controller Management Portal UI section for more details.

Uninstalling Anka

From the command line, execute the following command. Make sure all your VMs are stopped.

sudo /Library/Application\ Support/Veertu/Anka/tools/uninstall.sh

Known Issues

  • macOS 10.14 upgrade to 10.14.1 inside Anka VM, with UI upgrade procedure, is not functional. Use softwareupdate tool as a workaround.