UpCloud Terraform Provider

• Website: https://www.terraform.io
• 
• Mailing list: Google Groups
• Check examples directory

This Terraform plugin allows managing different UpCloud products with terraform.

Requirements

• Terraform 0.12.x or later
• Go > 1.14

Quick Start

• Install Terraform.
• Set environment variables for authentication

export UPCLOUD_USERNAME="upcloud-api-access-enabled-user"
export UPCLOUD_PASSWORD="verysecretpassword"

• Create a example_create_server.tf file:

# set the provider
terraform {
  required_providers {
    upcloud = {
      source = "UpCloudLtd/upcloud"
      version = "~> 2.0"
    }
  }
}

# Configure the UpCloud provider
provider "upcloud" {}

# Create a server
resource "upcloud_server" "example" {
  hostname = "terraform.example.tld"
  zone     = "de-fra1"
  plan     = "1xCPU-1GB"

  # Set the operating system
  template {
    storage = "Ubuntu Server 20.04 LTS (Focal Fossa)"

    # Use the size allotted by the 1xCPU-1GB plan
    size = 25
  }

  # Add a public IP address
  network_interface {
    type = "public"
  }
}

• Apply Terraform changes with: terraform apply.

Using the provider

You need to set UpCloud credentials in shell environment variable (.bashrc, .zshrc or similar) to be able to use the provider:

export UPCLOUD_USERNAME="upcloud-api-access-enabled-user"
export UPCLOUD_PASSWORD="verysecretpassword"

To allow API access to your UpCloud account, you need to allow API connections by visiting Account-page in your UpCloud Hub. We recommend you to set up a sub-account specifically for the API usage with its own username and password, as it allows you to assign specific permissions for increased security:

1. Open the People-page in the UpCloud Hub
2. Click Add in top-right corner and fill in the required details, and check the Allow API connections checkbox to enable API for the sub-account. You can also limit the API connections to a specific IP address or address range for additional security
3. Click the Create subaccount button at the bottom left of the page to create the sub-account

Below is an example configuration on how to create a server using the Terraform provider with Terraform 0.13 or later:

# set the provider version
terraform {
  required_providers {
    upcloud = {
      source = "UpCloudLtd/upcloud"
      version = "~> 2.0"
    }
  }
}

# configure the provider
provider "upcloud" {
  # Your UpCloud credentials are read from the environment variables:
  # export UPCLOUD_USERNAME="Username of your UpCloud API user"
  # export UPCLOUD_PASSWORD="Password of your UpCloud API user"
}

# create a server
resource "upcloud_server" "example" {
  hostname = "terraform.example.tld"
  zone     = "de-fra1"
  plan     = "1xCPU-1GB"

  # Declare network interfaces
  network_interface {
    type = "public"
  }

  network_interface {
    type = "utility"
  }

  # Include at least one public SSH key
  login {
    user = "terraform"
    keys = [
      "<YOUR SSH PUBLIC KEY>",
    ]
    create_password = false
  }

  # Provision the server with Ubuntu
  template {
    storage = "Ubuntu Server 20.04 LTS (Focal Fossa)"

    # Use all the space allotted by the selected simple plan
    size = 25

    # Enable backups
    backup_rule {
      interval  = "daily"
      time      = "0100"
      retention = 8
    }
  }
}

Terraform 0.12 or earlier (build the provider locally first):

# configure the provider
provider "upcloud" {
  # Your UpCloud credentials are read from the environment variables:
  # export UPCLOUD_USERNAME="Username of your UpCloud API user"
  # export UPCLOUD_PASSWORD="Password of your UpCloud API user"
}

# create a server
resource "upcloud_server" "example" {
  hostname = "terraform.example.tld"
  zone     = "de-fra1"
  plan     = "1xCPU-1GB"

  # Declare network interfaces
  network_interface {
    type = "public"
  }

  network_interface {
    type = "utility"
  }

  # Include at least one public SSH key
  login {
    user = "terraform"
    keys = [
      "<YOUR SSH PUBLIC KEY>",
    ]
    create_password = false
  }

  # Provision the server with Ubuntu
  template {
    storage = "Ubuntu Server 20.04 LTS (Focal Fossa)"

    # Use all the space allotted by the selected simple plan
    size = 25

    # Enable backups
    backup_rule {
      interval  = "daily"
      time      = "0100"
      retention = 8
    }
  }
}

For more examples, check the examples/ directory or visit official Terraform documentation.

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.14+ is required).

Get the provider source code:

git clone [email protected]:UpCloudLtd/terraform-provider-upcloud.git
cd terraform-provider-upcloud

To compile the provider, run go build. This will build the provider and put the provider binary in the current directory.

go build

In the majority of cases the make command will be executed to build the binary in the correct directory.

make

The UpCloud provider will be built and placed in the following location under the ~/.terraform.d/plugins directory. The version number will match the value specified in the makefile and in this case the version is 2.0.0.

~/.terraform.d/plugins
└── registry.upcloud.com
    └── upcloud
        └── upcloud
            └── 2.0.0
                └── darwin_amd64
                    └── terraform-provider-upcloud_v2.0.0

After the provider has been built you can then use standard terraform commands.

Use this provider config with the local version:

terraform {
  required_providers {
    upcloud = {
      source = "registry.upcloud.com/upcloud/upcloud"
      version = "~> 2.1"
    }
  }
}

Testing

In order to test the provider, you can simply run make test.

make test

In order to run the full suite of Acceptance tests, run make testacc.

Note: Acceptance tests create real resources, and often cost money to run.

make testacc

In order to run an individual acceptance test, the '-run' flag can be used together with a regular expression. The following example uses a regular expression matching single test called 'TestUpcloudServer_basic'.

make testacc TESTARGS='-run=TestUpcloudServer_basic'

The following example uses a regular expression to execute a grouping of basic acceptance tests.

make testacc TESTARGS='-run=TestUpcloudServer_*'

In order to view the documentation change rendering visite the terraform documentation preview.

Developing in Docker

You can also develop/build/test in Docker. After you've cloned the repository:

Create a docker container with golang as base:

docker run -it -v `pwd`:/work -w /work golang bash

Install Terraform:

cd /tmp
git clone https://github.com/hashicorp/terraform.git
cd terraform
go install

Build the UpCloud provider:

cd /work
make build

Run Terraform files, e.g. the examples:

cd /tmp
cp /work/examples/server.tf .
# change the provider source in server.tf to "registry.upcloud.com/upcloud/upcloud"
export UPCLOUD_USERNAME="upcloud-api-access-enabled-user"
export UPCLOUD_PASSWORD="verysecretpassword"
terraform init
terraform apply

After exiting the container, you can connect back to the container:

docker start -ai <container ID here>

Consuming local provider with Terraform 0.12.0

With the release of Terraform 0.13.0 the discovery of a locally built provider binary has changed. These changes have been made to allow all providers to be discovered from public and provider registries.

The UpCloud makefile supports the old, Terraform 0.12 style where plugin directory structure is not relevant and only the binary name matters.

The following make command can be executed to build and place the provider in the Go binary directory. Make sure your PATH includes the Go binary directory.

make build_0_12

After the provider has been built and can be executed, you can then use standard terraform commands as normal.