Setting up on macOS

Set up your Anka Build Cloud on macOS

Welcome! This tutorial will guide you through setting up your Anka Build Cloud.

Necessary Hardware

  1. A Mac to install the Anka Controller & Registry.
  2. A second Mac to install the Anka CLI (the “Node”).

You can complete this tutorial with only one machine running Mac OS, but it's not recommended.

What we are doing in this tutorial

  1. Install the Anka CLI + Create your first VM Template
  2. Install the Anka Build Cloud Controller & Registry
  3. Link the Anka CLI Node to the Controller
  4. Start a VM instance using the Controller UI

Step 1: Get familiar with the Anka CLI

Install the Anka Virtualization package

Download and install with your terminal

terminal installation

curl -L -o AnkaVirtualization.pkg https://veertu.com/downloads/anka-virtualization-latest
sudo installer -pkg AnkaVirtualization.pkg -tgt /

Verify the installation

❯ anka version
Anka version 2.X.X (build XXX)

For Anka CLI commands and options, see the Command Reference.

Obtain the macOS installer

There are multiple ways to obtain the installer .app file for Mac OSX that we'll detail for you below:

  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
  5. Have your local IT department provide a network volume or download links.

Create the VM Template

Using the Anka UI

Using the Anka CLI

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

You can find detailed instructions for anka create here.

You can continue on to Step 2 while you wait for this to finish.

Step 2. Install the Anka Build Cloud Controller & Registry

Perform the following steps on the machine intended to run the Controller & Registry.

Download the Controller & Registry PKG

Download the file called “Cloud Controller & Registry (Run on Mac)” from Anka Build Download page. If you are more comfortable with the command line, you can download the file with curl:

