Basic concepts of the ALB

STACKIT Application Load Balancer (ALB) efficiently distributes traffic to your services, increases reliability, and simplifies scaling. ALB operates at layer 7 (application layer), so you can route traffic based on content such as paths, headers, and hostnames. ALB supports these advanced features:

• Content-based routing
• Cookie-based session persistence
• TLS offloading
• TLS bridging

Each ALB runs on two lightweight virtual machines in an active/passive cluster. These virtual machines are distributed across multiple availability zones. This design ensures high availability and fault tolerance, reducing the risk of downtime if infrastructure fails in a single zone. Network security is managed automatically using pre-configured security groups, so your services remain protected without extra setup.

Create an ALB by using the STACKIT Application Load Balancer API. Connect your services—virtual machines or containers—using a STACKIT Network, which is required for ALB configuration.

IP address

STACKIT Application Load Balancer can be exposed using either an external or an ephemeral IP address. The following table summarizes the differences:

IP address type	Description	Management	Lifetime
External IP address	User-managed, static public IP address. Must be obtained before ALB creation and assigned during setup.	User-managed	Remains for the lifetime of the ALB
Ephemeral IP address	Dynamic public IP address. Assigned automatically at ALB creation and released on deletion.	System-managed	Tied to the ALB’s lifespan

External IP address

The external IP address is a static, public address you manage. Obtain this address before creating the Application Load Balancer and assign it during setup. You cannot change the external IP address after assignment.

Ephemeral IP address

The ephemeral IP address is a dynamic, public address assigned automatically when you create the Application Load Balancer. This address is not user-managed and is released when the Application Load Balancer is deleted.

Listener

A listener is the entry point for incoming connections to the ALB. It receives traffic on a specified port and forwards it to one or more targets based on defined rules and protocol options.

A listener is composed of a small set of top-level fields plus one protocol-specific option block. The following table summarizes each field:

Field	Type	Description
name	String	Human-readable identifier for the listener. Must be unique within the ALB. Used in API paths, logs, and cross-references.
port	Integer	Service port on which the listener accepts incoming traffic.
protocol	enum	Communication protocol accepted by the listener. Supported values include PROTOCOL_HTTP and PROTOCOL_HTTPS.
http	Object	HTTP-specific configuration block. Present when protocol is PROTOCOL_HTTP. Contains host and rule definitions.
https	Object	HTTPS-specific configuration block. Present when protocol is PROTOCOL_HTTPS. Contains host and rule definitions plus TLS offloading settings.
wafConfigName	String	Optional. Name of the ALB WAF configuration that inspects traffic on this listener. Omit or leave empty to run the listener without ALB WAF inspection.

For the complete listener request and response schema, see the v2 API — ALB listeners reference.

Name

The name is a human-readable identifier for the listener. It must be unique within the same ALB and is used in API paths, log records, and cross-references from other objects.

Service port

The service port specifies the port on which the listener receives incoming traffic.

Protocol

The protocol defines the communication protocol used by the listener. STACKIT Application Load Balancer supports HTTP and HTTPS protocols.

Protocol options

Protocol options are configuration blocks under each listener. They define how to handle incoming traffic based on the selected protocol.

You can configure protocol-specific options for HTTP and HTTPS listeners. These options control how requests are matched and routed. The http block applies to PROTOCOL_HTTP listeners and the https block applies to PROTOCOL_HTTPS listeners; the two blocks share the same host and rule model, but only https accepts TLS offloading settings.

Host

The host is a domain name that specifies which virtual host should handle the request.

Host matching order

When a request includes a Host header, the ALB matches it against the defined host entries in your rules. The matching order is:

1. Exact match: Rules with an exact match for the Host header are prioritized. For example, a rule with the host stackit.cloud takes precedence over a wildcard or catch-all rule for requests with the Host header stackit.cloud.
2. Wildcard match: If no exact match is found, the load balancer checks for wildcard matches. For example, a rule with the host *.stackit.cloud matches requests with Host headers like api.stackit.cloud or docs.stackit.cloud. The most specific wildcard match is preferred. For example, api.europe.stackit.cloud matches *.europe.stackit.cloud before *.stackit.cloud.
3. Catch-all: If no exact or wildcard match is found, the load balancer uses the rule with the catch-all host (*), if defined. This rule matches any Host header.

