Basic concepts

STACKIT Network Load Balancer (NLB) helps you scale hosted services during high demand and protects them from failures. The STACKIT Network Load Balancer uses two lightweight virtual machines with dedicated load balancing software. These virtual machines are deployed across multiple availability zones to ensure high availability and fault tolerance. This setup reduces the risk of downtime if an infrastructure failure occurs in a single zone. The machines are configured in a clustered active/passive setup within your project, providing high availability and reliability. Network access is secured by automatically provisioned and configured security groups.

You create a STACKIT Network Load Balancer using the STACKIT Portal or the Network Load Balancer API. Services typically run on virtual machines or in containers and connect through a STACKIT Network. A virtual service machine (IP address) and a network are required to configure an NLB.

STACKIT Network Load Balancer currently supports Layer 4 TCP network traffic. It uses either the Round Robin or Maglev method in an active/passive cluster setup.

External IP address

An external IP address is a user-managed, static public IP address where the NLB is exposed. You must obtain this IP address in advance and assign it to the load balancer during creation. After assignment, you cannot change the external IP address for the lifetime of the load balancer.

Ephemeral IP address

An ephemeral IP address is a dynamic public IP address where the NLB is exposed. STACKIT automatically assigns this address when you create the load balancer. Unlike an external IP address, the ephemeral address is not user-managed, is temporary, and is tied to the lifespan of the load balancer. When you delete the load balancer, STACKIT automatically releases the ephemeral IP address, and it is no longer accessible.

Listener

A listener is the entry point for communication. It receives network traffic and forwards it to multiple destinations, called targets.

Service port: Specifies the port the listener uses to receive traffic.
Protocol: Defines the communication protocol for the listener.

Target pool and targets

A target is a service, virtual machine, or container in your project that receives load-balanced traffic from the listener.

A target pool is a group of one or more targets and a target pool port used for communication with the targets. To set up a target pool, you must provide at least one target (IP address) and a target pool port.

You can enable session persistence on the target pool by setting session_persistence.use_source_ip_address to true. When enabled, the load balancing algorithm switches to Maglev.

STACKIT Network Load Balancer uses one or more listeners, each with a single target pool attached. Each target pool must have at least one target. For load balancing, provide at least two targets.

Active health check

An active health check is a monitor that the NLB uses to verify target availability. The health check is enabled by default and supports optional customization:

Check interval (interval): Controls how often the load balancer checks target connections.
Down after (healthyThreshold): Sets the number of failed connection attempts before a target is considered unreachable.
Up after (unhealthyThreshold): Sets the number of successful checks required for a target to be considered reachable.

Connection idle timeouts

STACKIT Network Load Balancer tracks each client connection. To free up resources, the load balancer closes connections that remain idle for too long. Connections are closed gracefully: a FIN segment is sent to both the client and the target. If the load balancer receives a segment for an untracked connection, it sends a RST segment to the client.

You can configure the idle timeout per listener. Lower timeout values release resources more quickly, allowing the load balancer to accept new connections faster. Higher timeout values let long-standing connections persist without data transfer, which is useful for applications that require persistent communication, but this consumes more resources.

The idle timer resets whenever the load balancer forwards data in either direction. A TCP keepalive probe that contains no data does not reset the timer.

Target security group

STACKIT Network Load Balancer configures security groups to control traffic between the load balancer and its targets. These security groups are required for the LB to function properly. They allow connections from the load balancer machines to the targets on the specified ports.

By default, a correctly configured security group is automatically assigned to targets located within the same STACKIT network. This ensures connectivity without requiring any customer intervention.

However, this automatic assignment is not possible if targets are located in another network. In this case you must set the field disableTargetSecurityGroupAssignment to true during creation. This disables automatic assignment and indicates that you will manage connectivity manually.

The required security group is exposed in the read-only targetSecurityGroup field in the API. You can assign the target security group manually when your targets are located in the same project. If your targets are located in a different project, but fall within the same SNA, you can use the loadBalancerSecurityGroup (see below).

This setting can only be configured at creation time. It cannot be changed later. If connectivity is not correctly configured, targets will not be reachable. The reachability of targets will only be checked, if disableTargetSecurityGroupAssignment is set to false.

Load balancer security group

The loadBalancerSecurityGroup field exposes the internal egress security group ID that is assigned to the load balancer’s machines. It includes the id and name of this security group:

"loadBalancerSecurityGroup": {
  "id": "string",
  "name": "string"
}

This id within the loadBalancerSecurityGroup field is crucial for establishing connectivity when your target VMs are located within a different project, but still within the same STACKIT Network Area (SNA). For scenarios where targets are in the same project but in different networks, use targetSecurityGroup (see above).

In such cross-project scenarios, the disableTargetSecurityGroupAssignment must be set to true. You will need to manually configure the security groups for your target VMs, to allow traffic from this load balancer to your external targets. First you must create a security group containing a security group rule. In this rule, you will specify the loadBalancerSecurityGroupID as the remoteSecurityGroupID and assign the final security group to the respective targets. This explicitly permits network traffic originating from this specific load balancer to be accepted by your target VMs, ensuring secure and controlled communication across network boundaries.