curl -S -L -o ~/Downloads/$(echo $(curl -Ls -r 0-1 -o /dev/null -w %{url_effective} https://veertu.com/downloads/ankacontroller-registry-mac-latest) | cut -d/ -f4) https://veertu.com/downloads/ankacontroller-registry-mac-latest

Install the Controller & Registry PKG

Double click on the .pkg to start the UI install process.

  • Or, you can install the package using the command line:
    sudo installer -pkg ~/Downloads/$(echo $(curl -Ls -r 0-1 -o /dev/null -w %{url_effective} https://veertu.com/downloads/ankacontroller-registry-mac-latest) | cut -d/ -f4) -target /

Verify your installation

Two methods are available:

  • Use the CLI status command:
    sudo anka-controller status
  • Use curl:
    curl http://<ip>:8080/api/v1/status

Anka Controller should be listening on port 80 (HTTP). Try pointing your browser to the machine's IP or hostname. You can use localhost or 127.0.0.1 if you're on the Controller machine.

Your new dashboard should look like the picture below

How your new dashboard looks like

Orientation

Let's take a look at what is now running on your machine:

  1. Anka Controller is serving web UI and REST API on port 80.
  2. Anka Registry is serving REST API on port 8089.
  3. ETCD database server serving on ports 2379 and 2380 (used by Anka Controller).

Configuration and scripts (reference)

The Anka Controller AND Registry command is installed into /usr/local/bin/anka-controller. To see what functions it has, execute the script with root privileges:

sudo anka-controller
usage: /usr/local/bin/anka-controller [start|stop|restart|status|logs]

When sudo anka-controller start is executed, the script will use launchd to load the daemon: /Library/LaunchDaemons/com.veertu.anka.controller.plist.

  • The Anka Controller & Registry run script is /usr/local/bin/anka-controllerd. This file acts as a run script and configuration file. You can modify it to change the default ports used by adding the proper option or ENV. For example, if you want to run the Registry on a different port and use 127.0.0.1, you would add the following above the "$CONTROLLER_BIN" line (reference):
    export ANKA_ANKA_REGISTRY="http://127.0.0.1:8081"
export ANKA_REGISTRY_LISTEN_ADDRESS=":8081"

Logging

Logs are written to /Library/Logs/Veertu/AnkaController by default:

/Library/Logs/Veertu/AnkaController/anka-controller.INFO
/Library/Logs/Veertu/AnkaController/anka-controller.WARNING
/Library/Logs/Veertu/AnkaController/anka-controller.ERROR

You can modify the destination in the /usr/local/bin/anka-controllerd file (reference).

You can also watch the logs live (similar to tail -f):

sudo anka-controller logs

The log level can be modified from the default 0 value. The higher the number, the more verbose the logging. (reference)

Great! Now that we have our Anka Controller & Registry up and running, let's add Nodes!

Perform the following steps on the Node where you created your first VM Template.

Add the Registry

We now need to configure the Registry on this machine so we can push/upload the local VM Template we created earlier. Uploading the Template to the Registry makes it possible to download and run it from other nodes.

Assuming you haven't changed the default port configuration, your Registry is serving requests on port 8089.

sudo anka registry add <registry name here> http://<ip>:8089

Verify the configuration:

sudo anka registry list-repos
++
++

<registry name you set> (default)

+--------+------------------+
| host   | <the ip you set> |
+--------+------------------+
| scheme | http             |
+--------+------------------+
| port   | 8089             |
+--------+------------------+

Then, confirm the registry list command doesn't throw any failures:

sudo anka registry list

Push the VM to the Registry

sudo anka registry push 10.15.X -t base

After the push completes, you should see your new Template in the “Templates” section of the controller UI.

Your first template

Join to the Controller & Registry

sudo ankacluster join http://<ip>
Password:
Testing connection to controller...: Ok
Testing connection to the registry...: Ok
Ok
Cluster join success
  • Replace <ip> with the IP of the machine hosting your controller:
  • If you changed the default port for the controller from 80, you'll need to use the new port at the end of the IP. Otherwise, leave it off.

The command may hang for a few moments and then display Cluster join success. Please report any errors you find to support@veertu.com.

Step 4: Start a VM instance using the Controller UI

  1. Go to your Controller dashboard and click on the Instances tab:

    your instances view

  2. Click on Create Instance(s), and the Create New Instances view displays:

    new instances view

  3. Select the VM Template and click Start. The Create New Instances view closes and returns you to the Instances view. You should now see the Instance in a Scheduling or Pulling State: a scheduling instance

  4. After the Scheduling and Pulling finishes, the VM starts on one of the Nodes and shows a Started State in the Controller UI:

    a started instance

You can now confirm the Instance is running from inside the Node:

  • JSON output is available for scripting/automation using anka --machine-readable
sudo anka --machine-readable list | jq
{
  "status": "OK",
  "body": [
    {
      "status": "suspended",
      "name": "catalina",
      "stop_date": "2020-04-01T21:30:59.798697Z",
      "creation_date": "2020-04-01T00:00:13.656296Z",
      "version": "base",
      "uuid": "10c720eb-dcce-46f7-baa3-28bacef0ec0f"
    },
    {
      "status": "running",
      "name": "mgmtManaged-catalina-1585776660490226000",
      "stop_date": "2020-04-01T21:36:11.742662Z",
      "creation_date": "2020-04-01T21:31:01.055250Z",
      "version": "",
      "uuid": "dcbeb319-421a-4d30-8466-194eb7fa5f75"
    }
  ],
  "message": ""
}

Orientation

Anka Controller and Registry package

  • Default Ports: Anka Controller: 80 / Anka Registry: 8089
  • Binaries and scripts: Anka Controller has only one combined binary. It can run Anka Controller, Anka Registry and ETCD Server.
    Installed at: /Library/Application Support/Veertu/Anka/bin/anka-controller
    Start script: /usr/local/bin/anka-controllerd
    Start/Stop script: /usr/local/bin/anka-controller
    Launchd daemon: /Library/LaunchDaemons/com.veertu.anka.controller.plist
  • Configuration files: Configuration for this package is done by altering the start script at /usr/local/bin/anka-controllerd.
  • Logs: /Library/Logs/Veertu/AnkaController
  • Data: ETCD data will be saved at: /Library/Application Support/Veertu/Anka/anka-controller
    Registry data will be saved at: /Library/Application Support/Veertu/Anka/registry

Standalone Anka Registry

  • Default Ports: 80
  • Binaries and scripts: Anka Registry for Mac binary is installed at: /Library/Application Support/Veertu/Anka/bin/ankaregd
    Launchd daemon: /Library/LaunchDaemons/com.veertu.anka.registry.plist
  • Configuration files: Configuration for this package is done by altering the Launcd daemon xml file at /Library/LaunchDaemons/com.veertu.anka.registry.plist.
  • Data: Will be saved at: /Library/Application Support/Veertu/Anka/registry

What next?


Last modified September 4, 2020 : quick fix (8bd2c06) by Nathan Pierce