Create an NLB

STACKIT Network Load Balancers (NLBs) can be created via the STACKIT Portal, STACKIT API, or the STACKIT Terraform provider.

Preparation

Before you create an NLB, there are some considerations you should make. Use the list below to decide and collect the information you need before you start:

• Naming: Choose a DNS-compliant name (lowercase, hyphens, numbers).
• Visibility: Decide whether the NLB is public or private. For public access, determine if you will attach an existing Public IP or let STACKIT assign one automatically. For private access, expect an automatically assigned private IP.
• Performance: Estimate the expected number of connections to the services/servers behind the load balancer, so you’re able to choose an appropriate service plan.
• Network: Determine the STACKIT network where the NLB will operate. All targets must be in the same network as the load balancer.
• Security posture: If exposing admin or sensitive ports publicly, plan ACL rules (i.e. permitted source IP ranges).
• Ports and protocols (listeners): List the external ports you want to expose and the protocol for each (TCP or UDP). Optionally define a descriptive listener name per port/protocol.
• Target pools and targets: For each listener, define a target pool with a target port and the backend targets that will receive traffic. Collect each target’s IP address (and optional display name). Ensure every target resides in the same network as the NLB.
• Session persistence: Decide if multiple requests in a user session must reach the same target. If yes, enable session persistence (based on source IP). Enabling persistence switches the load balancing algorithm from Round Robin to Maglev.
• Health checks: Decide whether to keep sensible defaults or customize. Defaults typically are: Down after 3 checks, check interval 5 seconds, up after 1 check. If customizing, decide the desired interval and up/down thresholds.

Optionally, you can get an overview of the impending costs by using the STACKIT Pricing Calculator to estimate expenses based on your planned NLB configuration. When using the Portal, costs will be calculated and displayed dynamically in the UI during the creation process.

Process

Follow the steps below to create an NLB using your preferred method.

To successfully execute the examples below:

• A network must exist.
• A target (server) must exist.

By default, a newly created NLB is provisioned with the service plan tier p10. If you need a different plan, you must specify it explicitly.

Via Portal

Navigate to portal.stackit.cloud, select your desired project and follow these steps:

1. In the sidebar under Networking, click on Network Load Balancer.
2. Click the Create Network Load Balancer button.
3. Fill in the required fields with the information you prepared earlier.
4. Click the Order fee-based button to create the NLB.

Done! Your STACKIT Network Load Balancer is being created and will be ready to use shortly.

As a result, two new instances will appear under Computing > Server, as demonstrated below. These instances represent the load balancer nodes that handle incoming traffic and distribute it to your defined targets:

You may also find newly created security groups associated with your NLB under Networking > Security Groups. This will not be the case if you disabled the target security group assignment during NLB creation:

Via API

Prerequisites

In order to create a STACKIT Network Load Balancer via API, you need to acquire a temporary Bearer token for authentication under a Service Account.

• Read “Access services with a service account” to learn how to create a Service Account and generate a Bearer token.
• Read the STACKIT CLI Authentication Guide to learn more about possible CLI and environment setups that enable you to acquire Bearer tokens.
• Please refer to STACKIT Network Load Balancer API documentation to learn more about the available API endpoints, parameters and the structure of request/response bodies.

To validate this request functionality with real data, you can use UI-based API clients like Postman or Thunder Client, or command-line tools like cURL.

While direct API requests are useful for testing or creating resources programmatically via imperative scripts (e.g., Python or Go), for managing production infrastructure, it is highly recommended to use the STACKIT Terraform Provider. Terraform allows for declarative resource definition (Infrastructure as Code), handling the underlying API interactions—like the one detailed below—automatically in the background.

Request details

Method: POST

Endpoint URL:

https://load-balancer.api.stackit.cloud/v2/projects/{projectId}/regions/{region}/load-balancers

Headers:

• Content-Type: application/json
• Authorization: Bearer <your_bearer_token>

Request body:

{
  "name": "my-load-balancer-01",
  "networks": [
    {
      "networkId": "2028e5d4-af4f-45e2-98df-502be37a4317 <UUID of the network where load balancer and targets reside>",
      "role": "ROLE_LISTENERS_AND_TARGETS"
    }
  ],
  "targetPools": [
    {
      "name": "web-backend-pool",
      "targetPort": 8080,
      "targets": [
        {
          "displayName": "web-server-01",
          "ip": "10.1.2.5 <Internal IPv4 address of the first target server>"
        },
        {
          "displayName": "web-server-02",
          "ip": "10.1.2.6 <Internal IPv4 address of a second target server>"
        }
      ],
      "activeHealthCheck": {
        "healthyThreshold": 2,
        "interval": "3s",
        "intervalJitter": "3s",
        "timeout": "3s",
        "unhealthyThreshold": 2
      }
    }
  ],
  "listeners": [
    {
      "displayName": "http-listener",
      "port": 80,
      "protocol": "PROTOCOL_TCP",
      "targetPool": "web-backend-pool <Must match the 'name' defined in the targetPools list above>"
    }
  ],
  "options": {
    "privateNetworkOnly": true,
    "accessControl": {
      "allowedSourceRanges": [
        "0.0.0.0/0 <CIDR range allowed to access this Load Balancer>"
      ]
    }
  }
}

Via Terraform

Here is a barebones definition for a STACKIT Load Balancer using the official STACKIT Terraform provider (version 0.79.0):

terraform {
  required_providers {
    stackit = {
      source = "stackitcloud/stackit"
    }
  }
}

# Key flow (using path)
provider "stackit" {
  # Credential configuration usually goes here or in ENV variables
  default_region           = "eu01"
  service_account_key_path = pathexpand("~/.stackit/credentials.json")
}

resource "stackit_loadbalancer" "example" {
  project_id = "your-project-uuid"
  name       = "example-tf-load-balancer"

  networks = [
    {
      network_id = "your-network-uuid"
      role       = "ROLE_LISTENERS_AND_TARGETS"
    }
  ]
  options = {
    private_network_only = true
  }

  target_pools = [
    {
      name        = "example-pool"
      target_port = 80
      targets = [
        {
          display_name = "target-1"
          ip           = "10.0.0.1" # Internal IP of your existing target
        }
      ]
    }
  ]

  listeners = [
    {
      display_name = "example-listener"
      port         = 80
      protocol     = "PROTOCOL_TCP"
      target_pool  = "example-pool"
    }
  ]
}