---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "stackit_loadbalancer Resource - stackit"
subcategory: ""
description: |-
  Setting up supporting infrastructure
  The example below creates the supporting infrastructure using the STACKIT Terraform provider, including the network, network interface, a public IP address and server resources.
---

# stackit_loadbalancer (Resource)

## Setting up supporting infrastructure


The example below creates the supporting infrastructure using the STACKIT Terraform provider, including the network, network interface, a public IP address and server resources.

## Example Usage

```terraform
# Create a network
resource "stackit_network" "example_network" {
  project_id       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name             = "example-network"
  ipv4_nameservers = ["8.8.8.8"]
  ipv4_prefix      = "192.168.0.0/25"
  labels = {
    "key" = "value"
  }
  routed = true
}

# Create a network interface
resource "stackit_network_interface" "nic" {
  project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  network_id = stackit_network.example_network.network_id
}

# Create a public IP for the load balancer
resource "stackit_public_ip" "public-ip" {
  project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  lifecycle {
    ignore_changes = [network_interface_id]
  }
}

# Create a key pair for accessing the server instance
resource "stackit_key_pair" "keypair" {
  name       = "example-key-pair"
  public_key = chomp(file("path/to/id_rsa.pub"))
}

# Create a server instance
resource "stackit_server" "boot-from-image" {
  project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name       = "example-server"
  boot_volume = {
    size        = 64
    source_type = "image"
    source_id   = "59838a89-51b1-4892-b57f-b3caf598ee2f" // Ubuntu 24.04
  }
  availability_zone = "xxxx-x"
  machine_type      = "g2i.1"
  keypair_name      = stackit_key_pair.keypair.name
  network_interfaces = [
    stackit_network_interface.nic.network_interface_id
  ]
}

# Create a load balancer
resource "stackit_loadbalancer" "example" {
  project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name       = "example-load-balancer"
  plan_id    = "p10"
  target_pools = [
    {
      name        = "example-target-pool"
      target_port = 80
      targets = [
        {
          display_name = stackit_server.boot-from-image.name
          ip           = stackit_network_interface.nic.ipv4
        }
      ]
      active_health_check = {
        healthy_threshold   = 10
        interval            = "3s"
        interval_jitter     = "3s"
        timeout             = "3s"
        unhealthy_threshold = 10
      }
    }
  ]
  listeners = [
    {
      display_name = "example-listener"
      port         = 80
      protocol     = "PROTOCOL_TCP"
      target_pool  = "example-target-pool"
    }
  ]
  networks = [
    {
      network_id = stackit_network.example_network.network_id
      role       = "ROLE_LISTENERS_AND_TARGETS"
    }
  ]
  external_address = stackit_public_ip.public-ip.ip
  options = {
    private_network_only = false
  }
}

# This example demonstrates an advanced setup where the Load Balancer is in one
# network and the target server is in another. This requires manual
# security group configuration using the `disable_security_group_assignment`
# and `security_group_id` attributes.

# We create two separate networks: one for the load balancer and one for the target.
resource "stackit_network" "lb_network" {
  project_id       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name             = "lb-network-example"
  ipv4_prefix      = "192.168.10.0/25"
  ipv4_nameservers = ["8.8.8.8"]
}

resource "stackit_network" "target_network" {
  project_id       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name             = "target-network-example"
  ipv4_prefix      = "192.168.10.0/25"
  ipv4_nameservers = ["8.8.8.8"]
}

resource "stackit_public_ip" "example" {
  project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

resource "stackit_loadbalancer" "example" {
  project_id       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name             = "example-advanced-lb"
  external_address = stackit_public_ip.example.ip

  # Key setting for manual mode: disables automatic security group handling.
  disable_security_group_assignment = true

  networks = [{
    network_id = stackit_network.lb_network.network_id
    role       = "ROLE_LISTENERS_AND_TARGETS"
  }]

  listeners = [{
    port        = 80
    protocol    = "PROTOCOL_TCP"
    target_pool = "cross-network-pool"
  }]

  target_pools = [{
    name        = "cross-network-pool"
    target_port = 80
    targets = [{
      display_name = stackit_server.example.name
      ip           = stackit_network_interface.nic.ipv4
    }]
  }]
}

# Create a new security group to be assigned to the target server.
resource "stackit_security_group" "target_sg" {
  project_id  = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name        = "target-sg-for-lb-access"
  description = "Allows ingress traffic from the example load balancer."
}

# Create a rule to allow traffic FROM the load balancer.
# This rule uses the computed `security_group_id` of the load balancer.
resource "stackit_security_group_rule" "allow_lb_ingress" {
  project_id        = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  security_group_id = stackit_security_group.target_sg.security_group_id
  direction         = "ingress"
  protocol = {
    name = "tcp"
  }

  # This is the crucial link: it allows traffic from the LB's security group.
  remote_security_group_id = stackit_loadbalancer.example.security_group_id

  port_range = {
    min = 80
    max = 80
  }
}

resource "stackit_server" "example" {
  project_id        = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  name              = "example-remote-target"
  machine_type      = "g2i.2"
  availability_zone = "eu01-1"

  boot_volume = {
    source_type = "image"
    source_id   = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    size        = 10
  }

  network_interfaces = [
    stackit_network_interface.nic.network_interface_id
  ]
}

resource "stackit_network_interface" "nic" {
  project_id         = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  network_id         = stackit_network.target_network.network_id
  security_group_ids = [stackit_security_group.target_sg.security_group_id]
}
# End of advanced example

# Only use the import statement, if you want to import an existing loadbalancer
import {
  to = stackit_loadbalancer.import-example
  id = "${var.project_id},${var.region},${var.loadbalancer_name}"
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `listeners` (Attributes List) List of all listeners which will accept traffic. Limited to 20. (see [below for nested schema](#nestedatt--listeners))
- `name` (String) Load balancer name.
- `networks` (Attributes List) List of networks that listeners and targets reside in. (see [below for nested schema](#nestedatt--networks))
- `project_id` (String) STACKIT project ID to which the Load Balancer is associated.
- `target_pools` (Attributes List) List of all target pools which will be used in the Load Balancer. Limited to 20. (see [below for nested schema](#nestedatt--target_pools))

### Optional

- `disable_security_group_assignment` (Boolean) If set to true, this will disable the automatic assignment of a security group to the load balancer's targets. This option is primarily used to allow targets that are not within the load balancer's own network or SNA (STACKIT network area). When this is enabled, you are fully responsible for ensuring network connectivity to the targets, including managing all routing and security group rules manually. This setting cannot be changed after the load balancer is created.
- `external_address` (String) External Load Balancer IP address where this Load Balancer is exposed.
- `options` (Attributes) Defines any optional functionality you want to have enabled on your load balancer. (see [below for nested schema](#nestedatt--options))
- `plan_id` (String) The service plan ID. If not defined, the default service plan is `p10`. Possible values are: `p10`, `p50`, `p250`, `p750`.
- `region` (String) The resource region. If not defined, the provider region is used.

### Read-Only

- `id` (String) Terraform's internal resource ID. It is structured as "`project_id`","region","`name`".
- `private_address` (String) Transient private Load Balancer IP address. It can change any time.
- `security_group_id` (String) The ID of the egress security group assigned to the Load Balancer's internal machines. This ID is essential for allowing traffic from the Load Balancer to targets in different networks or STACKIT network areas (SNA). To enable this, create a security group rule for your target VMs and set the `remote_security_group_id` of that rule to this value. This is typically used when `disable_security_group_assignment` is set to `true`.

<a id="nestedatt--listeners"></a>
### Nested Schema for `listeners`

Required:

- `port` (Number) Port number where we listen for traffic.
- `protocol` (String) Protocol is the highest network protocol we understand to load balance. Supported values are: `PROTOCOL_UNSPECIFIED`, `PROTOCOL_TCP`, `PROTOCOL_UDP`, `PROTOCOL_TCP_PROXY`, `PROTOCOL_TLS_PASSTHROUGH`.
- `target_pool` (String) Reference target pool by target pool name.

Optional:

- `display_name` (String)
- `server_name_indicators` (Attributes List) A list of domain names to match in order to pass TLS traffic to the target pool in the current listener (see [below for nested schema](#nestedatt--listeners--server_name_indicators))

<a id="nestedatt--listeners--server_name_indicators"></a>
### Nested Schema for `listeners.server_name_indicators`

Optional:

- `name` (String) A domain name to match in order to pass TLS traffic to the target pool in the current listener



<a id="nestedatt--networks"></a>
### Nested Schema for `networks`

Required:

- `network_id` (String) Openstack network ID.
- `role` (String) The role defines how the load balancer is using the network. Supported values are: `ROLE_UNSPECIFIED`, `ROLE_LISTENERS_AND_TARGETS`, `ROLE_LISTENERS`, `ROLE_TARGETS`.


<a id="nestedatt--target_pools"></a>
### Nested Schema for `target_pools`

Required:

- `name` (String) Target pool name.
- `target_port` (Number) Identical port number where each target listens for traffic.
- `targets` (Attributes List) List of all targets which will be used in the pool. Limited to 1000. (see [below for nested schema](#nestedatt--target_pools--targets))

Optional:

- `active_health_check` (Attributes) (see [below for nested schema](#nestedatt--target_pools--active_health_check))
- `session_persistence` (Attributes) Here you can setup various session persistence options, so far only "`use_source_ip_address`" is supported. (see [below for nested schema](#nestedatt--target_pools--session_persistence))

<a id="nestedatt--target_pools--targets"></a>
### Nested Schema for `target_pools.targets`

Required:

- `display_name` (String) Target display name
- `ip` (String) Target IP


<a id="nestedatt--target_pools--active_health_check"></a>
### Nested Schema for `target_pools.active_health_check`

Optional:

- `healthy_threshold` (Number) Healthy threshold of the health checking.
- `interval` (String) Interval duration of health checking in seconds.
- `interval_jitter` (String) Interval duration threshold of the health checking in seconds.
- `timeout` (String) Active health checking timeout duration in seconds.
- `unhealthy_threshold` (Number) Unhealthy threshold of the health checking.


<a id="nestedatt--target_pools--session_persistence"></a>
### Nested Schema for `target_pools.session_persistence`

Optional:

- `use_source_ip_address` (Boolean) If true then all connections from one source IP address are redirected to the same target. This setting changes the load balancing algorithm to Maglev.



<a id="nestedatt--options"></a>
### Nested Schema for `options`

Optional:

- `acl` (Set of String) Load Balancer is accessible only from an IP address in this range.
- `observability` (Attributes) We offer Load Balancer metrics observability via ARGUS or external solutions. Not changeable after creation. (see [below for nested schema](#nestedatt--options--observability))
- `private_network_only` (Boolean) If true, Load Balancer is accessible only via a private network IP address.

<a id="nestedatt--options--observability"></a>
### Nested Schema for `options.observability`

Optional:

- `logs` (Attributes) Observability logs configuration. Not changeable after creation. (see [below for nested schema](#nestedatt--options--observability--logs))
- `metrics` (Attributes) Observability metrics configuration. Not changeable after creation. (see [below for nested schema](#nestedatt--options--observability--metrics))

<a id="nestedatt--options--observability--logs"></a>
### Nested Schema for `options.observability.logs`

Optional:

- `credentials_ref` (String) Credentials reference for logs. Not changeable after creation.
- `push_url` (String) Credentials reference for logs. Not changeable after creation.


<a id="nestedatt--options--observability--metrics"></a>
### Nested Schema for `options.observability.metrics`

Optional:

- `credentials_ref` (String) Credentials reference for metrics. Not changeable after creation.
- `push_url` (String) Credentials reference for metrics. Not changeable after creation.