13 min read

Learning Objectives

By the end of this module, you will be able to:

  • Define Network Security Groups and their rules with `ionoscloud_nsg` and `ionoscloud_nsg_firewallrule`, and attach them to server NICs
  • Provision a Managed Application Load Balancer with `ionoscloud_application_loadbalancer`, a forwarding rule and a target group
  • Configure path-based HTTP routing and health checks for TaskBoard's API in code
  • Provision a Managed Network Load Balancer with `ionoscloud_networkloadbalancer` and choose between NLB and ALB
  • Protect load-balanced servers with NIC-level rules that admit only the load balancer's private address

Unit 2.3: Load Balancing and Security as Code

Introduction

TaskBoard's network from Unit 2.2 separates the tiers, but anything inside the app LAN can still reach every port of the API server, and clients still connect to a single server. Before you add a second API server, you need a load balancer in front of the API and firewall rules that you can review in a pull request.

In this unit you write both as code. Network Security Groups (NSGs) hold stateful firewall rules that apply to servers and NICs. The Managed Application Load Balancer (ALB) routes HTTP requests by path to target groups with health checks, and the Managed Network Load Balancer (NLB) distributes TCP traffic. Both load balancers are their own Terraform resources that you provision separately from the servers behind them. In the Code Lab you put an ALB in front of TaskBoard's API and lock down the app tier with an NSG.

1. Network Security Groups as Code

resource "ionoscloud_nsg" "app" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  name          = "taskboard-app"
  description   = "App tier: HTTP from the ALB only"
}

resource "ionoscloud_nsg_firewallrule" "app_http_from_alb" {
  datacenter_id    = ionoscloud_datacenter.taskboard.id
  nsg_id           = ionoscloud_nsg.app.id
  name             = "http-from-alb"
  type             = "INGRESS"
  protocol         = "TCP"
  source_ip        = "10.10.1.6"
  port_range_start = 80
  port_range_end   = 80
}

resource "ionoscloud_nsg_firewallrule" "app_egress" {
  datacenter_id = ionoscloud_datacenter.taskboard.id
  nsg_id        = ionoscloud_nsg.app.id
  name          = "egress-all"
  type          = "EGRESS"
  protocol      = "ANY"
}

An NSG has a deny-all default: rules only permit traffic, and any traffic not explicitly allowed is blocked. That applies to both directions, which is why the example also adds an egress rule. NSG firewalls are stateful, so replies to an allowed connection pass without a rule of their own.

1.1 Rule Arguments

Argument Required Notes
nsg_id, datacenter_id Yes The NSG and its VDC
protocol Yes TCP, UDP, ICMP or ANY; changing it forces a new rule
type No INGRESS (default) or EGRESS
source_ip, target_ip No One IPv4 address each; null allows all
port_range_start, port_range_end No For TCP and UDP; leave both null to allow all ports
icmp_type, icmp_code No For ICMP only

As the table shows, a rule matches a single source address. For a tier with several clients, write one rule per client, or generate them with for_each:

resource "ionoscloud_nsg_firewallrule" "db_from_app" {
  for_each         = toset(["10.10.2.11", "10.10.2.21"]) # DB-LAN NICs, Unit 2.5
  datacenter_id    = ionoscloud_datacenter.taskboard.id
  nsg_id           = ionoscloud_nsg.db.id
  name             = "pg-from-${each.value}"
  protocol         = "TCP"
  source_ip        = each.value
  port_range_start = 5432
  port_range_end   = 5432
}

1.2 Attaching NSGs to Servers and NICs

NICs and VMs can be NSG members. When a VM is a member, all of its NICs inherit the rules. To protect only the app-tier interface of the API server, attach the NSG to that NIC:

resource "ionoscloud_nic" "api_app" {
  datacenter_id       = ionoscloud_datacenter.taskboard.id
  server_id           = ionoscloud_server.api.id
  lan                 = ionoscloud_lan.app.id
  name                = "app"
  dhcp                = true
  ips                 = ["10.10.1.11"]
  firewall_active     = false
  security_groups_ids = [ionoscloud_nsg.app.id]
}

ionoscloud_server and ionoscloud_vcpu_server accept the same security_groups_ids argument for server-wide membership. A VDC can have one default NSG, linked with ionoscloud_datacenter_nsg_selection; every newly provisioned VM is added to it automatically.

1.3 NSG Limits and Scope

