Advanced API templates

The snippets on this page extend the basic request body shown in the API-tab of “Create an ALB”. We recommend you read that page/tab first to understand the basic creation process and prerequisites.

Some advanced features demonstrated on this page may require additional resources, like TLS certificates. Where this is the case, we provide further instructions.

You can explore the complete API specification in the Application Load Balancer API documentation.

ALB with cookie-based session persistence

Add this section to the basic request body to enable cookie-based session persistence for a specific routing rule:

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

ALB with WebSocket support

Add this section to the basic request body to enable WebSocket support for a specific routing rule:

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

ALB with query parameter matching

Add this section to the basic request body to enable query parameter matching for a specific routing rule:

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

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 by using this API method. Here’s an example for the request body:

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

We recommend that you version certificates and add their SHA-256 fingerprint/hash to the filename for easier management and identification. For more certificate operations, consult the Application Load Balancer Certificates API documentation.

2. Create the ALB with HTTPS listener

Add this section to the basic request body to create an HTTPS listener that uses the stored TLS certificate:

{
  ...
  "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"
          ]
        }
      }
    }
  ],
  ...
}

ALB with TLS bridging

This configuration requires an ALB with HTTPS listener and TLS termination enabled!

This example uses a custom certificate authority (CA) for backend TLS validation. For non-custom CAs, skip the customCa field. Add this section to the basic request body to create a target pool with TLS bridging enabled:

{
  ...
  "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" ]
        }
      }
    }
  ],
  ...
}

All of these configurations can also be achieved by using the STACKIT Portal to create and manage your application load balancers.