Where the zone is defined<\/li>\n<\/ul>\n\n\n\nCredentials<\/h3>\n\n\n\n The UpCloud provider reads UPCLOUD_USERNAME and UPCLOUD_PASSWORD from the environment, so the provider block can be completely empty:<\/p>\n\n\n\n
export UPCLOUD_USERNAME=”your-api-username”
Providers<\/h3>\n\n\n\n In the project root, create a versions.tf file:<\/p>\n\n\n\n
terraform {
required_providers {
provider “upcloud” {}<\/p>\n\n\n\n
The ~> 5.0 constraint allows any 5.x release but not 6.0, so you get fixes without a major version changing resource behaviour.<\/p>\n\n\n\n
Each module in modules\/ gets a versions.tf with the same required_providers block but no provider block. The root configures the provider and the modules only declare it, which is what keeps them reusable.<\/p>\n\n\n\n
Zone<\/h3>\n\n\n\n Create a variables.tf file in the root:<\/p>\n\n\n\n
variable “zone” {
Every module takes zone = var.zone. Managed databases must sit in the same zone as the private network they attach to, and once attached they can’t migrate zones. So a zone mismatch between modules shows up as a plan that tries to rebuild things.<\/p>\n\n\n\n
Run tofu init before moving on.<\/p>\n\n\n\n
Networking<\/h2>\n\n\n\n The network module creates the private network, a router, and a NAT gateway.<\/p>\n\n\n\n
To set this up, create a modules\/network\/variables.tf file:<\/p>\n\n\n\n
variable “name_prefix” {
variable “zone” {
variable “cidr” {
Then create a modules\/network\/main.tf file:<\/p>\n\n\n\n
resource “upcloud_router” “this” {
lifecycle {
resource “upcloud_network” “private” {
ip_network {
resource “upcloud_gateway” “this” {
router {
And finally, a modules\/network\/outputs.tf file:<\/p>\n\n\n\n
output “network_id” {
output “router_id” {
Then, in the root main.tf file, call the module and add an output so the network ID is visible after the apply:<\/p>\n\n\n\n
module “network” {
output “network_id” {
If you’re coming from AWS, note that there’s no separate subnet resource. The ip_network block is the subnet, so one network means one address range. The CIDR is a variable because peering later needs non-overlapping ranges.<\/p>\n\n\n\n
Outbound access<\/h3>\n\n\n\n The app servers have no public IP, but they still need to install packages, and that’s the NAT gateway’s job.<\/p>\n\n\n\n
A gateway with features = [“nat”] lets the router translate outbound traffic, and it doesn’t tell the servers to send traffic there.<\/p>\n\n\n\n
Without dhcp_default_route = true, DHCP never gives the servers a default route, so anything outside 10.0.10.0\/24 has nowhere to go. The servers boot normally, cloud-init fails to install anything, and the only visible symptom is the load balancer returning 503 because no backend is serving (I can’t tell you how many hours I spent debugging this one).<\/p>\n\n\n\n
The ignore_changes on the router exists for a related reason. The gateway adds its own static route to the router behind the scenes. Without the lifecycle rule, OpenTofu sees that route as drift and removes it on the next apply.<\/p>\n\n\n\n
Run tofu apply.<\/p>\n\n\n\n
The gateway takes a couple of minutes to provision, and when it finishes, you should see:<\/p>\n\n\n\n
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.<\/p>\n\n\n\n
Outputs:<\/p>\n\n\n\n
network_id = “036656aa-b67e-4b07-999b-80441b8ba056”<\/p>\n\n\n\n
Your ID will be different.<\/p>\n\n\n\n
In the UpCloud control panel, open Networks and select nextcloud-private. The overview should show 10.0.10.0\/24 with DHCP enabled.<\/p>\n\n\n\nUpCloud network overview showing the private network with DHCP enabled<\/em><\/p>\n\n\n\nThen check the Routing tab. You’ll see a 0.0.0.0\/0 route. That’s the route the gateway added, and the one the ignore_changes rule protects.<\/p>\n\n\n\nRouting tab showing the default route added by the NAT gateway<\/em><\/p>\n\n\n\nServers<\/h2>\n\n\n\n The compute module creates the app servers.<\/p>\n\n\n\n
To do this, create a modules\/compute\/variables.tf file:<\/p>\n\n\n\n
variable “name_prefix” {
variable “zone” {
variable “network_id” {
variable “plan” {
variable “server_count” {
Then a modules\/compute\/main.tf file:<\/p>\n\n\n\n
resource “upcloud_server” “app” {
hostname = “${var.name_prefix}-app-${count.index + 1}”
template {
network_interface {
login {
user_data = <<-EOF
And finally, a modules\/compute\/outputs.tf file:<\/p>\n\n\n\n
output “private_ips” {
Go back to the root directory, and in the main.tf file, call the compute module and add an output for the private IPs:<\/p>\n\n\n\n
module “compute” {
output “app_private_ips” {
The nginx page is a placeholder so the load balancer has something to check. We’ll replace the user_data with real connection details later.<\/p>\n\n\n\n
Access<\/h3>\n\n\n\n The servers have a single private interface, so there’s no public IP and no SSH from your machine. The fallback is the web console in the control panel, which is why the login block generates a root password and emails it to you.<\/p>\n\n\n\n
You can’t have both. UpCloud rejects create_password = true alongside SSH keys, so pick one per server. With no public interface, a key has nothing to connect to, so the password is the option to go with.<\/p>\n\n\n\n
metadata = true is required too. Cloud-init reads user_data from UpCloud’s metadata service, and the API refuses to create a server from a cloud-init template without it.<\/p>\n\n\n\n
Cloud-init<\/h3>\n\n\n\n I added the retry loop because both servers boot at the same moment and hit the package mirrors together, and on one run, one of them failed to install nginx.<\/p>\n\n\n\n
Cloud-init runs once, and nothing supervises it, so that failure was permanent. Anything in user_data that touches the network should assume it’ll sometimes fail.<\/p>\n\n\n\n
Run tofu apply and when it finishes, you should see:<\/p>\n\n\n\n
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.<\/p>\n\n\n\n
Outputs:<\/p>\n\n\n\n
app_private_ips = [
In the control panel, open Servers. You’ll see nextcloud-app-1 and nextcloud-app-2.<\/p>\n\n\n\nClicking on any of them will reveal they have no public IP, only a private one.<\/p>\n\n\n\nUpCloud control panel showing two servers with only private IPs<\/em><\/p>\n\n\n\nLoad balancer<\/h2>\n\n\n\n The load balancer module creates the only public resource in the build.<\/p>\n\n\n\n
To set it up, create a modules\/loadbalancer\/variables.tf file:<\/p>\n\n\n\n
variable “name_prefix” {
variable “zone” {
variable “network_id” {
variable “backend_ips” {
Then a modules\/loadbalancer\/main.tf file:<\/p>\n\n\n\nresource “upcloud_loadbalancer” “this” {
networks {
networks {
resource “upcloud_loadbalancer_backend” “this” {
properties {
resource “upcloud_loadbalancer_static_backend_member” “app” {
backend = upcloud_loadbalancer_backend.this.id
resource “upcloud_loadbalancer_frontend” “this” {
networks {
And then a modules\/loadbalancer\/outputs.tf file:<\/p>\n\n\n\n
output “public_dns” {
In the root main.tf file, call the module and add an output for the DNS name:<\/p>\n\n\n\n
module “loadbalancer” {
output “lb_dns” {
backend_ips takes the server list straight from the compute module. Change server_count, and the backend members follow, with no edits to this module.<\/p>\n\n\n\n
Public access<\/h3>\n\n\n\n There’s no public network resource on UpCloud. Public access is a networks block with type = “public” on whatever needs it, and in this build that’s only the load balancer. It sits on both networks: public to receive traffic, private to reach the servers.<\/p>\n\n\n\n
The frontend and the DNS output both use networks[1], which is the public block because it’s declared second. That index is positional because if you reorder the blocks, both point to the private network. The DNS name is read from the network block rather than the top-level dns_name attribute, which is deprecated because a load balancer can now have more than one network.<\/p>\n\n\n\n
This listens on plain HTTP. For production, add a certificate bundle and a frontend on 443. The provider supports both automatic and manual bundles.<\/p>\n\n\n\n
Health checks<\/h3>\n\n\n\n fall = 3 and rise = 2 are deliberately different. A server is pulled after 30 seconds of failures but brought back after 20 seconds of success, so a single slow response doesn’t halve your capacity and a flapping server doesn’t keep rejoining.<\/p>\n\n\n\n
Run tofu apply and when it finishes:<\/p>\n\n\n\n
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.<\/p>\n\n\n\n
Outputs:<\/p>\n\n\n\n
app_private_ips = [
Don’t curl it straight away. An apply finishing means UpCloud accepted the resources, not that the servers are serving. For the first few minutes, you’ll get a 503, which is the health check correctly refusing to send traffic to servers still running cloud-init.<\/p>\n\n\n\n
Give it three to four minutes, then:<\/p>\n\n\n\n
curl -H “Connection: close” http:\/\/<your-lb-dns><\/p>\n\n\n\n
Run it a few times. The response should alternate between hello from nextcloud-app-1 and hello from nextcloud-app-2. The Connection: close header forces a fresh connection each time, so you’re testing the balancing rather than a reused connection.<\/p>\n\n\n\n
In the control panel, open Load balancers, select nextcloud-lb, and check the backend. Both members should show as Up. If one is Down while the other serves, it’s a server that didn’t finish cloud-init, not a load balancer problem. That’s the first place to look when traffic only ever reaches one backend.<\/p>\n\n\n\nUpCloud control panel showing the load balancer with both backend members up<\/em><\/p>\n\n\n\nWrapping up<\/h2>\n\n\n\n At this point, you have a private network with a NAT gateway for outbound access, two app servers with no public IP at all, and a load balancer in front of them that health-checks both and distributes traffic between them.<\/p>\n\n\n\n
However, it has nowhere to put anything. The servers serve a placeholder page, and nothing persists.<\/p>\n\n\n\n
Part 2 fixes that. We’ll add managed PostgreSQL with connection pooling, Valkey for caching and sessions, object storage for uploads, an encrypted shared filesystem that both servers can mount, and a peered management network.<\/p>\n\n\n\n
Then we’ll wire every connection detail into the servers through cloud-init, and finish with how to manage and secure the whole thing.<\/p>\n\n\n\n
Before you go, two things. If you’re stopping here for now, run `tofu destroy`, since the gateway and the load balancer bill hourly, and one `tofu apply` brings everything back.<\/p>\n\n\n\n
And the complete modules for both parts are in the GitHub repository<\/a> if you’d rather read ahead.<\/p>\n","protected":false},"author":83,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","community-category":[256,274,259,235],"class_list":["post-10491","tutorial","type-tutorial","status-publish","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/10491","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial"}],"about":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/types\/tutorial"}],"author":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/users\/83"}],"replies":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/comments?post=10491"}],"version-history":[{"count":3,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/10491\/revisions"}],"predecessor-version":[{"id":10508,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/10491\/revisions\/10508"}],"wp:attachment":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/media?parent=10491"}],"wp:term":[{"taxonomy":"community-category","embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/community-category?post=10491"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
![\"Architecture](\"https:\/\/upcloud.com\/media\/opentofu-upcloud-infrastructure-architecture-1024x823.png\")
<\/figure>\n\n\n\n![\"UpCloud](\"https:\/\/upcloud.com\/media\/upcloud-private-network-dhcp-1024x679.png\")
<\/figure>\n\n\n\n![\"UpCloud](\"https:\/\/upcloud.com\/media\/upcloud-nat-gateway-default-route-1024x328.png\")
<\/figure>\n\n\n\n![\"UpCloud](\"https:\/\/upcloud.com\/media\/upcloud-two-private-app-servers-1024x279.png\")
<\/figure>\n\n\n\n![\"Network](\"https:\/\/upcloud.com\/media\/opentofu-private-app-servers-upcloud-1024x501.png\")
<\/figure>\n\n\n\n![\"OpenTofu](\"https:\/\/upcloud.com\/media\/opentofu-upcloud-load-balancer-configuration-968x1024.png\")
<\/figure>\n\n\n\n![\"UpCloud](\"https:\/\/upcloud.com\/media\/upcloud-load-balancer-healthy-backends-1024x690.png\")
<\/figure>\n\n\n\n