--- description: | HyperOne Packer builder creates new images on the HyperOne platform. The builder takes a source image, runs any provisioning necessary on the image after launching it, then creates a reusable image. page_title: HyperOne - Builders sidebar_title: HyperOne --- # HyperOne Builder Type: `hyperone` Artifact BuilderId: `hyperone.builder` The `hyperone` Packer builder is able to create new images on the [HyperOne platform](http://www.hyperone.com/). The builder takes a source image, runs any provisioning necessary on the image after launching it, then creates a reusable image. The builder does _not_ manage images. Once it creates an image, it is up to you to use it or delete it. ## Authentication HyperOne supports several authentication methods, which are all supported by this builder. ### User session If using user session, set the `token` field to your authentication token. The `project` field is required when using this method. ```json { "token": "YOUR TOKEN", "project": "YOUR_PROJECT" } ``` ### User session by SSH key If you've added an SSH key as a credential to your user account and the private key is added to the ssh-agent on your local machine, you can authenticate by setting just the platform login (your e-mail address): ```json { "token_login": "your.user@example.com" } ``` ### h1 CLI If you're using [h1-cli](https://github.com/hyperonecom/h1-cli) on your local machine, HyperOne builder can use your credentials saved in a config file. All you have to do is login within the tool: ```shell-session $ h1 login --username your.user@example.com ``` You don't have to set `token` or `project` fields at all using this method. ### Service account Using `h1`, you can create a new token associated with chosen project. ```shell-session $ h1 project token add --name packer-builder --project PROJECT_ID ``` Set the `token` field to the generated token or save it in the `HYPERONE_TOKEN` environment variable. You don't have to set the `project` option using this method. ```json { "token": "YOUR TOKEN" } ``` ## Configuration Reference There are many configuration options available for the builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a [communicator](/docs/templates/legacy_json_templates/communicator) can be configured for this builder. ### Required: - `disk_size` (float) - Size of the created disk, in GiB. - `project` (string) - The id or name of the project. This field is required only if using session tokens. It should be skipped when using service account authentication. - `source_image` (string) - ID or name of the image to launch server from. - `token` (string) - The authentication token used to access your account. This can be either a session token or a service account token. If not defined, the builder will attempt to find it in the following order: - In `HYPERONE_TOKEN` environment variable. - In `~/.h1-cli/conf.json` config file used by [h1-cli](https://github.com/hyperonecom/h1-cli). - By using SSH authentication if `token_login` variable has been set. - `vm_type` (string) - ID or name of the type this server should be created with. ### Optional: - `api_url` (string) - Custom API endpoint URL, compatible with HyperOne. It can also be specified via environment variable `HYPERONE_API_URL`. - `disk_name` (string) - The name of the created disk. - `disk_type` (string) - The type of the created disk. Defaults to `ssd`. - `image_description` (string) - The description of the resulting image. - `image_name` (string) - The name of the resulting image. Defaults to `packer-{{timestamp}}` (see [configuration templates](/docs/templates/legacy_json_templates/engine) for more info). - `image_service` (string) - The service of the resulting image. - `image_tags` (map of key/value strings) - Key/value pair tags to add to the created image. - `network` (string) - The ID of the network to attach to the created server. - `private_ip` (string) - The ID of the private IP within chosen `network` that should be assigned to the created server. - `public_ip` (string) - The ID of the public IP that should be assigned to the created server. If `network` is chosen, the public IP will be associated with server's private IP. - `public_netadp_service` (string) - Custom service of public network adapter. Can be useful when using custom `api_url`. Defaults to `public`. - `ssh_keys` (array of strings) - List of SSH keys by name or id to be added to the server on launch. - `state_timeout` (string) - Timeout for waiting on the API to complete a request. Defaults to 5m. - `token_login` (string) - Login (an e-mail) on HyperOne platform. Set this if you want to fetch the token by SSH authentication. - `user_data` (string) - User data to launch with the server. Packer will not automatically wait for a user script to finish before shutting down the instance, this must be handled in a provisioner. - `vm_name` (string) - The name of the created server. - `vm_tags` (map of key/value strings) - Key/value pair tags to add to the created server. ## Chroot disk ### Required: - `chroot_disk` (bool) - Set to `true` to enable chroot disk build. - `pre_mount_commands` (array of strings) - A series of commands to execute before mounting the chroot. This should include any partitioning and filesystem creation commands. The path to the device is provided by `{{.Device}}`. ### Optional: - `chroot_command_wrapper` (string) - How to run shell commands. This defaults to `{{.Command}}`. This may be useful to set if you want to set environment variables or run commands with `sudo`. - `chroot_copy_files` (array of strings) - Paths to files on the running VM that will be copied into the chroot environment before provisioning. Defaults to `/etc/resolv.conf` so that DNS lookups work. - `chroot_device` (string) - The path of chroot device. Defaults an attempt is made to identify it based on the attach location. - `chroot_disk_size` (float) - The size of the chroot disk in GiB. Defaults to `disk_size`. - `chroot_disk_type` (string) - The type of the chroot disk. Defaults to `disk_type`. - `chroot_mount_path` (string) - The path on which the device will be mounted. - `chroot_mounts` (array of strings) - A list of devices to mount into the chroot environment. This is a list of 3-element tuples, in order: - The filesystem type. If this is "bind", then Packer will properly bind the filesystem to another mount point. - The source device. - The mount directory. - `mount_options` (array of tuples) - Options to supply the `mount` command when mounting devices. Each option will be prefixed with `-o` and supplied to the `mount` command. - `mount_partition` (string) - The partition number containing the / partition. By default this is the first partition of the volume (for example, sdb1). - `post_mount_commands` (array of strings) - As `pre_mount_commands`, but the commands are executed after mounting the root device and before the extra mount and copy steps. The device and mount path are provided by `{{.Device}}` and `{{.MountPath}}`. ## Basic Example Here is a basic example. It is completely valid as soon as you enter your own token. ```json { "type": "hyperone", "token": "YOUR_AUTH_TOKEN", "source_image": "ubuntu-18.04", "vm_type": "a1.nano", "disk_size": 10 } ``` ## Chroot Example ```json { "type": "hyperone", "token": "YOUR_AUTH_TOKEN", "source_image": "ubuntu-18.04", "vm_type": "a1.nano", "disk_size": 10, "chroot_disk": true, "pre_mount_commands": [ "apt-get update", "apt-get install debootstrap", "debootstrap --arch amd64 bionic {{.MountPath}}" ] } ``` ## HCL Example ```hcl variable "token" { type = string } variable "project" { type = string } source "hyperone" "new-syntax" { token = var.token project = var.project source_image = "debian" disk_size = 10 vm_type = "a1.nano" image_name = "packerbats-hcl-{{timestamp}}" image_tags = { key="value" } } build { sources = [ "source.hyperone.new-syntax" ] provisioner "shell" { inline = [ "apt-get update", "apt-get upgrade -y" ] } } ```