How to use the load balancer security group

Scenario 1 — Automatic mode (default)

In the default setup, connectivity is managed for you automatically.

During the creation of the load balancer, you must set the disableTargetSecurityGroupAssignment flag to false (see: Create an NLB via API).
A dedicated target security group is created and applied to all your target VMs.
This security group contains the necessary rules to allow traffic from the load balancer.
No manual configuration is needed.

Scenario 2 — Manual mode (cross-network setup)

If your targets are outside the load balancer’s primary network, automatic assignment is not possible. You must configure networking manually to allow traffic.

To manually configure the security groups of the target VMs you will need to use the IaaS API (see documentation: IaaS API or Terraform Provider).

Create the load balancer with disableTargetSecurityGroupAssignment enabled

For the creation of a network load balancer with the API see: Create an NLB via API
- During the creation of the load balancer, you must set the disableTargetSecurityGroupAssignment flag to true.
- This prevents the system from attempting automatic assignment and signals that you will handle the setup.
Identify the correct load balancer security group ID

After the load balancer is created, the API will expose read-only information about its internal security groups. You must reference this ID in the next step.
- loadBalancerSecurityGroup: Use the id from this field if your targets are in a different project or network (but within the same STACKIT Network Area). This is the ID of the load balancer’s internal egress security group.
Configure your target VM’s security group

Now, you will create and apply a new security group to your target VMs to allow traffic from the load balancer. This involves three actions via the IaaS API:
- Create a new security group for your targets: Give this security group a descriptive name (e.g., my-app-lb-access-sg). Note the new ID it returns.
- Add an ingress rule to this new group: Create a new security group rule that allows incoming traffic. In the rule’s configuration, set the remoteSecurityGroupId to the ID you identified in step 2.
- Assign the new group to your targets: Update the network interface of each of your target VMs to include the ID of the new security group you created in step 3.1. Once these steps are complete, your targets will be correctly configured to accept traffic from the load balancer across network boundaries.
Create a new security group

First, you will create a security group using the POST call with your ProjectId (see Create new security group).
- Path parameters: Include your ProjectId.
- Request body:
```
{
  "description": "Allows ingress traffic to the targets from the Load Balancer",
  "name": "TargetSecurityGroup",
  "stateful": true
}
```
Upon successful creation, note down the id of the newly created security group. This will be referred to as Your-New-Security-Group-Id.
Create a security group rule that accepts load balancer traffic

Next, you will create a new security group rule using the POST call with your ProjectId and the SecurityGroupId of the newly created security group (see Create new security group rule).
- Path parameters: Include your ProjectId and Your-New-Security-Group-Id.
- Request body:
```
{
  "description": "Accept traffic from the Load Balancer",
  "direction": "ingress",
  "ethertype": "IPv4",
  "portRange": {
    "max": <targetPort>,
    "min": <targetPort>
  },
  "remoteSecurityGroupId": <loadBalancerSecurityGroup ID>,
  "protocol": <protocol number (e.g. 6 for tcp)>
}
```
Update network interface

Finally, you will update the network interfaces of your targets to assign your newly created TargetSecurityGroup to them. This enables the targets to accept incoming traffic from the load balancer (see Update a network interface).
- Path parameters: You will need the ProjectId, networkId, and the specific nicId of each VM’s NIC you want to update. You may need to list NICs first to get their IDs (see: List all network interfaces inside a network).
- Request body:
```
{
  "securityGroups": [
    <other existing IDs - use list call>,
    <Your-New-Security-Group-Id>
  ]
}
```
Perform this step for all target VMs that are listed in the load balancer’s target pool. When done, your VMs will be configured to accept traffic originating from the load balancer, even if the target VMs are located outside of the load balancer’s network (but keep in mind that they must be in the same SNA).

Service plans

Service plans define the virtual machine flavor and the maximum number of connections available for your NLB.

Flavor: Specifies the hardware configuration, including compute, memory, and storage capacity for each load balancer virtual machine instance. For more information on the naming scheme read Server machine types.
Max connections: Sets the maximum number of concurrent connections per load balancer virtual machine instance.

To set the service plan, provide a planId field. If you omit planId, the default is p10.

The following table shows available service plans, including their flavors and connection limits:

Plan ID	Region	VM flavor	Max connections
p10 (default)	EU01	t1.2	10,000
p50	EU01	s1a.4d	50,000
p250	EU01	s1a.8d	250,000
p750	EU01	s1a.16d	750,000
p10 (default)	EU02	t3i.1-EU02	10,000
p50	EU02	c2a.4d-EU02	50,000
p250	EU02	c2a.8d-EU02	250,000
p750	EU02	c2a.16d-EU02	750,000

General recommendations

STACKIT Network Load Balancers operate at Layer 4 only. You are responsible for encrypting traffic as needed.
Estimate your required maximum concurrent connections in advance to select the right service plan.
- Use observability integration to identify if a larger plan is more suitable for your workload.
Follow the principle of least privilege by assigning load balancer-specific roles:
- NLB admin: Can perform create, read, update, and delete operations on load balancer resources.
- NLB reader: Can read all load balancer resources.