Skip to content
SHC Docs

UpCloud

SHC has a connection type for UpCloud. It gives a cluster running on UpCloud servers a managed load balancer and block storage.

There is no Terraform module for UpCloud. You create the servers and their private network yourself, then run shc init and shc node join on them.

This page states what the code does. No live estate has run on UpCloud yet, so it has no list of gotchas.

ConcernValue
Connection typeupcloud
Required credentialstoken, zone
DNSNone. UpCloud has no authoritative DNS API, so DNS needs another connection, for example Cloudflare
Load balancerupcloud-lb: one load balancer per connection, TCP only
Block volumesupcloud-storage: created in the connection’s zone, one node at a time
Node cloudupcloud, detected
Node locationThe zone, for example fi-hel1, detected
FieldUsed bySecretMeaning
tokenbothyesAn UpCloud API token
zonebothnoThe zone the load balancer and the storage are created in, for example fi-hel1
network_uuidload balancernoThe private network the load balancer joins to reach the nodes
planload balancernoThe load balancer plan. Defaults to development
base_urlbothnoThe API address. Defaults to https://api.upcloud.com/1.3; leave it unset

token and zone are required to connect. network_uuid is required only by the load balancer: a connection used for volumes alone can leave it out, and a port published through the connection without it is refused with X400973PRXCFG.

A secret never goes on the command line. Put the token in a file and name the file with --value-file:

Terminal window
$ shc connection connect upcloud --cred zone=fi-hel1 --cred network_uuid=<network-uuid> --cred token=- --value-file upcloud.token

The connection name is part of the load balancer’s name (shc-<name>), so it must be 1 to 60 letters, digits, hyphens or underscores.

A block volume reaches only the nodes whose recorded cloud and location match the volume’s. For upcloud-storage that is cloud upcloud and the connection’s zone.

UpCloud servers are detected. A node reads its cloud and its zone from the server’s metadata service when it starts, so shc init and shc node join need no flags:

Terminal window
$ shc node ls

The location column reads upcloud/fi-hel1 for a node in that zone.

Set them by hand only on a node that does not show them:

Terminal window
$ shc init --cloud upcloud --location fi-hel1
$ shc node join <token> --cloud upcloud --location fi-hel1
$ shc node update <node> --cloud upcloud --location fi-hel1

A node that records another cloud, no cloud, or another zone is outside every volume of this connection. A deployment whose volume cannot reach any node stays pending.

upcloud-storage creates one MaxIOPS storage per volume in the connection’s zone, attaches it to the node that runs the deployment, and moves it with the deployment.

  • A volume is single-node read-write (rwo). Any other access mode is refused with X400325VOLCFG.
  • A volume is at most 4096 GiB. Sizes round up to whole GiB.
  • The provider finds the server by the node’s name: a server in the connection’s zone whose title, hostname or UUID equals it. Name each server after its node. Two servers that match are refused.

With more than one connection that can provision volumes, name the one to use:

Terminal window
$ shc config set storage.volumes.provider upcloud

Which mounts go on a block volume is covered in Block storage by default.

upcloud-lb keeps one UpCloud load balancer per connection, named shc-<connection>, with a public IPv4 network and the private network from network_uuid. Every deployment that publishes a port through the connection shares it, so an outside port binds once per connection.

Publish a port through it by naming the connection after @:

Terminal window
$ shc install <app> -t <tenant> -s <stack> --expose 5432@upcloud=<service>:5432

upcloud-lb forwards TCP only. A UDP port on it is refused at install with X400987PRTUDP.