Packer is easy to use automation solution for creating any type of machine images. It embraces modern configuration management by allowing automated software install and setup within Packer-built images. Helping to create private templates faster, we are excited to introduce the UpCloud Packer builder.

UpCloud Packer builder works as a plugin for Packer to simplify template configuration and make deploying custom cloud servers faster. In this guide, you will find the required steps to installing Packer builder for UpCloud on your own computer running Linux. Each of the software used here are also available for macOS and Windows with their own installation instructions by their developers.

Contents

Installing the prerequisites

Like with most installation instructions, the first step is to make sure you have the necessary tools to continue. In this case, you will need to have git client, curl, and unzip to follow along with the guide.

Verify that the aforementioned packages are installed with your system appropriate command such as one of the two examples below. If you wish to just go by the quickstart option, you can leave out the git tools.

sudo apt-get install git curl unzip
sudo yum install git curl unzip

Having the prerequisites fulfilled, you can get started with the installation.

Option 1. Quickstart

Packer is available packaged as a zip file. To install the precompiled binary, you will need to download the appropriate package for your OS. For example, using the following command to download the 64-bit Linux version of Packer.

curl -O https://releases.hashicorp.com/packer/1.1.3/packer_1.1.3_linux_amd64.zip

You might need to check the version number on the Packer website and update the URL.

When the download finishes, extract Packer into an appropriate directory that is included in your $PATH such as /usr/local/bin.

sudo unzip packer_1.1.3_linux_amd64.zip -d /usr/local/bin

Then verify that Packer is working, for example, with the command below.

packer --version
1.1.3

Next, download the pre-built binary of the plugin available on the GitHub releases page.

Download the archive appropriate for your operating system, for example on Linux with the command underneath.

curl -LO https://github.com/UpCloudLtd/upcloud-packer/releases/download/3.0.0/packer-builder-upcloud-3.0.0-linux-amd64.zip

Create a directory for the Packer plugins and unpack the binary into the new folder.

mkdir -p ~/.packer.d/plugins
unzip packer-builder-upcloud-3.0.0-linux-amd64.zip -d ~/.packer.d/plugins

Then make sure the file is executable.

chmod +x ~/.packer.d/plugins/packer-builder-upcloud

The two binaries are all that you really need to build custom templates on UpCloud. Jump ahead to the last section in this tutorial to get started with building templates.

Option 2. Installing from the source

If you want to try out the latest version and build the binaries yourself, follow along with the instructions below. This part of the guide will show you how to install Go, Glide, Packer itself, and of course the UpCloud plugin for Packer.

Installing Go

Go is an open source programming language that was developed to makes it easy to build simple, reliable, and efficient software. The Packer builder for UpCloud was written in Go while leveraging the UpCloud Go API.

Go binaries get frequent updates and the command below to download the install package might not be the latest. You can check for possible newer versions on their download page and change the version number in the package URL as necessary.

curl -O https://storage.googleapis.com/golang/go1.9.3.linux-amd64.tar.gz

Unpack the downloaded binaries to an appropriate location e.g. with the next command.

sudo tar -C /usr/local -xzf go1.9.3.linux-amd64.tar.gz

Then create a new directory to save any Go sources into. You are of course free to choose the location of the Go home directory. If you wish to store the related files somewhere else, set the GOPATH environmental variable accordingly.

mkdir -p ~/go/bin
export GOPATH=$HOME/go
export GOBIN=$GOPATH/bin
export PATH=$PATH:/usr/local/go/bin:$GOBIN

For future use, you should also save the above lines in your profile.

echo 'export GOPATH=$HOME/go' | tee -a ~/.profile
echo 'export GOBIN=$GOPATH/bin' | tee -a ~/.profile
echo 'export PATH=$PATH:/usr/local/go/bin:$GOBIN' | tee -a ~/.profile

This way you will avoid having to reset the paths every time you log in or open a new terminal.

Installing Glide

Glide is the modern package managers for Go. It scans the source code of your application or library to determine the needed dependencies and retrieves them. The dependencies are then exported to the vendor directories where the Go tools can find and use them.

The easiest way to install the latest version of Glide is to use their install script with the following command.

curl https://glide.sh/get | sh

Optionally if you would rather install Glide manually, you can find binaries for a number of operating systems at the Glide releases page.

Once the installation is complete, you can check the Glide version using the command below.

glide -v
glide version v0.13.1

With Glide installed, continue on with installing Packer.

Installing Packer

Packer can also be found on GitHub and is easily installed with Go. Use the following command to download the latest version of Packer for your operating system.

go get github.com/hashicorp/packer

Then verify that Packer can be found and is working by checking the version number.

packer --version
1.1.4

With Packer itself installed and ready, continue below with installing the UpCloud plugin.