The defaults are 200 NSGs per VDC, 100 rules per NSG, and 10 NSGs per VM or per NIC. You cannot add nodes from Managed Kubernetes node pools or suspended Cubes as members. NSG members are NICs and VMs, so an NSG binds to the servers behind a load balancer, never to the ALB or NLB itself (Section 4).

The NIC-based firewall uses the ionoscloud_firewall resource and the firewall_active flag on a NIC. Using NSGs in parallel with a NIC-based firewall is not recommended, which is why the NIC above sets firewall_active = false.

2. The Managed Application Load Balancer

The ALB operates at Layer 7. Each ALB needs at least one listener, a forwarding rule and a target group. A listener accepts client connections on an IP and port; forwarding rules decide how requests reach the registered targets.

2.1 Load Balancer and Target Group

resource "ionoscloud_ipblock" "alb" {
  name     = "taskboard-alb-ip"
  location = ionoscloud_datacenter.taskboard.location
  size     = 1
}

resource "ionoscloud_application_loadbalancer" "api" {
  datacenter_id  = ionoscloud_datacenter.taskboard.id
  name           = "taskboard-alb"
  listener_lan   = ionoscloud_lan.public.id
  ips            = [ionoscloud_ipblock.alb.ips[0]]
  target_lan     = ionoscloud_lan.app.id
  lb_private_ips = ["10.10.1.6/24"]
}

resource "ionoscloud_target_group" "api" {
  name             = "taskboard-api"
  algorithm        = "ROUND_ROBIN"
  protocol         = "HTTP"
  protocol_version = "HTTP1"

  targets {
    ip     = "10.10.1.11"
    port   = 80
    weight = 100
  }

  health_check {
    check_interval = 2000
    retries        = 3
  }
  http_health_check {
    path       = "/health"
    method     = "GET"
    match_type = "STATUS_CODE"
    response   = "200"
  }
}

A public ALB needs customer-reserved public IPs on the listener LAN, so ips comes from an IP block. target_lan is the balanced private LAN, and lb_private_ips is the ALB's own address in it, with a subnet mask. If you omit it, the system generates an IP with a /24 subnet. A fixed address from the managed-services range (Unit 2.2, Section 1.3) lets you write NSG rules against it.

Target weights range from 0 to 256. A target with weight 0 receives no balanced traffic but still accepts persistent connections. The health check interval defaults to 2000 ms with 3 retries, and the HTTP health check path defaults to /.

2.2 Forwarding Rules and Path-Based Routing

resource "ionoscloud_application_loadbalancer_forwardingrule" "http" {
  datacenter_id               = ionoscloud_datacenter.taskboard.id
  application_loadbalancer_id = ionoscloud_application_loadbalancer.api.id
  name                        = "http"
  protocol                    = "HTTP"
  listener_ip                 = ionoscloud_ipblock.alb.ips[0]
  listener_port               = 80

  http_rules {
    name         = "api"
    type         = "FORWARD"
    target_group = ionoscloud_target_group.api.id
    conditions {
      type      = "PATH"
      condition = "STARTS_WITH"
      value     = "/api"
    }
  }

  http_rules {
    name             = "default"
    type             = "STATIC"
    status_code      = 404
    response_message = "Not found"
    content_type     = "text/plain"
  }
}

A FORWARD rule needs a target_group. Conditions can match HEADER, PATH, QUERY, METHOD, HOST, COOKIE or SOURCE_IP, and the action runs only if every condition is met. A rule without conditions always applies, so the STATIC rule returns a fixed 404 for every other path. REDIRECT rules send clients elsewhere with status 301, 302, 303, 307 or 308.

For HTTPS, keep protocol = "HTTP" and pass certificate IDs in server_certificates; the ALB then terminates TLS. An ALB supports up to 10 listeners, and client_timeout defaults to 50,000 ms.

3. The Managed Network Load Balancer

# ionoscloud_ipblock.nlb: a one-address block, like ionoscloud_ipblock.alb
resource "ionoscloud_networkloadbalancer" "tcp" {
  datacenter_id  = ionoscloud_datacenter.taskboard.id
  name           = "taskboard-nlb"
  listener_lan   = ionoscloud_lan.public.id
  ips            = [ionoscloud_ipblock.nlb.ips[0]]
  target_lan     = ionoscloud_lan.app.id
  lb_private_ips = ["10.10.1.7/24"]
}

