Create an ALB via API

Use these templates to create STACKIT Application Load Balancers (ALBs) via the API. All configurations extend the base template. Advanced features require additional resources like TLS certificates.

Explore the complete API specification in the Application Load Balancer API documentation.

Prerequisites

Before sending requests, ensure you have:

• A valid Bearer token for authentication
• Your STACKIT project ID

Follow the instructions in the overview page to get these items.

Base request format

Send all creation requests as POST calls to this endpoint:

https://alb.api.stackit.cloud/v2beta2/projects/{projectId}/load-balancers

Replace {projectId} with your project ID and use one of the following templates for the creation of your request body.

Base template — ALB with HTTP listener

The following data structure represents a minimal ALB configuration. It provides the common elements which more advanced configurations build upon:

{
  "name": "demo-alb",
  "externalAddress": "45.xxx.xxx.xxx",
  "options": {
    "ephemeralAddress": false,
    "privateNetworkOnly": false
  },
  "networks": [
    {
      "networkId": "a8815d0c-874b-4e47-xxxx-xxxxxxxxxxx",
      "role": "ROLE_LISTENERS_AND_TARGETS"
    }
  ],
  "listeners": [
    {
      "port": 80,
      "protocol": "PROTOCOL_HTTP",
      "http": {
        "hosts": [
          {
            "host": "app.stackit.cloud",
            "rules": [
              {
                "pathPrefix": "/",
                "targetPool": "demo-alb-tp-80"
              }
            ]
          }
        ]
      }
    }
  ],
  "targetPools": [
    {
      "name": "demo-alb-tp-80",
      "targetPort": 80,
      "targets": [
        {
          "displayName": "webserver01",
          "ip": "10.xxx.xxx.xxx"
        },
        {
          "displayName": "webserver02",
          "ip": "10.xxx.xxx.xxx"
        }
      ]
    }
  ]
}

Template — ALB with cookie-based session persistence

{
  ...
  "rules": [
    {
      "pathPrefix": "/tasks",
      "targetPool": "demo-alb-tp-80",
      "cookiePersistence": {
        "name": "sessionid",
        "ttl": "360s"
      }
    }
  ]
  ...
}

Template — ALB with WebSocket support

{
  ...
  "rules": [
    {
      "pathPrefix": "/ws",
      "targetPool": "demo-alb-tp-8000",
      "webSocket": true
    }
  ]
  ...
}

Template — ALB with query parameter matching

{
  ...
  "rules": [
    {
      "pathPrefix": "/resources",
      "targetPool": "demo-alb-tp-80",
      "queryParameters": [
        {
          "name": "userId",
          "exactMatch": "123"
        }
      ]
    }
  ]
  ...
}

Template — ALB with HTTPS listener

This configuration requires a stored TLS certificate!

1. Store your TLS certificate

Before you can create the actual load balancer with an HTTPS listener, you have to store an existing TLS certificate using the following API endpoint:

https://alb.api.stackit.cloud/v2beta2/projects/{projectId}/certificates

Here’s an example for the request body:

{
  "name": "demo-tls-cert",
  "privateKey": "-----BEGIN PRIVATE KEY-----\...\n-----END PRIVATE KEY-----",
  "publicKey": "-----BEGIN CERTIFICATE------\...\n----END CERTIFICATE-----"
}

For more TLS certificate operations, consult the Load Balancer Certificates API documentation.

2. Create the ALB with HTTPS listener

To create the actual load balancer, include the following content as part of your request body:

{
  ...
  "listeners": [
    {
      "displayName": "tls-listener",
      "port": 443,
      "protocol": "PROTOCOL_HTTPS",
      "http": {
        "hosts": [
          {
            "host": "app.stackit.cloud",
            "rules": [
              {
                "pathPrefix": "/",
                "targetPool": "demo-alb-tp-80"
              }
            ]
          }
        ]
      },
      "https": {
        "certificateConfig": {
          "certificateIds": [
            "demo-tls-cert-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ]
        }
      }
    }
  ],
  ...
}

Template — ALB with TLS bridging

This configuration requires an HTTPS listener with TLS termination enabled!

This example uses a custom certificate authority (CA) for backend TLS validation. For non-custom CAs, skip the customCa field.

{
  ...
  "listeners": [
    {
      "displayName": "tls-listener",
      "port": 443,
      "protocol": "PROTOCOL_HTTPS",
      "http": {
        "hosts": [
          {
            "host": "app.stackit.cloud",
            "rules": [
              {
                "pathPrefix": "/",
                "targetPool": "demo-alb-tp-80"
              }
            ]
          }
        ]
      },
      "https": {
        "certificateConfig": {
          "certificateIds": [
            "demo-tls-cert-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ]
        }
      }
    }
  ],
  "targetPools": [
    {
      "name": "secure-tp-5732",
      "targetPort": 5732,
      "targets": [
        {
          "displayName": "my-target",
          "ip": "192.0.2.5"
        }
      ],
      "tlsConfig": {
        "customCa": "my-custom-ca",
        "enabled": true,
        "skipCertificateValidation": false
      },
      "activeHealthCheck": {
        "healthyThreshold": 1,
        "unhealthyThreshold": 1,
        "interval": "3s",
        "intervalJitter": "3s",
        "timeout": "3s",
        "httpHealthChecks": {
          "path": "/health",
          "okStatuses": [ "200" ]
        }
      }
    }
  ],
  ...
}