Anka VM Clone

Type: veertu-anka-vm-clone

The veertu-anka-vm-clone Packer builder is able to clone existing Anka VM Templates for use with the Anka Virtualization package and the Anka Build Cloud. The builder takes a source VM name, clones it, and then runs any provisioning necessary on the new VM Template before stopping or suspending it.

The builder does not manage templates. Once a template is created, it is up to you to use it or delete it.

Important Notes

In Anka 3.0 we now require a tagged source VM before cloning in order to share the underlying .ank image and optimize disk space. If your source VM is not tagged yet, we will assign one . We highly recommend pushing this VM Template/Tag to your registry so disk usage is optimized.

Interrupted or failed builds: With Packer's -on-error=ask, choosing [a] abort without cleanup leaves the cloned VM on disk for inspection (no anka delete). Choosing [c] clean up still removes it. See issue #94.

Configuration Reference

There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters.

Required Configuration

• source_vm_name (String) The VM to clone for provisioning, either stopped or suspended.

• type (String) Must be veertu-anka-vm-clone.

Optional Configuration

• vm_name (String) The name for the VM that is created.

  Generated using the source_vm_name if not provided: ({{ source_vm_name }}-{10RandomChars}).

  Ignored when skip_clone is true.

• vcpu_count (String) The number of vCPU cores, defaults to 2.

• ram_size (String) The size in "[0-9]+G" format, defaults to 2G.

• disk_size (String) The size in "[0-9]+G" format, defaults to 25G.

  We will automatically resize the internal disk for you by executing diskutil apfs resizeContainer inside of the VM. The plugin resolves the APFS container from diskutil info / or diskutil apfs list. IMPORTANT: Changing the clone's disk size will break the layer sharing with the root and double disk space usage. Change the disk size of the source template, then clone from it instead.

  Example: clone-existing-with-new-disk-size.pkr.hcl

• stop_vm (Boolean) Whether or not to stop the vm after it has been created, defaults to false.

• display_controller (string) The display controller to set (run anka modify VMNAME set display --help to see available options).

  Example: clone-existing-with-pg-display_controller.pkr.hcl

• always_fetch (Boolean) Always pull the source VM from the registry. Defaults to false.

  Example: pull-and-clone-existing.pkr.hcl

• skip_clone (Boolean) Do not clone source_vm_name. The builder starts, modifies, and provisions source_vm_name itself, then stops or suspends it. Defaults to false.

  The build changes source_vm_name in place. vm_name is ignored. The builder still pulls source_vm_name when it is not local, or when always_fetch is true. Resource and property settings (vcpu_count, ram_size, disk_size, port_forwarding_rules, vm_label, and others) apply to source_vm_name.

  The builder does not delete source_vm_name when the build fails or when you use packer build -force.

  The artifact name is source_vm_name. Thus the veertu-anka-registry-push post-processor pushes a new tag onto the same registry template, and you do not need remote_vm. Do not set delete_template_post_push = true unless you want the post-processor to delete source_vm_name after the push.

  Examples:

  • skip-clone-with-post-processing.pkr.hcl (Anka Registry tag)
  • skip-clone-with-thin-oci-tags.pkr.hcl (thin_oci_pulls + thin OCI push)

• boot_delay (String) The time to wait before running packer provisioner commands, defaults to 7s.

• wait_for_networking (Boolean) When enabled (the default), after boot_delay the builder runs anka run with a short shell loop that pings 8.8.8.8 until one reply succeeds (up to 120 attempts, one second apart) so basic guest connectivity is up before Packer continues—for example before shell provisioners that curl the internet. Set to false to skip that step. The check runs after boot_delay and does not change boot_delay itself. If your environment blocks ICMP to 8.8.8.8, set this to false and use another strategy (such as a longer boot_delay or a provisioner that retries).

• log_level (String) Set to debug to stream Anka debug lines to the Packer UI while commands run. You can also set ANKA_LOG_LEVEL=debug on the host. The plugin captures debug through ANKA_LOG_FILE on a FIFO. It does not pass --debug. Failed Anka commands print the captured debug even when log_level is unset.

• cacert (String) Path to a CA Root certificate.

• cert (String) Path to your node's client certificate to use for registry communication (if certificate authorization is enabled).

• insecure (Boolean) Skip TLS verification.

• key (String) Path to your node's client certificate key, if the cert certificate doesn't contain one, to use for registry communication (if certificate authorization is enabled).

  cacert, cert, insecure, and key are only for an Anka Registry. The build fails if you set them when remote is an OCI registry URL, because anka pull does not accept them.

• hw_uuid (String) (Anka 2 only) The Hardware UUID you wish to set (usually generated with uuidgen).

  Example: clone-existing-with-hwuuid.pkr.hcl

• port_forwarding_rules (Struct)

  If port forwarding rules are already set and you want to not have them fail the packer build, use packer build --force.

  Example: clone-existing-with-port-forwarding-rules.pkr.hcl

  • port_forwarding_guest_port (Int)
  • port_forwarding_host_port (Int)
  • port_forwarding_rule_name (String)

