|
| 1 | +# UpCloud Packer builder |
| 2 | + |
| 3 | +[](https://travis-ci.org/UpCloudLtd/upcloud-packer) |
| 4 | + |
| 5 | +This is a builder plugin for Packer which can be used to generate storage templates on UpCloud. It utilises the [UpCloud Go API](https://github.com/UpCloudLtd/upcloud-go-api) to interface with the UpCloud API. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +### Pre-built binaries |
| 10 | + |
| 11 | +You can download the pre-built binaries of the plugin from the [GitHub releases page](https://github.com/UpCloudLtd/upcloud-packer/releases). Just download the archive for your operating system and architecture, unpack it, and place the binary in the appropriate location, e.g. on Linux `~/.packer.d/plugins`. Make sure the file is executable, then install [Packer](https://www.packer.io/). |
| 12 | + |
| 13 | +### Installing from source |
| 14 | + |
| 15 | +#### Prerequisites |
| 16 | + |
| 17 | +You will need to have the [Go](https://golang.org/) programming language and the [Packer](https://www.packer.io/) itself installed. You can find instructions to install each of the prerequisites at their documentation. |
| 18 | + |
| 19 | +#### Building and installing |
| 20 | + |
| 21 | +Run the following commands to download and install the plugin from the source. |
| 22 | + |
| 23 | +```sh |
| 24 | +git clone https://github.com/UpCloudLtd/upcloud-packer |
| 25 | +cd upcloud-packer |
| 26 | +go build |
| 27 | +cp upcloud-packer ~/.packer.d/plugins/packer-builder-upcloud |
| 28 | +``` |
| 29 | + |
| 30 | +## Usage |
| 31 | + |
| 32 | +The builder will automatically generate a temporary SSH key pair for the `root` user which is used for provisioning. This means that if you do not provision a user during the process you will not be able to gain access to your server. |
| 33 | + |
| 34 | +If you want to login to a server deployed with the template, you might want to include an SSH key to your `root` user by replacing the `<ssh-rsa_key>` in the below example with your public key. |
| 35 | + |
| 36 | +Here is a sample template, which you can also find in the `examples/` directory. It reads your UpCloud API credentials from the environment variables and creates an Ubuntu 20.04 LTS server in the `nl-ams1` region. |
| 37 | + |
| 38 | +```json |
| 39 | +{ |
| 40 | + "variables": { |
| 41 | + "username": "{{ env `UPCLOUD_API_USER` }}", |
| 42 | + "password": "{{ env `UPCLOUD_API_PASSWORD` }}" |
| 43 | + }, |
| 44 | + "builders": [ |
| 45 | + { |
| 46 | + "type": "upcloud", |
| 47 | + "username": "{{ user `username` }}", |
| 48 | + "password": "{{ user `password` }}", |
| 49 | + "zone": "nl-ams1", |
| 50 | + "storage_uuid": "01000000-0000-4000-8000-000030200200" |
| 51 | + } |
| 52 | + ], |
| 53 | + "provisioners": [ |
| 54 | + { |
| 55 | + "type": "shell", |
| 56 | + "inline": [ |
| 57 | + "apt-get update", |
| 58 | + "apt-get upgrade -y", |
| 59 | + "echo '<ssh-rsa_key>' | tee /root/.ssh/authorized_keys" |
| 60 | + ] |
| 61 | + } |
| 62 | + ] |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +You will need to provide a username and a password with the access rights to the API functions to authenticate. We recommend setting up a subaccount with only the API privileges for security purposes. You can do this at your [UpCloud Control Panel](https://my.upcloud.com/account) in the My Account menu under the User Accounts tab. |
| 67 | + |
| 68 | +Enter the API user credentials in your terminal with the following commands. Replace the `<API_username>` and `<API_password>` with your user details. |
| 69 | + |
| 70 | +```sh |
| 71 | +export UPCLOUD_API_USER=<API_username> |
| 72 | +export UPCLOUD_API_PASSWORD=<API_password> |
| 73 | +``` |
| 74 | +Then run Packer using the example template with the command underneath. |
| 75 | +``` |
| 76 | +packer build examples/basic_example.json |
| 77 | +``` |
| 78 | +If everything goes according to plan, you should see something like the example output below. |
| 79 | + |
| 80 | +```sh |
| 81 | +upcloud: output will be in this color. |
| 82 | + |
| 83 | +==> upcloud: Creating temporary ssh key... |
| 84 | +==> upcloud: Getting storage... |
| 85 | +==> upcloud: Creating server based on storage "Ubuntu Server 20.04 LTS (Focal Fossa)"... |
| 86 | +==> upcloud: Server "packer-custom-image-20210206-213858" created and in 'started' state |
| 87 | +==> upcloud: Using ssh communicator to connect: 94.237.109.25 |
| 88 | +==> upcloud: Waiting for SSH to become available... |
| 89 | +==> upcloud: Connected to SSH! |
| 90 | +==> upcloud: Provisioning with shell script: /var/folders/pt/x34s6zq90qxb78q8fcwx6jx80000gn/T/packer-shell198358867 |
| 91 | + upcloud: Hit:1 http://archive.ubuntu.com/ubuntu focal InRelease |
| 92 | + upcloud: Get:2 http://archive.ubuntu.com/ubuntu focal-updates InRelease [114 kB] |
| 93 | +... |
| 94 | +==> upcloud: Stopping server "packer-custom-image-20210206-213858"... |
| 95 | +==> upcloud: Server "packer-custom-image-20210206-213858" is now in 'stopped' state |
| 96 | +==> upcloud: Creating storage template for server "packer-custom-image-20210206-213858"... |
| 97 | +==> upcloud: Storage template for server "packer-custom-image-20210206-213858" created |
| 98 | +==> upcloud: Stopping server "packer-custom-image-20210206-213858"... |
| 99 | +==> upcloud: Deleting server "packer-custom-image-20210206-213858"... |
| 100 | +Build 'upcloud' finished after 3 minutes 19 seconds. |
| 101 | +``` |
| 102 | + |
| 103 | +## Configuration reference |
| 104 | + |
| 105 | +This section describes the available configuration options for the builder. Please note that the purpose of the builder is to create a storage template that can be used as a source for deploying new servers, therefore the temporary server used for building the template is not configurable. |
| 106 | + |
| 107 | +### Required values |
| 108 | + |
| 109 | +* `username` (string) The username to use when interfacing with the UpCloud API. |
| 110 | +* `password` (string) The password to use when interfacing with the UpCloud API. |
| 111 | +* `zone` (string) The zone in which the server and template should be created (e.g. `nl-ams1`). |
| 112 | +* `storage_uuid` (string) The UUID of the storage you want to use as a template when creating the server. |
| 113 | + |
| 114 | + |
| 115 | +### Optional values |
| 116 | + |
| 117 | +* `storage_name` (string) The name of the storage that will be used to find the first matching storage in the list of existing templates. Note that `storage_uuid` parameter has higher priority. You should use either `storage_uuid` or `storage_name` for not strict matching (e.g "ubuntu server 20.04"). |
| 118 | +* `storage_size` (int) The storage size in gigabytes. Defaults to `25`. Changing this value is useful if you aim to build a template for larger server configurations where the preconfigured server disk is larger than 25 GB. The operating system disk can also be later extended if needed. Note that Windows templates require large storage size, than default 25 Gb. |
| 119 | +* `state_timeout_duration` (string) The amount of time to wait for resource state changes. Defaults to `5m`. |
| 120 | +* `template_prefix` (string) The prefix to use for the generated template title. Defaults to an empty string, meaning the prefix will be the storage title. You can use this option to easily differentiate between different templates. |
| 121 | +* `clone_zones` ([]string) The array of extra zones (locations) where created templates should be cloned. Note that default `state_timeout_duration` is not enough for cloning, better to increase a value depending on storage size. |
| 122 | +* `ssh_private_key_path` (string) Path to SSH Private Key that will be used for provisioning and stored in the template. |
| 123 | +* `ssh_public_key_path` (string) Path to SSH Public Key that will be used for provisioning. |
| 124 | +* `network_interfaces` (array) The array of network interfaces to request during the creation of the server for building the packer image. Example: |
| 125 | + |
| 126 | +```json |
| 127 | + ... |
| 128 | + "network_interfaces": [ |
| 129 | + { |
| 130 | + "type": "public", |
| 131 | + "ip_addresses": [ |
| 132 | + { |
| 133 | + "family": "IPv4" |
| 134 | + } |
| 135 | + ] |
| 136 | + }, |
| 137 | + { |
| 138 | + "type": "private", |
| 139 | + "network": "{{ private_network_uuid }}", |
| 140 | + "ip_addresses": [ |
| 141 | + { |
| 142 | + "family": "IPv4", |
| 143 | + "address": "192.168.3.123" |
| 144 | + } |
| 145 | + ] |
| 146 | + }, |
| 147 | + { |
| 148 | + "type": "utility", |
| 149 | + "ip_addresses": [ |
| 150 | + { |
| 151 | + "family": "IPv4" |
| 152 | + } |
| 153 | + ] |
| 154 | + } |
| 155 | + ] |
| 156 | + ... |
| 157 | +``` |
| 158 | + |
| 159 | + |
| 160 | +## License |
| 161 | + |
| 162 | +This project is distributed under the [MIT License](https://opensource.org/licenses/MIT), see LICENSE.txt for more information. |
0 commit comments