Working with the Registry and API
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, use anka registry command to work with the registry.
Store your build and test VM templates in the registry.
Then, you can pull them, modify them and push them again with a different tag to the Registry. This way you can maintain versions. Pull specific VM template and tag to a different machine running Anka package.
Registry operations are available through Anka Client command line and through Registry REST APIs.
Working with registry using Anka CLI
View all of the available registry commands by running anka registry --help.
> sudo anka registry --help
Usage: anka registry [OPTIONS] COMMAND [ARGS]...
Configure and control the Anka Cloud Registry
Options:
-r, --remote TEXT Set the registry name (instead of 'default')
-a, --registry-path TEXT Set the registry URL (instead of 'default')
-c, -i, --cert, --pem PATH Path to your node certificate (if certificate authentication is enabled)
-k, --key PATH Path to your node certificate key if the client/node certificate doesn't contain one
--cacert, --root-cert PATH Path to a CA Root certificate
--insecure Skip TLS verification
--help Display usage information
Commands:
add Add a registry
check-download-size Return the size of the template and tag
delete Remove the registry from your configuration
describe Show a VM template description and tags
list List VMs in registry
list-repos List registries you have configured
pull Pull the specified VM template (and latest...
push Push a VM template (and tag) to the Cloud...
set Set default registry
Add registry to a Node/machine running Anka
anka registry add <givesomename> <registryURLwithport>
You can add/define multiple registries to a node. The last one added is treated as current. To change current use the set command.
Set Current registry
anka registry set <previouslydefiniedname>
Push VM to the Registry
anka registry push -d <description> -t <tag> {vmNameOrUUID}
Pull VM from the Registry
anka registry pull -t <tag> {vmNameOrUUID}
Pull VM from the Registry with Shrink
anka registry pull -s -t <tag> {vmNameOrUUID}
For example, let’s say you have V1, V2 tags in the Registry for a VM. You pull V2. Then, you pull V1 with -s flag. It will optimize the local disk space usage by deleting all V2 related tag/version files.
Push independent VM as new tag of existing VM in Registry
anka registry push NEW_VM -v EXISTING_VM_IN_REGISTRY -t NEW_TAG
For example, let’s say you have a VM1, with latest tag t2. Now, you want to push a completely independent VM2 as the next tag to VM1. You will use anka registry push VM2 -v VM1 -t NEW_TAG.
List VMs in the Registry
anka registry list
REST API
Status
❯ curl -s http://anka.registry:8089/registry/status
{"status":"OK","body":{"status":"Running","version":"1.13.0-24e848a5"},"message":""}
List VMS
Note
This is a new API introduced in version 1.7.0
Old path /registry/vm still works for backward compatibility.
Description: List all VMs stored in the Registry.
Path: /registry/v2/vm
Method: GET
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Return a specific Template. Passing this parameter will show more information about the Template’s tags |
Returns:
- Status: Operation Result (OK|FAIL)
- Body: List of VM objects. If id supplied, also returns list of versions.
- message: Error message in case of an error
Template format
- name: Template’s name
- id: Template’s id
- size: Total size of all Template’s files on the registry in bytes
- versions: Array of Version objects.
Version format
- tag: The version’s tag
- number: Serial number of the version
- description: The version’s description
- images: List of image file names
- state_files: List of state file names (suspend images)
- config_file: Name of the version’s VM config file
- nvram: Name of the VM nvram file
- size: Total size of all version’s files on registry in bytes.
CURL Example
# List example
curl -s http://anka.registry:8089/registry/v2/vm | jq {
"status": "OK",
"body": [
{
"id": "c12ccfa5-8757-411e-9505-128190e9854e",
"name": "11.6.0",
"size": 21024776192
}
],
"message": ""
}
# Get Single Template
curl -s "http://anka.registry:8089/registry/v2/vm?id=c12ccfa5-8757-411e-9505-128190e9854e" | jq
{
"status": "OK",
"body": {
"id": "c12ccfa5-8757-411e-9505-128190e9854e",
"name": "11.6.0",
"versions": [
{
"number": 0,
"tag": "vanilla",
"config_file": "c12ccfa5-8757-411e-9505-128190e9854e.yaml",
"nvram": "nvram",
"images": [
"6e45c8998fab41d9bbf4a6a6975efda0.ank"
],
"state_files": null,
"description": "",
"state_file": "",
"size": 18645143552
},
{
"number": 1,
"tag": "vanilla+port-forward-22",
"config_file": "c12ccfa5-8757-411e-9505-128190e9854e.yaml",
"nvram": "nvram",
"images": [
"6e45c8998fab41d9bbf4a6a6975efda0.ank"
],
"state_files": null,
"description": "",
"state_file": "",
"size": 18645143552
},
{
"number": 2,
"tag": "vanilla+port-forward-22+brew-git",
"config_file": "c12ccfa5-8757-411e-9505-128190e9854e.yaml",
"nvram": "nvram",
"images": [
"732787cd099d47e2bcd429f93ba57613.ank",
"6e45c8998fab41d9bbf4a6a6975efda0.ank"
],
"state_files": null,
"description": "",
"state_file": "",
"size": 21024776192
}
],
"size": 21024776192
},
"message": ""
}
Delete VM
Description: Delete a specific VM and all associated tags
Path: /registry/vm
Method: DELETE
Required Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| id | string | The Template’s id. |
Returns:
- Status: Operation Result (OK|FAIL)
- message: Error message in case of an error
CURL Example
curl -X DELETE "http://anka.registry.net:8089/registry/vm?id=00510971-5c37-4a60-a9c6-ea185397d9b4"
{
"status":"OK",
"body": null,
"message":""
}
Get VM Configuration
Description: Show vm configuration file for a specific version or tag (or latest if none specified) of a VM template
Path: /registry/vm/info
Method: GET
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Return the VM with that ID. |
Optional Query Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
| tag | string | The specific Tag to get info for | Latest |
| version | int | The number of the version to get info for, 0 indexed | Latest |
Returns:
- Status: Operation Result (OK|FAIL)
- Body: VM configuration object
- message: Error message in case of an error
Object format
- name: Name of the Template
- ram: Amount of virtual RAM the VM has
- hard_drives: Array of hard drives
- usb: USB info
- uuid: Id of the vm
- network_cards: A list of network cards, with port forwarding rules
- firmware: VM’s firmware
- state_file: Name of state file (suspend image)
- nvram: Path of nvram file
- version: VM configuration version (internally used)
- cpu: Number of virtual CPU cores
- display: VM’s display
CURL Example
curl "http://anka.registry.net:8089/registry/vm/info?id=2fa0f10e-e91e-4665-8d42-00a39b9707de"
{
"message" : "",
"status" : "OK",
"body" : {
"nvram" : true,
"state_file" : "668e52df4d454f0fbc14cc69a15c5006.ank",
"display" : {
"frame_buffer" : {
"height" : 768,
"pci_slot" : 29,
"vnc_ip" : "0.0.0.0",
"width" : 1024,
"password" : "admin"
}
},
"version" : 1,
"usb" : {
"pci_slot" : 7,
"host" : 0,
"tablet" : 1
},
"network_cards" : [
{
"mode" : "shared",
"pci_slot" : 28,
"mac_address" : "56:45:45:3c:db:02",
"port_forwarding_rules" : [
{
"host_port" : 0,
"protocol" : "tcp",
"rule_name" : "ssh1",
"guest_port" : 22,
"host_ip" : "0"
}
]
}
],
"hard_drives" : [
{
"pci_slot" : 4,
"controller" : "ablk",
"file" : "239bb374545141ceb481d495ec01683e.ank"
}
],
"cpu" : {
"cores" : 2
},
"name" : "appium-base",
"ram" : "2G",
"uuid" : "2fa0f10e-e91e-4665-8d42-00a39b9707de",
"firmware" : {
"type" : "uefi"
}
}
}
Revert
Reverting is a potentially dangerous operation. It will revert all tags which came AFTER the one you’re targeting. We recommend a multi-template-single-tag approach instead to avoid this.
Description: Revert a VM to a certain Tag or version number. Delete the latest version if none is specified.
Path: /registry/revert
Method: DELETE
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | The Template id. |
Optional Data Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
| tag | string | The Tag to revert to. Newer versions will also be deleted | Latest |
| version | int | The number of the version to revert to, 0 indexed | Latest |
Returns:
- Status: Operation Result (OK|FAIL)
- message: Error message in case of an error
CURL Example
# Delete latest version
curl -X DELETE "http://anka.registry.net:8089/registry/revert?id=00510971-5c37-4a60-a9c6-ea185397d9b4"
{
"body" : null,
"message" : "",
"status" : "OK"
}
# Revert to the first version of the template
curl -X DELETE "http://anka.registry.net:8089/registry/revert?id=a3cc47f0-3a73-11e9-b515-c4b301c47c6b&number=0"
{
"status" : "OK",
"body" : null,
"message" : ""
}
# Revert to a specific Tag
❯ curl -X DELETE "http://anka.registry:8089/registry/revert?id=aff190a4-9871-4fb7-b909-73742f0fbdbe" -d '{"tag": "vanilla+port-forward-22+brew-git"}'
{"status":"OK","body":null,"message":""}
Set Template Arch
Description: Set the template’s arch manually.
Path: /registry/vm/arch
Method: PUT
Required Data Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
| id | string | The Template id. | - |
| arch | string | The architecture (“arm64” or “amd64”) | - |
Returns:
- Status: Operation Result (OK|FAIL)
- message: Error message in case of an error
CURL Example
❯ curl -s http://10.8.1.10:8089/registry/vm\?id\=0e1660cb-632f-4748-8a0d-ce82ae6bcd25 | jq
{
"status": "OK",
"body": {
"id": "0e1660cb-632f-4748-8a0d-ce82ae6bcd25",
"name": "12.1.0",
"versions": [
{
"number": 0,
"tag": "vanilla+addons",
"config_file": "0e1660cb-632f-4748-8a0d-ce82ae6bcd25.yaml",
"nvram": "nvram",
"images": [
"7180b240cfc8434299212b8fc06c3f04.ank"
],
"state_files": [],
"description": "",
"state_file": "",
"size": 19425398784,
"arch": ""
}
],
"size": 19425398784,
"arch": "amd64"
},
"message": ""
}
❯ curl -X PUT http://10.8.1.10:8089/registry/vm/arch -d '{"id": "0e1660cb-632f-4748-8a0d-ce82ae6bcd25", "arch": "arm64"}'
{"status":"OK","body":null,"message":""}
❯ curl -s http://10.8.1.10:8089/registry/vm\?id\=0e1660cb-632f-4748-8a0d-ce82ae6bcd25 | jq
{
"status": "OK",
"body": {
"id": "0e1660cb-632f-4748-8a0d-ce82ae6bcd25",
"name": "12.1.0",
"versions": [
{
"number": 0,
"tag": "vanilla+addons",
"config_file": "0e1660cb-632f-4748-8a0d-ce82ae6bcd25.yaml",
"nvram": "nvram",
"images": [
"7180b240cfc8434299212b8fc06c3f04.ank"
],
"state_files": [],
"description": "",
"state_file": "",
"size": 19425398784,
"arch": ""
}
],
"size": 19425398784,
"arch": "arm64"
},
"message": ""
}