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. To help in creating private templates easier, 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.

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

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

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. Use the next command to download the Go install package.

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

Then unpack the download to an appropriate location.

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

Next, 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.

With the installation completed, you can check the Glide version using the command below.

glide -v
glide version v0.12.3

With Glide installed, continue on with installing Packer itself.

Installing Packer

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

curl -O https://releases.hashicorp.com/packer/1.0.0/packer_1.0.0_linux_amd64.zip

Once the zip finishes downloading, extract it into the $GOPATH/bin directory. The packer binary is all that is necessary to run Packer.

unzip packer_1.0.0_linux_amd64.zip -d $GOBIN

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

packer --version
1.0.0

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. You can find an example configuration file in the source .../upcloud-packer/examples directory. Copy the example file to somewhere easier to find.

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

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

nano $GOPATH/basic_example.json

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
  • 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 customisation 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 customise 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 output will be in this color.

==> 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)

If the deployment process is successful, 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.