Rule

A rule defines how incoming traffic is processed. It specifies the conditions for matching requests and the actions the ALB takes when those conditions are met.

Rules can include these matchers:

• Path: Matches the part of the URL after the domain (for example, /api/v1/users). Used to route requests to the correct target.
• Header matchers: Match requests based on HTTP header values (for example, x-api-key: my-key).
• Query parameter matchers: Match requests based on specific key-value pairs in the query string (for example, ?version=1.0).
• Cookie persistence: Ensures session persistence by routing requests from the same user to the same target based on cookies.
• WebSocket: Supports WebSocket connections for real-time communication between client and server.

Path matching algorithm

You can use two path match types:

• Prefix: Matches requests with paths that start with the specified prefix. For example, /api matches /api, /api/v1/users, and /api123, but not /foobar.
• Exact: Matches requests with the exact specified path (for example, /api/v1/users matches only that path).

Path selection strategy

The Application Load Balancer evaluates routes in the order they are defined. The first route that matches a request is selected, and matching stops as soon as a match is found.

For example, given this route list in order:

1. /api
2. /api/v1

A request to /api/v1/users matches route 1 (/api), even though route 2 is more specific, because it appears later in the list.

To ensure the most specific match is used, always list more specific prefixes first.

ALB WAF configuration

The wafConfigName field attaches an ALB WAF configuration to the listener. When set to the name of an existing ALB WAF configuration in the same project and region, the listener inspects all Layer 7 traffic on that port with the Coraza engine before forwarding requests to the target pools. Removing the field disables ALB WAF inspection for that listener without deleting the referenced ALB WAF configuration, which can still be attached to other listeners.

Because activation is per-listener, you can protect only the ports that need inspection (for example, PROTOCOL_HTTPS on 443) while leaving other listeners on the same ALB untouched.

For the object model, managed rule sets, custom rule groups, and ALB WAF logging, see ALB WAF features and Basic concepts of the ALB WAF.

Target pool

A target pool is a group of one or more backend resources—called targets—that receive and process traffic distributed by the ALB. Each target pool is configured with a communication port and a set of targets, identified by their IP addresses.

When you configure a target pool, specify:

• At least one target IP address
• A target pool port for backend communication

STACKIT Application Load Balancer distributes traffic across targets in the pool using the Maglev load balancing algorithm. This approach ensures high performance and consistent traffic distribution.

Target

A target is an individual backend resource—either a virtual machine (VM) or a container—that processes traffic forwarded by the Application Load Balancer. Targets must be reachable with the STACKIT Network and respond on the specified target pool port.

Maintaining healthy and responsive targets is critical for delivering reliable and scalable services.

HTTP headers

The Application Load Balancer automatically appends the X-Forwarded-For and X-Forwarded-Proto headers to all requests routed to targets. These headers identify the original client IP address and the protocol used to connect to the ALB. For security purposes, the ALB ignores any existing values for these headers on incoming client requests to prevent spoofing.

TLS offloading

TLS offloading is the process where the STACKIT Application Load Balancer handles the encryption and decryption of secure traffic. This offloads encryption work from your backend servers, finally lowering hardware requirements.

When users connect to your application over HTTPS, the ALB manages encryption and decryption. After decrypting the traffic, it forwards the data as plain HTTP to your target servers. This approach keeps client traffic secure and optimizes backend server performance.

To set up an HTTPS listener, store a valid X.509 SSL/TLS certificate using the STACKIT Certificate API. A TLS certificate, issued by a Certificate Authority (CA), includes:

• Identification details
• Validity period
• Public key
• Serial number
• Issuer’s digital signature

TLS certificates ensure that traffic between clients and the Application Load Balancer is encrypted and authenticated, protecting sensitive information and verifying the organizational identity behind your site.

Certificate ID

The certificate ID is a unique identifier for a TLS/SSL certificate stored with the STACKIT Certificate API. This ID is required when configuring HTTPS listeners.

TLS bridging

A target pool can define how encrypted traffic is handled between the STACKIT Application Load Balancer and your backend services. TLS bridging only works when HTTPS is enabled and then ensures traffic is encrypted at every stage of the connection path.