Installing upcloud-packer plugin

Now, the last component needed to generate private templates on UpCloud is the Packer builder plugin. Download the package from Github with the following command.

go get github.com/UpCloudLtd/upcloud-packer

Next, change into the downloaded source directory.

cd $GOPATH/src/github.com/UpCloudLtd/upcloud-packer

You can then run the install with Glide and build the plugin with go.

glide install --strip-vendor
go build

Lastly, create a directory for the Packer plugins. Then copy the upcloud-packer binary there to make it available to Packer.

mkdir -p ~/.packer.d/plugins
cp upcloud-packer ~/.packer.d/plugins/packer-builder-upcloud

That is it for the installation. You should now be able to generate templates on UpCloud using Packer commands. Continue below to test it out.

Building a template with Packer

Packer uses simple JSON configuration files to define the template you wish to build. If you installed the plugin from the source, you can locate an example configuration file in the Go sources directory under .../upcloud-packer/examples. Copy the example file to somewhere convenient, e.g. to your $GOPATH.

cp $GOPATH/src/github.com/UpCloudLtd/upcloud-packer/examples/basic_example.json $GOPATH/

Then open the template with your favorite editor, for example using the following command.

nano $GOPATH/basic_example.json

If you just downloaded the prebuilt binaries, you can find the example in the repository. Alternatively, just copy and paste the same template found below. Create a template file basic_example.json where convenient.

The basic template is ready to deploy, but you should take a look at the parameters in the builders segment. The type, username, and password are rather self-explanatory and should be the same for every template. The important parts are the target zone and the original storage-uuid. These tell Packer which public template you wish to use as the basis for generating your own and where it should be made available.

Choose the zone where you wish to deploy cloud servers with the custom template. The currently available zones are the following:

  • Helsinki fi-hel1
  • Helsinki fi-hel2
  • London uk-lon1
  • Frankfurt de-fra1
  • Chicago us-chi1
  • Amsterdam nl-ams1
  • Singapore sg-sin1

The second bit you should select is the public template that will be used to generate your custom template. The example configuration below uses the Ubuntu 16.04 image, but you can use any Linux template you wish available as a public template on UpCloud.

With the basic configuration done, the customization to the template can then be added to the provisioners segment. The example provisioner runs the basic update and upgrade commands in the shell.

Additionally, if you want to log into a server deployed with the template, you might want to include an SSH key to your root user by replacing the <ssh-rsa_key> with your public key or provision another username. The Packer generates a temporary SSH key while building the template which cannot be used afterwards.

You can find instructions on how to use different types of provisioners to customize your template at the Packer documentations for provisioners.

{
   "variables": {
      "UPCLOUD_USERNAME": "{{ env `UPCLOUD_API_USER` }}",
      "UPCLOUD_PASSWORD": "{{ env `UPCLOUD_API_PASSWORD` }}"
   },
   "builders": [
      {
         "type": "upcloud",
         "username": "{{ user `UPCLOUD_USERNAME` }}",
         "password": "{{ user `UPCLOUD_PASSWORD` }}",
         "zone": "nl-ams1",
         "storage_uuid": "01000000-0000-4000-8000-000030060200"
      }
   ],
   "provisioners": [
      {
         "type": "shell",
         "inline": [
           "apt update",
           "apt upgrade -y",
           "echo '<ssh-rsa_key>' | tee /root/.ssh/authorized_keys"
         ]
      }
   ]
}

Once you have made the configurations, save the file and exit the editor.

The Packer builder leverages the UpCloud Go API to interface with the UpCloud API. 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 in the My Account menu under the User Accounts tab.

Enter the API user credentials in your terminal with the following two commands. Replace the <API_username> and <API_password> with your user details.

export UPCLOUD_API_USER=<API_username>
export UPCLOUD_API_PASSWORD=<API_password>

Then in the same terminal, use the command below to generate a template based on the configuration file.

packer build $GOPATH/basic_example.json
==> upcloud: Creating temporary SSH key ...
==> upcloud: Creating server "packer-builder-upcloud-1502364156" ...
==> upcloud: Waiting for server "packer-builder-upcloud-1502364156" to enter the "started" state 
...
==> Builds finished. The artifacts of successful builds are:
--> upcloud: Private template (UUID: 013399d9-5308-46b1-9f89-bcbe0c4b983d, Title: packer-builder-upcloud-1502364156-disk1-template-1502364398, Zone: nl-ams1)

When the deployment process finishes, you should see output similar to the example above.

Conclusions

Congratulations, you should now have your own custom template visible at your UpCloud Control Panel under Disks and My Templates tab. With the simple configuration process and the fast deployment, you can have a purpose build template ready in minutes.

Test it out by pressing the Deploy button and start a new server from the custom template to verify it was build to your specifications.