resource "ionoscloud_networkloadbalancer_forwardingrule" "ws" {
  datacenter_id          = ionoscloud_datacenter.taskboard.id
  networkloadbalancer_id = ionoscloud_networkloadbalancer.tcp.id
  name                   = "websocket"
  algorithm              = "SOURCE_IP"
  protocol               = "TCP"
  listener_ip            = ionoscloud_ipblock.nlb.ips[0]
  listener_port          = 443

  targets {
    ip     = "10.10.1.11"
    port   = 8443
    weight = 1
    health_check {
      check          = true
      check_interval = 2000
    }
  }
}

The NLB has the same listener LAN and target LAN model, but its rules and health checks are TCP only. Health check defaults are a 50,000 ms client timeout, a 5,000 ms connect timeout, a 50,000 ms target timeout and 3 retries.

3.1 NLB or ALB?

Need Choose
Routing by path, header, host, query or cookie ALB
Fixed responses or redirects without a backend ALB
TLS termination with certificates on the load balancer ALB
Any TCP protocol, decided only at Layer 4 NLB
Client stickiness by source IP NLB with SOURCE_IP

If your balancing logic needs HTTP requests and their attributes, use the ALB. If routing performance is critical, keep the logic at Layer 4 and route TCP traffic through the NLB. TaskBoard uses the ALB for its REST API.

4. Securing Load-Balanced Tiers

4.1 Where the Rules Apply

NSG rules bind to the NICs of the servers in the target LAN, not to the load balancer. So you secure an ALB-fronted service from the target side:

  1. Give the ALB a fixed lb_private_ips address, for example 10.10.1.6.
  2. Allow the service port on the target NIC only from that address (Section 1).
  3. Give targets no public NIC, or keep the public NIC out of the service path.
locals {
  alb_private_ip = "10.10.1.6"
}
# In the ALB:      lb_private_ips = ["${local.alb_private_ip}/24"]
# In the NSG rule: source_ip      = local.alb_private_ip

One local value keeps the ALB address and the NSG rule in sync. In this unit's lab the API server keeps its public NIC for SSH; in production, remove it and reach the server through the VPN (Unit 2.2).

4.2 Outbound Traffic from Targets

Neither the ALB nor the NLB supports Source NAT (SNAT): targets cannot initiate network connections through the load balancer. Servers behind the load balancer that need to download packages or call external APIs use the Managed NAT Gateway and the route from Unit 2.2. The NSG egress rule from Section 1 must allow that traffic too.

API Reference Quick Card

Key API endpoints behind this unit's resources:

Method Endpoint Description
POST /datacenters/{datacenterId}/securitygroups Created by ionoscloud_nsg
POST /datacenters/{datacenterId}/securitygroups/{securityGroupId}/rules Created by ionoscloud_nsg_firewallrule
PUT /datacenters/{datacenterId}/servers/{serverId}/nics/{nicId}/securitygroups Sets the NSGs of a NIC
POST /datacenters/{datacenterId}/applicationloadbalancers Created by ionoscloud_application_loadbalancer
POST /targetgroups Created by ionoscloud_target_group

Base URL: https://api.ionos.com/cloudapi/v6 Authentication: Authorization: Bearer <token>

Code Lab

Objective: Provision an ALB in front of TaskBoard's API with Terraform, attach an NSG to the API server's app NIC, and verify that HTTP traffic reaches the API only through the ALB.

Prerequisites:

  • The network project from Unit 2.2, applied, with IONOS_TOKEN set
  • Terraform with the provider pinned as in Unit 1.2
  • The API server serving HTTP on port 80 (cloud-init from Unit 2.1)

Step 1: Add a health endpoint to the API server

Extend the API server's cloud-config so that nginx returns 200 for /health and /api/ (for example with write_files and two location blocks). Because user_data applies only to new volumes, rebuild the server:

terraform apply -replace=ionoscloud_server.api -auto-approve | tail -n 1

Expected output:

Apply complete! Resources: ... added, 0 changed, ... destroyed.

Step 2: Add the NSG and its rules

Add ionoscloud_nsg.app and both rules from Section 1, and set firewall_active = false and security_groups_ids on ionoscloud_nic.api_app (Section 1.2).

terraform plan | grep -E "will be (created|updated)"

Expected output:

  # ionoscloud_nic.api_app will be updated in-place
  # ionoscloud_nsg.app will be created
  # ionoscloud_nsg_firewallrule.app_egress will be created
  # ionoscloud_nsg_firewallrule.app_http_from_alb will be created

