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:

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

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: You can also delete Vms from the registry through controller REST APIs.

Connect to the registry docker container

docker exec -it <container_id>  bash

Then execute:

anka-regctl delete <vm_id>