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:

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

  VMs registry

Options:
  --remote TEXT         specific registry address  [optional]
  --registry-path TEXT  pass a url to use for registry  [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             show VM description
  list                 list all available vms in default repository
  list-repos           list all the repositories
  pull                 pull certain VM
  push                 push local VM version to default repository
  set                  set default repository
  

Adding a new Registry

Configure the destination registry with anka registry add command:

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:

$ anka registry list-repos
newreg

+--------+----------------+
| host   | XX.XXX.XXX.XXX |
+--------+----------------+
| scheme | http           |
+--------+----------------+


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 multiple registries exist, 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

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

  push image

Options:
  --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 sierraiso v2
Uploading files  [#######################-------------]   65%  0d 00:00:14

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

$anka registry describe sierraiso
+------+--------------------------------------+
| id   | ea0a1270-4882-11e7-a9f8-38c98630393f |
+------+--------------------------------------+
| name | sierraiso                            |
+------+--------------------------------------+

versions

+----------+-------+
|   number | tag   |
+==========+=======+
|        0 | v1    |
+----------+-------+
|        1 | v2    |
+----------+-------+

Pulling VMs from Registry

Once you have pushed VMs to Registry, you will be able to pull different versions of them using other hosts setup with Anka. anka provides the pull command for moving VMs from the registry. Again, providing a --help as an argument will print the available usage:

$ anka registry pull --help
Usage: anka registry pull [OPTIONS] VM_ID

  pull image

Options:
  --tag TEXT         [optional]
  --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.

Deleting VMs from Registry

Registry backend comes up with it’s own utility called anka-regctl. Inside the registry docker container, type anka-regctl to see a list of operations available. For example, in order to delete VMs from the registry, execute the following command:

Connect to the registry docker container

docker exec -it <container_id>  bash

Then execute:

anka-regctl delete <vm_id>