> For the complete documentation index, see [llms.txt](https://docs.helmut.de/helmut4-releases/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helmut.de/helmut4-releases/v4.13.0/getting-started/additional-configurations/communication-ssl-proxy-and-ports/load-balancers/aws-application-load-balancer-alb.md). # AWS Application Load Balancer (ALB) An AWS Application Load Balancer (ALB) can be used as a reverse proxy in front of Helmut4. The ALB provides a single access point for clients, handles HTTP and HTTPS traffic, terminates SSL/TLS, and forwards valid requests to the Helmut4 backend system. This guide describes the recommended ALB settings for correct communication with Helmut4. *** ## Example Architecture A typical setup looks like this: ``` Client ↓ DNS name, for example helmut.example.com ↓ AWS Application Load Balancer ↓ HTTPS listener :443 ↓ Listener rule ↓ Target group ↓ Helmut4 backend ``` The ALB should be configured with: ``` HTTP listener: 80 HTTPS listener: 443 Target group: Helmut4 backend on the correct HTTPS port Health check: /v1/fx/version ``` *** ## Load Balancer Configuration Create an **Application Load Balancer**. Recommended settings: ``` Type: Application Load Balancer Scheme: Internal or Internet-facing IP address type: IPv4 ``` #### Scheme Use **Internal** if Helmut4 is only accessed from inside AWS, through VPN, or through private company networks. Use **Internet-facing** only if Helmut4 must be reachable from the public internet. #### DNS Name The ALB receives its own AWS DNS name. In most environments, users should not access this DNS name directly. Instead, create a dedicated DNS record, for example: ``` helmut.example.com ``` and point it to the ALB DNS name. The DNS name used by clients must match the SSL/TLS certificate configured on the HTTPS listener. *** ### Listener Configuration The ALB should provide two listeners: ``` HTTP:80 HTTPS:443 ``` *** ### HTTP Listener The HTTP listener should redirect all incoming traffic to HTTPS. Recommended settings: ``` Protocol: HTTP Port: 80 Default action: Redirect to HTTPS Redirect protocol: HTTPS Redirect port: 443 Status code: HTTP_301 ``` This ensures that clients always communicate with Helmut4 over HTTPS. Example behavior: ``` http://helmut.example.com → https://helmut.example.com ``` *** ### HTTPS Listener The HTTPS listener handles encrypted client traffic and forwards valid requests to the Helmut4 target group. Recommended settings: ``` Protocol: HTTPS Port: 443 SSL/TLS certificate: Certificate matching the Helmut4 DNS name Security policy: Company-approved TLS policy ``` The certificate is usually provided through **AWS Certificate Manager (ACM)**. Example: ``` DNS name: helmut.example.com Certificate: helmut.example.com or *.example.com ``` *** ### HTTPS Listener Rules Configure a listener rule that forwards Helmut4 traffic to the Helmut4 target group. Recommended rule: ``` Condition: HTTP Host Header is helmut.example.com Action: Forward to target group helmut Priority: 1 ``` This ensures that only requests for the configured Helmut4 DNS name are forwarded to the Helmut4 backend. A default rule can be used to return a fixed response if no condition matches. Example default response: ``` Response code: 404 Content-Type: text/plain ``` This is useful to prevent unrelated hostnames or direct ALB requests from being forwarded to Helmut4. *** ### Target Group Configuration Create a target group for the Helmut4 backend. Recommended settings: ``` Target type: Instance or IP Protocol: HTTPS Port: 443 ``` Use the protocol and port that match your Helmut4 environment. Example target: ``` Target: helmut-server-01.example.com Port: 443 ``` If Helmut4 is running behind Traefik or another reverse proxy, make sure the target group points to the externally exposed HTTPS port of that proxy. For example, if Traefik exposes HTTPS on a custom port, the target group must use that port instead of `443`. *** ### Health Check Configuration Configure the target group health check to verify that Helmut4 is reachable. Recommended settings: ``` Protocol: HTTPS Path: /v1/fx/version Port: traffic port Success codes: 200 ``` The health check should return a successful HTTP response when the Helmut4 service is available. If the target does not pass the health check, the ALB marks it as unhealthy and stops forwarding traffic to it. *** ### SSL/TLS Handling In this setup, SSL/TLS is terminated at the ALB. This means: ``` Client → ALB: HTTPS ALB → Helmut4 target: HTTPS ``` The ALB presents the public certificate to the client. The backend connection from the ALB to Helmut4 also uses HTTPS when the target group protocol is set to `HTTPS`. Make sure that the Helmut4 backend accepts HTTPS traffic on the configured target port. *** ### Security Group Configuration The ALB security group must allow incoming client traffic. Recommended inbound rules for the ALB: ``` TCP 80 from allowed client networks TCP 443 from allowed client networks ``` The Helmut4 target security group must allow traffic from the ALB security group. Recommended inbound rule for the Helmut4 target: ``` TCP 443 from ALB security group ``` If a custom backend port is used, replace `443` with the configured target port. Avoid exposing the Helmut4 target directly unless required by your architecture. *** ### Important Port Note If Helmut4 and another reverse proxy, such as Traefik, are running on the same host as another load balancer or proxy, make sure there are no port conflicts. Please refer to [Change HTTP/HTTPS Ports](/helmut4-releases/v4.13.0/getting-started/additional-configurations/communication-ssl-proxy-and-ports/change-http-https-ports.md) For example, if another service already uses ports `80` and `443`, the exposed ports of the Helmut4 Traefik container may need to be changed. The ALB target group must then point to the adjusted external port. Example: ``` Traefik HTTPS exposed port: 8443 ALB target group port: 8443 ``` Add this section after **Load Balancer Configuration** or before **Listener Configuration**: *** ## Load Balancer Attributes In addition to the listener and target group configuration, the following ALB attributes are important for Helmut4 communication. Recommended settings: ``` HTTP/2: On HTTP client keepalive duration: 3600 seconds Connection idle timeout: 4000 seconds Preserve host header: On X-Forwarded-For header: Append Drop invalid header fields: Off Client port preservation: Off Cross-zone load balancing: On ``` ### Preserve Host Header This setting should be enabled. ``` Preserve host header: On ``` Helmut4 may rely on the original host name used by the client. Preserving the host header ensures that the backend receives the same host name that was used when accessing the ALB, for example: ``` helmut.example.com ``` Without this setting, the backend may receive a modified host header, which can cause incorrect redirects, URL generation issues, or communication problems. ### Connection Idle Timeout The connection idle timeout should be set high enough for long-running Helmut4 requests. Recommended value: ``` Connection idle timeout: 4000 seconds ``` This helps prevent the ALB from closing idle connections too early during longer operations. ### HTTP Client Keepalive Duration Recommended value: ``` HTTP client keepalive duration: 3600 seconds ``` This allows client connections to stay open and be reused, reducing connection overhead. ### X-Forwarded-For Header Recommended setting: ``` X-Forwarded-For header: Append ``` This allows Helmut4 or upstream services to identify the original client IP address. The ALB appends the client IP to the `X-Forwarded-For` header before forwarding the request to the backend. ### HTTP/2 Recommended setting: ``` HTTP/2: On ``` HTTP/2 can remain enabled on the ALB client side. The ALB handles the client connection and forwards the request to the configured Helmut4 target group. ### Cross-Zone Load Balancing Recommended setting: ``` Cross-zone load balancing: On ``` This allows the ALB to distribute traffic across targets in different Availability Zones, depending on the configured target group and backend availability. *** You can also add this compact note to the **Summary** section: ``` Important ALB attributes: Preserve host header: On Connection idle timeout: 4000 seconds HTTP client keepalive duration: 3600 seconds X-Forwarded-For header: Append HTTP/2: On Cross-zone load balancing: On ``` *** ## Optional: Fixed Response for Unmatched Requests It is recommended to configure a default fixed response on the HTTPS listener for requests that do not match the Helmut4 host header. Example: ``` Default action: Return fixed response Response code: 404 Content-Type: text/plain ``` This avoids forwarding unwanted traffic to Helmut4. *** ## How the Setup Works Clients connect to the Helmut4 DNS name: ``` https://helmut.example.com ``` The DNS record points to the AWS Application Load Balancer. The ALB listens on ports `80` and `443`. Traffic on port `80` is redirected to HTTPS on port `443`. Traffic on port `443` is handled by the HTTPS listener. The listener checks the configured rules and forwards matching requests to the Helmut4 target group. The target group sends the request to the configured Helmut4 backend target. *** ## Summary For a standard Helmut4 ALB setup, configure: ``` ALB type: Application Load Balancer Scheme: Internal or Internet-facing, depending on access requirements HTTP listener: Port 80, redirect to HTTPS 443 HTTPS listener: Port 443, with a valid SSL/TLS certificate Listener rule: Forward matching Helmut4 host header to the target group Default HTTPS action: Fixed 404 response for unmatched requests Target group: HTTPS target using the correct Helmut4 port Health check: /v1/fx/version Security groups: Allow clients to ALB, and ALB to Helmut4 ``` Replace all placeholder DNS names and ports, such as: ``` helmut-server-01.example.com:443 ``` with the actual DNS names, IP addresses, and external ports used in your environment.