• host_directory_mounts (Struct) (Anka 3.9.0+, Apple Silicon only)

  Persists host directory mounts in the VM template using anka modify mount. Mounted folders appear under /Volumes/My Shared Files/ in the guest.

  Example: clone-existing-with-host-directory-mounts.pkr.hcl

  • host_path (String) Absolute path to the host directory to mount.
  • guest_folder_name (String) Optional guest folder name under /Volumes/My Shared Files/. Defaults to the host path's folder name.

• vm_label (Struct) Assign, rename, or delete Anka VM labels (anka modify … label). Repeat the block for each label operation.

  Example: clone-existing-with-labels.pkr.hcl

  • name (String) Label key (required except for delete_all).
  • value (String) Label value (set only).
  • delete (Boolean) Delete the label named by name.
  • set_name (String) Rename: current name is name, new name is set_name.
  • delete_all (Boolean) Delete all labels on the VM.

• registry-path (String) The registry URL (will use your default configuration if not set).

• remote (String) The registry name or URL (will use your default configuration if not set).

  This takes priority in Anka 3 and registry-path will be ignored.

  (Anka 3.9.0+) To pull the source VM as a full OCI tag, set remote to an OCI registry URL: an oci:// URL, or an http(s):// URL with /v2 in its path (for example oci://registry.example.com/v2/veertu/). The builder then runs anka pull instead of anka registry pull. A remote name from anka registry add always uses anka registry pull.

• thin_oci_pulls (Struct) (Anka 3.10.0+) Thin OCI tags to pull onto source_vm_name before the clone. Repeat the block for each thin tag. The builder pulls them in the order you write them, each with anka pull --thin, after the source VM is local and has a tag.

  The pulls change source_vm_name itself: the thin tags stay on the source VM after the build.

  Each pull is always thin. A full pull after thin tags removes those thin tags, so a full tag can only be the source VM itself (local, or pulled with remote and source_vm_tag).

  Examples:

  • clone-existing-with-thin-oci-tags.pkr.hcl (clone, then thin push)
  • skip-clone-with-thin-oci-tags.pkr.hcl (skip_clone, multiple thin pulls, then thin push)

  • url (String) Required. The OCI tag to pull: an oci:// URL, or an http(s):// URL with /v2 in its path (for example oci://ghcr.io/homebrew/core/cmake:4.3.4).
  • transform (List of String) sed expressions that change the file paths of this layer. Each one becomes an anka pull --transform option, in order (for example ["s|cmake/4.3.4|usr/local"]).
  thin_oci_pulls {
    url       = "oci://ghcr.io/homebrew/core/cmake:4.3.4"
    transform = ["s|cmake/4.3.4|usr/local"]
  }
  thin_oci_pulls {
    url       = "oci://ghcr.io/homebrew/core/ninja:1.13.2"
    transform = ["s|ninja/1.13.2|opt/homebrew"]
  }
  

  Anka does not relocate the @@HOMEBREW_PREFIX@@ / @@HOMEBREW_CELLAR@@ placeholders in Homebrew bottles. Only bottles that link no other Homebrew libraries (cellar :any_skip_relocation, for example cmake and ninja) run after a thin pull.

• source_vm_tag (String) Specify the tag of the VM we want to clone instead of using the default. Also the tag to target when pulling from the registry (defaults to latest tag).

  Example: pull-and-clone-existing.pkr.hcl

• update_addons (Boolean) (Anka 2 only) Update the vm addons. Defaults to false.

  Example: clone-existing-with-update_addons.pkr.hcl

• use_anka_cp (Boolean) Use built in anka cp command. Defaults to false.

  Example: clone-existing-with-use-anka-cp.pkr.hcl

Example

Here is an example that uses the file and shell provisioners.

Also see clone-existing.pkr.hcl and clone-existing-with-file-provisioner.pkr.hcl.

variable "source_vm_name" {
  type = string
  default = "anka-packer-base-macos"
}

variable "vm_name" {
  type = string
  default = "anka-packer-from-source"
}

source "veertu-anka-vm-clone" "clone" {
  vm_name = "${var.vm_name}"
  source_vm_name = "${var.source_vm_name}"
}

build {
  sources = [
    "source.veertu-anka-vm-clone.clone",
  ]
  provisioner "file" {
    destination = "/private/tmp/"
    source      = "./examples/ansible"
  }
  provisioner "shell" {
    inline = [
      "[[ ! -d /tmp/ansible ]] && exit 100",
      "touch /tmp/ansible/test1"
    ]
  }
  provisioner "file" {
    destination = "./"
    direction   = "download"
    source      = "/private/tmp/ansible/test1"
  }
  provisioner "shell-local" {
    inline = [
      "[[ ! -f ./test1 ]] && exit 200",
      "rm -f ./test1"
    ]
  }
}