Enable TLS bridging by configuring TLS on the target pool for an HTTPS listener. You can specify a custom Certificate Authority (CA) using the customCAId field. If you do not specify a custom CA, the system’s trusted CAs are used by default.

TLS bridging ensures that sensitive data remains encrypted both over the public internet and within your private network.

Active health checks

Active health checks monitor the health of backend targets to ensure that traffic is routed only to healthy instances. The Application Load Balancer sends requests to targets based on configurable settings. If a target fails health checks, it is temporarily removed from the target pool until it passes again.

Default health checks

The following table summarizes default health check settings:

Setting	Description	Range	Default value
Check interval	Time between health checks in seconds.	>0	5
Down after	Number of consecutive failed checks after which a target is marked as “unhealthy”.	1-20	3
Up after	Number of consecutive successful checks after which a target is marked as “healthy”.	1-20	3

Optional HTTP health checks

HTTP health checks validate backend responsiveness using HTTP requests instead of TCP connections. You can configure:

• An HTTP path (for example, /health)
• Acceptable HTTP status codes (for example, 200-299) to define successful responses

Observability

Observability is a managed service that provides a comprehensive toolset for monitoring telemetry data—metrics and logs. For detailed information about observability and its capabilities, see the Observability documentation.

You can integrate your STACKIT Application Load Balancer with an Observability instance to gain real-time insights into traffic flow, performance, and application health. This integration enables you to monitor your traffic behavior and infrastructure performance, quicker identify bottlenecks, and ensure a seamless user experience.

Logs

Standard outputs consist primarily of underlying Envoy proxy system logs. These indicate whether Envoy started, stopped, or is healthy. Enhanced log delivery is on our current roadmap.

When an ALB listener has an ALB WAF configuration attached, the ALB additionally emits ALB WAF logs produced by the embedded Coraza engine (shipped under the component="waf" label). For record anatomy, correlation, and a worked example, see ALB WAF logs in Basic concepts of the ALB WAF.

Metrics

Metrics provide aggregated data to monitor the overall health and performance of the Application Load Balancer, including request counts, latency, error rates, and resource utilization.

Enabling logs and metrics

To enable logs and metrics for the Application Load Balancer, attach an Observability instance and configure the following two settings on the ALB per stream (logs and metrics):

• credentialsRef: Reference to a technical credential (basic authentication username and password) that authorizes the ALB to write to the Observability instance. You create the credential inside the Observability instance itself; the ALB only stores the reference.
• pushUrl: Remote-write endpoint URL of the Observability instance that receives the stream. The host is region- and instance-specific and is exposed by the Observability instance detail page.

Push URL patterns

The pushUrl for each stream follows a stable pattern per Observability instance:

Stream	pushUrl pattern
Logs	https://logs.<region-cluster>.argus.<region>.stackit.cloud/instances/<instance-id>/loki/api/v1/push
Metrics	https://push.metrics.<region-cluster>.argus.<region>.stackit.cloud/instances/<instance-id>/api/v1/receive

<region-cluster> and <region> are provisioned per Observability instance (for example, eu01). Always copy the concrete URL from the Observability instance rather than composing it by hand — the exact host prefix can vary per instance and region.

To copy the concrete URLs for your instance, open the Observability instance detail page in the STACKIT Portal, or query the instance via the Observability API. The full walkthrough is in Locating your identifiers and Endpoint URLs.

Credentials

The ALB does not create Observability credentials — it references a technical credential that already exists on the Observability instance. You can create the credential using any of these tools, they are equivalent:

• STACKIT Portal: Observability → your instance → API credentials.
• STACKIT CLI: stackit observability credentials create ....
• STACKIT Terraform Provider: stackit_observability_credential resource.
• Observability API: POST to the credentials endpoint of the instance.

Whichever tool you use, the credential name you enter in credentialsRef on the ALB must match exactly the credential name that exists on the Observability instance. If the names diverge, the ALB fails to authenticate against the push endpoint.

For step-by-step credential creation, see Obtaining Technical Credentials.

For the full ALB request body (including the observability block), see the v2 API — Application Load Balancer reference.