Step 3: Add the ALB, target group and forwarding rule

Add the resources from Sections 2.1 and 2.2, plus an output:

output "alb_ip" { value = ionoscloud_ipblock.alb.ips[0] }
terraform apply -auto-approve | tail -n 1

Expected output:

Apply complete! Resources: 7 added, 1 changed, 0 destroyed.

Step 4: Check the ALB through the API

DC=$(terraform output -raw datacenter_id)
curl -s -H "Authorization: Bearer $IONOS_TOKEN" \
  "https://api.ionos.com/cloudapi/v6/datacenters/$DC/applicationloadbalancers?depth=1" \
  | jq -r '.items[] | "\(.properties.name) \(.metadata.state)"'

Expected output:

taskboard-alb AVAILABLE

Step 5: Verify routing through the ALB

ALB=$(terraform output -raw alb_ip)
curl -s -o /dev/null -w "%{http_code}\n" "http://$ALB/api/"
curl -s -o /dev/null -w "%{http_code}\n" "http://$ALB/other"

Expected output:

200
404

Step 6: Verify isolation inside the app LAN

ssh -J root@"$(terraform output -raw api_public_ip)" root@10.10.1.21 \
  'curl -s --max-time 5 -o /dev/null -w "%{http_code}\n" http://10.10.1.11/api/ || echo blocked'

Expected output:

000
blocked

The worker is in the same LAN, but the NSG on the API server's app NIC admits port 80 only from the ALB's address 10.10.1.6.

Validation Checklist:

  • [ ] The ALB is AVAILABLE with the reserved public IP
  • [ ] /api/ returns 200 through the ALB and other paths return the static 404
  • [ ] The worker cannot reach the API server's port 80 directly
  • [ ] terraform plan shows no changes after the apply

Cleanup:

terraform destroy -auto-approve

Common Pitfalls

Developer mistakes to avoid with this unit's topic:

  1. All traffic blocked after attaching an NSG

    • Problem: As soon as the NSG is attached, the server stops answering and cannot reach the NAT gateway or the database.
    • Why it happens: NSGs deny all traffic that no rule allows, in both directions.
    • Fix: Add explicit EGRESS rules for the outbound traffic the server needs, and INGRESS rules for each client address and port.
  2. Expecting the NSG to protect the load balancer

    • Problem: You attach an NSG to the ALB in a design document, and the Terraform plan has no place to put it.
    • Why it happens: NSG members are NICs and VMs. The load balancer's listener is not a member.
    • Fix: Filter on the target NICs, with rules that allow only the load balancer's fixed lb_private_ips address (Section 4.1).
  3. Health checks mark every target as down

    • Problem: The ALB returns errors although the API server runs.
    • Why it happens: The HTTP health check requests a path the application does not serve, or the NSG blocks the health check from the ALB's private address.
    • Fix: Point http_health_check.path at an endpoint that returns the configured response, and allow the ALB's private IP on the service port.

Summary

You can now put TaskBoard's API behind a load balancer and secure it as code. NSGs hold stateful, deny-by-default rules that you attach to servers or NICs. The ALB connects a public listener LAN with a private target LAN, routes HTTP requests by path to target groups with health checks, and can return fixed responses. The NLB covers TCP-only balancing, and the security boundary always sits on the target NICs.

Key Points:

  • NSG rules only permit traffic; everything else is blocked in both directions, and replies are allowed (stateful)
  • NSG members are NICs and VMs; do not use NSGs in parallel with the NIC-based firewall
  • An ALB needs a listener, a forwarding rule and a target group; public listeners need reserved IPs
  • Use the ALB for HTTP routing and TLS termination, the NLB for Layer 4 TCP balancing
  • Neither load balancer supports SNAT; targets use the NAT gateway for outbound traffic

Important Terminology:

  • Network Security Group (NSG): A set of stateful allow rules applied to member NICs or VMs in a VDC
  • Listener LAN: The LAN where a load balancer accepts client connections
  • Target LAN: The private LAN where a load balancer reaches its targets through lb_private_ips
  • Target group: A reusable set of ALB targets with an algorithm and health checks
  • Forwarding rule: The listener configuration that maps an IP and port to targets, with HTTP rules on an ALB

Next Steps

Continue Learning: Unit 2.4: Storage Provisioning as Code

Related Topics: