Setting up the Controller & Registry on macOS

Welcome! This tutorial guides you through setting up your Anka Build Cloud Controller & Registry on MacOS.

This guide is for first time users and shouldn’t be used for upgrading. Please use the upgrading guide instead.

Checklist

Set up the Anka Build Cloud components.
Get Orientated.

MacOS

The macOS package will install and run using Apple’s Rosetta. There is no native arm package at this time.

Necessary Hardware

A Mac to install the Anka Controller and/or Registry.
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.

Download the Controller and/or 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/ -f5) https://veertu.com/downloads/ankacontroller-registry-mac-latest

Install the Controller and/or 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/ -f5) -target /

Verify your installation (macOS)

Two methods are available:

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

Orientation (macOS)

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 in: /Library/Application Support/Veertu/Anka/anka-controller
Registry data will be saved in: /Library/Application Support/Veertu/Anka/registry

Configuration and Scripts

Config 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:8089"
export ANKA_REGISTRY_LISTEN_ADDRESS=":8089" 
```

Logging (macOS)

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)

Step 3: Link the Anka CLI Node to the Controller (macOS)

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 (macOS)

This is not needed on all Nodes connecting to the Controller. Most users have a “builder machine” that has the registry connection and is used to create and push VM Templates/Tags.

We now need to configure the Registry on this machine so we can push/upload the local VM Template so other machines connected to the Anka Build Cloud. 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 (macOS)

sudo anka registry push 12.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 (macOS)

Be sure to run ankacluster as root.

Avoid using underscores in your domainnames/urls.

❯ 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.

The Anka agent is listening on a socket to provide status information at runtime. You can override the path of the socket by setting the ANKA_AGENT_SOCKET env var.

Check Join Status

You can check the status of the Anka agent using the ankacluster status command.

❯ ankacluster status
status: running
config:
  vm_limit: 2
  optimization_threshold: 5
  num_workers: 2
  controller_addresses:
  - http://anka.controller.dev
  version: 1.13.0-6cd34a2c
  capacity_mode: number
  heartbeat: 5s
  node_name: MyMacMiniNode
  vm_stuck_check_delay: 30s
  vm_stuck_check_timeout: 10s

Step 4: Start a VM instance using the Controller UI (macOS)

Go to your Controller dashboard and click on the Instances tab:
Click on Create Instance(s), and the Create New Instances view displays:
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:
After the Scheduling and Pulling finishes, the VM starts on one of the Nodes and shows a Started State in the Controller UI:

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": ""
}

Timestamp format: https://www.ietf.org/rfc/rfc3339.txt

Standalone Registry (macOS)

Often we find that customers wish to run the Anka Build Cloud Registry alongside their Anka Nodes to optimize the speed of pulling VM Templates, but keep the Controller hosted in a cloud offsite.

In order to run the standalone registry on macOS you’ll download and install the the registry standalone pkg. Below you will find instructions for configuration.

Orientation (macOS/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 Launchd daemon xml file at /Library/LaunchDaemons/com.veertu.anka.registry.plist. Be sure to unload it first.
Data will be saved in: /Library/Application Support/Veertu/Anka/registry

Configuration (macOS/registry)

In order to change the configuration of your registry on macOS, you’ll need to unload the plist with sudo launchctl unload -w /Library/LaunchDaemons/com.veertu.anka.registry.plist and then edit it to include what you need. You can get a full list of supported config options from the help output:

❯ /Library/Application\ Support/Veertu/Anka/bin/ankaregd --help
Usage of /Library/Application Support/Veertu/Anka/bin/ankaregd:

-access_logs                           Enables registry access logs.

-add_dir_header                        If true, adds the file directory to the header of the log messages

-alsologtostderr                       log to standard error as well as files (default: "true")

-api-keys-cleaning-interval (duration) The interval for cleaning of expired api keys. (default: "4h0m0s")

-api-keys-session-ttl (duration)       The API Keys session TTL (used for automatic expiration). (default: "5m0s")

-backend-plugin-path (string)          The path to a backend plugin (instead of using disk)

-base-path (string)                    Set the registry data's base path (default: ".")

-ca-cert (string)                      (Certificate Authentication) The CA/root cert used to authenticate incoming requests/certs.
. . .

What next?

Prepare and join your machines to the Build Cloud.
Connect the cloud to your CI software.
Find out how to use the Controller REST API.