Skip to content

index.md

Latest commit

 

History

History
167 lines (133 loc) · 5.43 KB

index.md

File metadata and controls

167 lines (133 loc) · 5.43 KB
Raw
layout
page_title Provider: UpCloud
description The UpCloud Terraform Provider enables organisations to control resources provided by the UpCloud platform.

UpCloud Provider

The UpCloud Terraform Provider enables organisations to control resources provided by the UpCloud platform.

Configure provider

Using environment variables

Define credentials using UPCLOUD_USERNAME and UPCLOUD_PASSWORD environment variables.

terraform {
  required_providers {
    upcloud = {
      source  = "UpCloudLtd/upcloud"
      version = "~> 5.0"
    }
  }
}

provider "upcloud" {
  # username and password configuration arguments can be omitted  
  # if environment variables UPCLOUD_USERNAME and UPCLOUD_PASSWORD are set
  # username = ""
  # password = ""
}

Using configuration arguments

terraform {
  required_providers {
    upcloud = {
      source  = "UpCloudLtd/upcloud"
      version = "~> 5.0"
    }
  }
}

provider "upcloud" {
  username = "<Your username>"
  password = "<Your password>"
}

Schema

Optional Attributes

  • password (String) Password for UpCloud API user. Can also be configured using the UPCLOUD_PASSWORD environment variable.
  • request_timeout_sec (Number) The duration (in seconds) that the provider waits for an HTTP request towards UpCloud API to complete. Defaults to 120 seconds
  • retry_max (Number) Maximum number of retries
  • retry_wait_max_sec (Number) Maximum time to wait between retries
  • retry_wait_min_sec (Number) Minimum time to wait between retries
  • token (String) Token for authenticating to UpCloud API. Can also be configured using the UPCLOUD_TOKEN environment variable or using the system keyring. Use upctl account login command to save a token to the system keyring. (EXPERIMENTAL)
  • username (String) UpCloud username with API access. Can also be configured using the UPCLOUD_USERNAME environment variable.

Using the provider

Requirements

It's recommended to configure your credentials using environment variable:

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 subaccount 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 Create subaccount in top-right corner and fill in the required details and create the subaccount user.
  3. Once the user has been created, go to Permissions and select the user. Then check the Allow API connections checkbox to enable API access for the subaccount user. Note: You can also limit the API connections to a specific IP address or address range for additional security.

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

# set the provider version
terraform {
  required_providers {
    upcloud = {
      source = "UpCloudLtd/upcloud"
      version = "~> 5.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 24.04 LTS (Noble Numbat)"

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

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

Additional tooling

It is recommended to install the UpCloud CLI client upctl to help out with accessing information about your account and troubleshooting. For example, typically Terraform resources require parameters that can be easily listed with commands such as these:

Known issues

  • BACKUP_RULE_CONFLICT when updating server simple_backup and storage backup_rule in one apply

    Removing simple_backup from a server and adding backup_rule to a storage attached to that same server in one apply operation will throw the BACKUP_RULE_CONFLICT error. This is caused by the fact that updating backup rules has to be done in a specific order that is not possible to achieve with Terraform. The workaround for this issue is to first remove simple_backup from the server, apply the change, and then add backup_rule to a desired storage and apply the change separately.