Using Registry

Anka registry provides an easy way to store, version, and distribute macOS VMs that are used for CI and development. Once you’ve completed creation and setup of your VMs anka registry command can be used to upload or download a VM to the Registry. Anka’s INSTANT START feature can also enable VMs stored in the Registry to be quickly booted after distribution.

Using Anka Registry

anka provides a set of commands useful for interacting with the registry. You can view all of the available registry commands by running anka registry --help:

anka registry [OPTIONS] COMMAND [ARGS]...

  VMs registry

Options:
  -r, --remote TEXT         Use specific registry NAME instead of 'default'  [optional]
  -a, --registry-path TEXT  Specify explicit registry URL to use  [optional]
  --help                    Show this message and exit.  [optional]

Commands:
  add                  add repository
  check-download-size  Returns size of the data to be downloaded
  delete               delete repository
  describe             Shows VM description
  list                 List default registry contents
  list-repos           list all the repositories
  pull                 Pull certain VM
  push                 Push local VM version to repository
  set                  set default repository

Adding a new Registry

Configure the destination registry on the machine where you will create macOS VM and then push it to the registry.

anka registry add [OPTIONS] REG_NAME REG_URL

  add repository

Options:
  --client-cert PATH  [optional]
  --client-key PATH   [optional]
  --root-cert PATH    [optional]
  --pem PATH          [optional]
  --help              Show this message and exit.  [optional]
  
$ anka registry add newreg http://XX.XXX.XXX.XXX

Then, you can see the registry entry when listing. Default is shown with default tag against it. Default means the current registry anka client is connecting to.

Usage: anka registry list-repos [OPTIONS]

  list registry repositories

Options:
  -d, --default  show only default repository
  --help         Show this message and exit.
  
$ anka registry list-repos
anka registry list-repos
++
++

awsreg

+--------+----------------+
| host   | xx.xxx.xxx.xxx |
| scheme | http           |
| port   | 80             |
+--------+----------------+

localnew

+--------+-----------+
| host   | xxx.x.x.x |
| scheme | http      |
+--------+-----------+

newreg (default)

+--------+----------------+
| host   | xx.xxx.xxx.xxx |
| scheme | http           |
+--------+----------------+


Use anka registry set command to change the default registry.

If you have installed the registry mac application and will be accessing it from the same machine, then use the following to add the registry.

$ anka registry add REGISTRYNAME http://localhost

When a single registry exists, it is automatically set to the default available registry. If there are multiple registries, use the anka registry set command to connect to a specific registry.

Pushing VMs to Registry

Once you have completed setup of your VMs and have added a new registry, you are ready to push VMs to the registry. anka provides the push command for moving VMs to the registry. As with all anka commands, providing a --help as an argument will print the available usage:

VM_ID can be VMNAME or VM UUID. TAG is the version identifier. -d flag can be used to provide a text description.

$ anka registry push --help
anka registry push [OPTIONS] VM_ID TAG

  Push local VM version to default repository

Options:
  -d, --description TEXT  Assign description to the tag  [optional]
  --help                  Show this message and exit.  [optional]

We want to push the VM sierraiso to Registry with tag v1. We can use the VMNAME for the vm_id above. Note the progress bar provided as well:

$anka registry push -d mysierravm sierraiso v2
Uploading files  [#######################-------------]   65%  0d 00:00:14

After VM has completed uploading to the registry, we can view the VM and its versions by using anka registry describe.

anka registry describe mytcma2
+------+--------------------------------------+
| id   | 025e2466-586c-11e8-b46b-003ee1cde439 |
| name | mytcma2                              |
+------+--------------------------------------+

versions

+----------+-------+-----------+---------------+
|   number | tag   | state     | description   |
|----------+-------+-----------+---------------|
|        0 | v1    | suspended | mar0112v2     |
|        1 | v2    | suspended | mar0112v2     |
+----------+-------+-----------+---------------+


Pulling VMs from Registry

Once you have pushed VMs to Registry, you will be able to pull different versions of that VM. anka provides the pull command to download Vm from the registry. Again, providing a --help as an argument will print the available usage:

$ anka registry pull [OPTIONS] VM_ID

  Pull certain VM

Options:
  -t, --tag TEXT         [optional]
  -v, --version INTEGER  [optional]
  --help                 Show this message and exit.  [optional]

Let’s pull down the VM sierraiso v1 from Registry:

$anka registry pull sierraiso --tag v1
Downloading files  [#-----------------------------------]    4%

Using anka registry pull without any --tag pulls the latest version of the VM.

Working with Pulled VMs

Once you have pulled a VM from the Registry, you can run commands directly inside the VM environment using anka run. Use anka run to enable common developer workflows.

REST API Interface to Registry

Rest API access to registry is available through the Controller REST APIs. You can execute the following operations.

To list all VM templates from the registry

url= "/api/v1/registry/vm"
method="GET"
body=none
Returns: Operation result, List of registry VM UUIDs and names

To show information on a specific VM template from the registry

url= "/api/v1/registry/vm?id={vm_id}"
method="GET"
body=none
Returns: Operation result, VM UUID, name and tag list

To delete a specific VM template and all associated tags from the registry

url= "/api/v1/registry/vm?id={vm_id}"
method="DELETE"
body=none
Returns: Operation result

To distribute a specific VM template to all build nodes

url= "/api/v1/registry/distribute"
method="POST"
body="VM Uuid,  tag, version" 
Example Body: {"template_id":"226d946b-2467-11e7-84b7-a860b60fd826", “tag”=”v1”}
Returns: Operation result, request id

To get distribution status

url= "/api/v1/registry/distribute?id={request_id}"
method="GET"
body=none 
Returns: Operation result, map of node id -> (distribution status, template id, tag, version, time)