Skip to content

Latest commit

 

History

History
206 lines (148 loc) · 7.36 KB

README.md

File metadata and controls

206 lines (148 loc) · 7.36 KB
Raw

Packer Plugin for Anka

This is a Packer Plugin for building images that work with Veertu's Anka macOS Virtualization tool.

Compatibility

Packer Version Anka Packer Plugin Version
below 1.7.0 < 1.8.0
1.7.0 and above >= 2.0.0
>= 1.11.0 >= v4.0.0
Packer Plugin Version Anka CLI Version
2.x 2.x
>= 3.x >= 3.0.0

Installing with packer init

  1. Add a packer block to your .pkr.hcl like this:

    packer {
  required_plugins {
    veertu-anka = {
      version = "= v4.0.0"
      source = "github.com/veertuinc/veertu-anka"
    }
  }
}

  2. Then run packer init {HCL file name}

  3. Run your packer build command with your hcl template

Installing from Binary

  1. Install Packer v1.8 or newer.
  2. Install Veertu Anka.
  3. Download the latest release for your host environment.
  4. Unzip the plugin binaries to a location where Packer will detect them at run-time, such as any of the following:
    • The directory where the packer binary is.
    • The ~/.config/packer/plugins directory.
    • The current working directory.
  5. Rename the binary file to packer-plugin-veertu-anka.
  6. Run your packer build command with your hcl template.

Documentation

Builders Post Processors
[ veertu-anka-vm-create ] [ veertu-anka-registry-push ]
[ veertu-anka-vm-clone ]

Usage

Currently file provisioners do not support ~ or $HOME in the destination paths. Please use absolute or relative paths.

The most basic pkr.hcl file you can build from is:

source "veertu-anka-vm-create" "anka-packer-base-macos" {
  installer = "/Applications/Install macOS Big Sur.app/"
  vm_name = "anka-packer-base-macos"
}

build {
  sources = [
    "source.veertu-anka-vm-create.anka-packer-base-macos"
  ]

  post-processor "veertu-anka-registry-push" {
    tag = "veertu-registry-push-test"
  }
}

This will create a "base" VM template using the .app or .ipsw you specified in installer = "/Applications/Install macOS Big Sur.app/" with the name anka-packer-base-macos. Once the VM has been successfully created, it will push that VM to your default registry with the tag veertu-registry-push-test.

If you don't specify vm_name, we will obtain it from the installer and create a name like anka-packer-base-12.6-21G115.

However, hw_uuid, port_forwarding_rules, and several other configuration settings are ignored for the created "base" vm. We recommend using the veertu-anka-vm-clone builder to modify these values.

You can also skip the creation of the base VM template and use an existing VM template:

source "veertu-anka-vm-clone" "anka-packer-from-source" { 
  vm_name = "anka-packer-from-source"
  source_vm_name = "anka-packer-base-macos"
  always_fetch = true
}

build {
  sources = [
    "source.veertu-anka-vm-clone.anka-packer-from-source",
  ]
}

This will check to see if the VM template/tag exists locally, and if not, pull it from the registry:

❯ PKR_VAR_source_vm_tag="v1" PACKER_LOG=1 packer build -var 'source_vm_name=anka-packer-base-macos' examples/clone-existing-with-port-forwarding-rules.pkr.hcl
. . .
2021/04/07 14:11:52 packer-plugin-veertu-anka plugin: 2021/04/07 14:11:52 Searching for anka-packer-base-macos locally...
2021/04/07 14:11:52 packer-plugin-veertu-anka plugin: 2021/04/07 14:11:52 Executing anka --machine-readable show anka-packer-base-macos
2021/04/07 14:11:53 packer-plugin-veertu-anka plugin: 2021/04/07 14:11:53 Could not find anka-packer-base-macos locally, looking in anka registry...
2021/04/07 14:11:53 packer-plugin-veertu-anka plugin: 2021/04/07 14:11:53 Executing anka --machine-readable registry pull --tag v1 anka-packer-base-macos

Within your .pkrvars.hcl files, you can utilize variable blocks and then assign them values using the command line packer build -var 'foo=bar' or as environment variables PKR_VAR_foo=bar https://www.packer.io/docs/templates/hcl_templates/variables#assigning-values-to-build-variables

This will clone anka-packer-base-macos to a new VM and, if there are set configurations, make them.

Check out the examples directory to see how port-forwarding and other options are used.

Build Variables

Packer allows for the exposure of build variables which connects information related to the artifact that was built. Those variables can then be accessed by post-processors and provisioners.

The variables we expose are:

  • VMName: name of the artifact vm
  • OSVersion: OS version from which the artifact was created
    • eg. 10.15.7
  • DarwinVersion: Darwin version that is compatible with the current OS version
    • eg. 19.6.0
locals {
  source_vm_name = "anka-packer-base-11.2-16.4.06"
}

source "veertu-anka-vm-clone" "anka-macos-from-source" {
  "source_vm_name": "${local.source_vm_name}",
  "vm_name": "anka-macos-from-source"
}

build {
  sources = [
    "source.veertu-anka-vm-clone.anka-macos-from-source"
  ]

  provisioner "shell" {
    inline = [
      "echo vm_name is ${build.VMName}",
      "echo os_version is ${build.OSVersion}",
      "echo darwin_version is ${build.DarwinVersion}"
    ]
  }
}

Development

You will need a recent golang installed and setup. See go.mod for which version is expected.

We use gomock to quickly and reliably mock our interfaces for testing. This allows us to easily test when we expect logic to be called without having to rewrite golang standard library functions with custom mock logic. To generate one of these mocked interfaces, installed the mockgen binary by following the link provided and then run the make go.test.

  • You must install packer-sdc to generate docs and HCL2spec.

Run the plugin locally

go run -ldflags="-X main.version=$(cat VERSION) -X main.commit=$(git rev-parse HEAD)" main.go

Building, Linting, and Testing

make all && make install

When testing with an example HCL:

ANKA_LOG_LEVEL=debug ANKA_DELETE_LOGS=0 PACKER_LOG=1 packer build examples/create-from-installer.pkr.hcl

To test the post processor you will need an active vpn connection that can reach an anka registry. You can setup an anka registry by either adding the registry locally with:

anka registry add <registry_name> <registry_url>

-or-

You can setup the create-from-installer-with-post-processing.pkr.hcl with the correct registry values and update the make target anka.test to use that .pkr.hcl file and run:

make create-test