diff --git a/.web-docs/README.md b/.web-docs/README.md new file mode 100644 index 0000000..fa4208c --- /dev/null +++ b/.web-docs/README.md @@ -0,0 +1,35 @@ +This is a [Packer](https://www.packer.io/) Plugin for building images that work with [Veertu's Anka macOS Virtualization tool](https://veertu.com/). + +### Installation + +To install this plugin, copy and paste this code into your Packer configuration, then run [`packer init`](https://www.packer.io/docs/commands/init). + +```hcl +packer { + required_plugins { + veertu-anka = { + version = "= 3.2.0" + source = "github.com/veertuinc/veertu-anka" + } + } +} +``` + +Alternatively, you can use `packer plugins install` to manage installation of this plugin. + +```sh +$ packer plugins install github.com/veertuinc/veertu-anka +``` + +### Components +~> For use with the post-processor, it's important to use `anka registry add` to [set your default registry on the machine building your templates/tags](https://docs.veertu.com/anka/apple/command-line-reference/#registry-add). + +#### Builders +- [veertu-anka-vm-clone](/packer/integrations/veertuinc/veertu-anka/latest/components/builder/clone) - Packer builder is able to clone existing Anka VM Templates for use with the [Anka Virtualization](https://veertu.com/technology/) package and the [Anka Build Cloud](https://veertu.com/anka-build/). 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. +- [veertu-anka-vm-create- ](/packer/integrations/veertuinc/veertu-anka/latest/components/builder/create) Packer builder is able to create new Anka VM Templates for use with the +[Anka Virtualization](https://veertu.com/technology/) package and the [Anka Build Cloud](https://veertu.com/anka-build/). The builder takes the path to macOS installer .app +and installs that macOS version inside of an Anka VM Template. + +#### Post-Processors +- [veertu-anka-registry-push](/packer/integrations/veertuinc/veertu-anka/latest/components/post-processor/veertu-anka-registry-push) Packer Post Processor is able to push your created Anka VM templates to +the [Anka Build Cloud Registry](https://veertu.com/anka-build/) through the [Anka Virtualization](https://veertu.com/technology/) package. diff --git a/.web-docs/components/builder/vm-clone/README.md b/.web-docs/components/builder/vm-clone/README.md new file mode 100644 index 0000000..1b2e685 --- /dev/null +++ b/.web-docs/components/builder/vm-clone/README.md @@ -0,0 +1,122 @@ +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](https://veertu.com/technology/) package and the [Anka Build Cloud](https://veertu.com/anka-build/). 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](https://docs.veertu.com/anka/apple/getting-started/creating-your-first-vm/#disk-optimization).** + +## 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}`). + +* `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 disk0s2 0` inside of the VM. + +* `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). + +* `always_fetch` (Boolean) Always pull the source VM from the registry. Defaults to false. + +* `boot_delay` (String) The time to wait before running packer provisioner commands, defaults to `7s`. + +* `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). + +* `hw_uuid` (String) (Anka 2 only) The Hardware UUID you wish to set (usually generated with `uuidgen`). + +* `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`. + + * `port_forwarding_guest_port` (Int) + * `port_forwarding_host_port` (Int) + * `port_forwarding_rule_name` (String) + +* `registry-path` (String) The registry URL (will use your default configuration if not set). + +* `remote` (String) The registry name (will use your default configuration if not set). + + > This takes priority in Anka 3 and `registry-path` will be ignored. + +* `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). + +* `update_addons` (Boolean) (Anka 2 only) Update the vm addons. Defaults to false. + +* `use_anka_cp` (Boolean) Use built in anka cp command. Defaults to false. + +## Example + +Here is an example that uses the file and shell provisioners. + +```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" + ] + } +} + +``` diff --git a/.web-docs/components/builder/vm-create/README.md b/.web-docs/components/builder/vm-create/README.md new file mode 100644 index 0000000..6fda7ff --- /dev/null +++ b/.web-docs/components/builder/vm-create/README.md @@ -0,0 +1,102 @@ +Type: `veertu-anka-vm-create` + +**Packer 3.x will no longer support Anka 2.x. You can still however use the Packer 2.x release for support.** + +The `veertu-anka-vm-create` Packer builder is able to create new Anka VM Templates for use with the +[Anka Virtualization](https://veertu.com/technology/) package and the [Anka Build Cloud](https://veertu.com/anka-build/). The builder takes the path to macOS installer .app +and installs that macOS version inside of an Anka VM Template. + +The builder does _not_ manage templates. Once a template is created, it is up +to you to use it or delete it. + +## Configuration Reference + +There are many configuration options available for the builder. They are +segmented below into two categories: required and optional parameters. + +### Required Configuration + +* `installer` (String) The path to a macOS installer. This process takes about 20 minutes. + - Starting in 3.1.2: This can also be set to 'latest' or a specific macOS version in order to have Anka attempt downloading the installer for you (`vm_name` will be set to `anka-packer-base-${installer}`). + +* `type` (String) Must be `veertu-anka-vm-create`. + +### Optional Configuration + +* `vm_name` (String) The name for the VM that is created. One is generated with installer data if not provided (`anka-packer-base-{{ installer.OSVersion }}-{{ installer.BundlerVersion }}`). + +* `vcpu_count` (String) The number of vCPU cores, defaults to `2`. + + > This change gears us up for Anka 3.0 release when cpu_count will be vcpu_count. For now this is still CPU and not vCPU. + +* `ram_size` (String) The size in "[0-9]+G" format, defaults to `4G`. + +* `disk_size` (String) The size in "[0-9]+G" format, defaults to `40G`. + + > We will automatically resize the internal disk for you by executing `diskutil apfs resizeContainer disk0s2 0` inside of the VM + +* `stop_vm` (Boolean) Whether or not to stop the vm after it has been created, defaults to false. + +* `use_anka_cp` (Boolean) Use built in anka cp command. You shouldn't need this option. Defaults to false. + +* `anka_password` (String) Sets the password for the vm. Can also be set with `ANKA_DEFAULT_PASSWD` env var. Defaults to `admin`. + +* `anka_user` (String) Sets the username for the vm. Can also be set with `ANKA_DEFAULT_USER` env var. Defaults to `anka`. + +* `boot_delay` (String) The time to wait before running packer provisioner commands, defaults to `7s`. + +* `log_level` (String) The log level for Anka. This currently only supports `debug` and is only useful for VM creation failures. + +* `hw_uuid` (String) (Anka 2 only) The Hardware UUID you wish to set (usually generated with `uuidgen`). + +* `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`. + + * `port_forwarding_guest_port` (Int) + * `port_forwarding_host_port` (Int) + * `port_forwarding_rule_name` (String) + +* `display_controller` (string) The display controller to set (run `anka modify VMNAME set display --help` to see available options). + +## Example + +Here is an example: + +```hcl + +variable "vm_name" { + type = string + default = "anka-packer-base-macos" +} + +variable "installer" { + type = string + default = "/Applications/Install macOS Big Sur.app/" +} + +variable "vcpu_count" { + type = string + default = "" +} + +source "veertu-anka-vm-create" "base" { + installer = "${var.installer}" + vm_name = "${var.vm_name}" + vcpu_count = "${var.vcpu_count}" +} + +build { + sources = [ + "source.veertu-anka-vm-create.base" + ] + + provisioner "shell" { + inline = [ + "echo hello world", + "echo llamas rock" + ] + } +} + +``` diff --git a/.web-docs/components/post-processor/anka-registry-push/README.md b/.web-docs/components/post-processor/anka-registry-push/README.md new file mode 100644 index 0000000..b9b2364 --- /dev/null +++ b/.web-docs/components/post-processor/anka-registry-push/README.md @@ -0,0 +1,95 @@ +Type: `veertu-anka-registry-push` + +The `veertu-anka-registry-push` Packer Post Processor is able to push your created Anka VM templates to the [Anka Build Cloud Registry](https://veertu.com/anka-build/) through the [Anka Virtualization](https://veertu.com/technology/) package. + +This post-processor is part of the [Veertu Anka plugin](https://github.com/veertuinc/packer-plugin-veertu-anka). To install this plugin using `packer init`, add the following Packer block to your hcl template: + +```hcl +packer { + required_plugins { + veertu-anka = { + version = "= 3.2.0" + source = "github.com/veertuinc/veertu-anka" + } + } +} +``` + +## Configuration Reference + +There are many configuration options available for the post-processor. They are +segmented below into two categories: required and optional parameters. + +### _**Required Configuration**_ + +* `type` (String) **Must be `veertu-anka-registry-push`; no other types** + +### _**Optional Configuration**_ + +* `cacert` (String) Path to a CA Root certificate. + +* `cert` (String) Path to your node certificate (if certificate authority is enabled). + +* `description` (String) The description of the tag. + +* `insecure` (Boolean) Skip TLS verification. + +* `key` (String) Path to your node certificate key if the client/node certificate doesn't contain one. + +* `local` (Boolean) Assign a tag to your local template and avoid pushing to the Registry. + +* `remote` (String) The registry URL or name to target for registry operation (will use your default configuration if not set). + +* `remote_vm` (String) The name of a registry template you want to push the local template onto. + +* `tag` (String) The name of the tag to push (will default as 'latest' if not set). + +* `force` (Boolean) Whether or not to forcefully push, regardless of a tag already existing + +## Other + +When using `packer build -force`, the post-processor will issue a [revert API call](https://docs.veertu.com/anka/anka-build-cloud/working-with-registry-and-api/#revert) to remove the existing tag before pushing the new. + +## Example + +Here is an example that uses the file and shell provisioners. + +```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" + ] + } + + post-processor "veertu-anka-registry-push" { + tag = "v2" + } +} + +``` diff --git a/Makefile b/Makefile index 87f83dd..282362e 100644 --- a/Makefile +++ b/Makefile @@ -114,9 +114,9 @@ go.hcl2spec: install-packer-sdc GOOS=$(OS_TYPE) go generate post-processor/ankaregistry/post-processor.go #generate: @ Generate -generate: install-packer-sdc - @go generate ./... - @rm -rf .docs - @packer-sdc renderdocs -src docs -partials docs-partials/ -dst .docs/ - @./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "" - @rm -r ".docs" \ No newline at end of file +generate: install-packer-sdc go.hcl2spec + @rm -rf .docs + @packer-sdc renderdocs -src docs -partials docs-partials/ -dst .docs/ + @./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "veertuinc" + @rm -r ".docs" +