Skip to navigation

SSL and TLS termination

TLS (Transport Layer Security, the newer name for SSL) is an encryption standard: it is what puts the s in https:// and the padlock in the browser. TLS termination means the load balancer decrypts the traffic and needs a certificate for your site. TLS passthrough means the load balancer forwards the encrypted traffic unopened, and your own server decrypts it with its own certificate.

When to use each mode

ModeProtocol to chooseWho holds the certificateClients connect toUse it when
TerminateLayer 7 HTTPSIBEE issues and renews it for youPort 443You run a website or API and want HTTPS without managing certificates. Most users want this.
PassthroughLayer 4 TLS passthroughYour backend serversPort 8443Your servers must decrypt the traffic themselves, for example for compliance, or they use client certificates
NoneLayer 7 HTTP or Layer 4 TCPNobodyPort 80, or the TCP port IBEE assignsTesting, or traffic that your app already encrypts

Only Terminate lets the load balancer read requests, so path and header rules work only with HTTP and HTTPS.

How it works

Terminate (L7 HTTPS):

  1. The client opens https:// to the load balancer’s hostname, or to your own domain.
  2. The load balancer presents a certificate that IBEE manages, and decrypts the request.
  3. It forwards the request to a backend without encryption, over plain HTTP to the backend’s port.
  4. It encrypts the backend’s answer and sends it to the client.

Passthrough (L4 TLS passthrough):

  1. The client connects to the load balancer’s hostname on port 8443 and starts a TLS handshake.
  2. The load balancer reads only the hostname the client asks for in the handshake (called SNI, Server Name Indication) and forwards the encrypted connection to a backend.
  3. The backend presents its own certificate and decrypts the traffic. The load balancer never sees the content.

Traffic between the load balancer and your backends is not encrypted. The Encrypt traffic from the load balancer to this backend option is saved, but not applied yet. If that hop must be encrypted, use TLS passthrough, so that only your backend decrypts the traffic.

Before you begin

  • A verified organization and room in your plan for another load balancer. See Create a load balancer.
  • Backends that serve plain HTTP on their port, for Terminate. For Passthrough, backends that serve TLS and hold a certificate.
  • For your own domain: access to your domain’s DNS settings, and an API token with load-balancer.write. The portal has no custom domain field yet.

Create an HTTPS load balancer in the portal

1

Open the create form

Under Network & Security, click Load Balancer, then Create Load Balancer.

2

Choose the protocol

Set Layer to Layer 7 and Protocol to HTTPS (“Terminate TLS with a managed certificate.”). These are the defaults.

For passthrough instead, set Layer to Layer 4 and Protocol to TLS passthrough (“Preserve end-to-end TLS without termination.”).

3

Add backends

Enter each backend’s address and the port where it serves plain HTTP, for example 8080. Leave Encrypt traffic from the load balancer to this backend unticked.

4

Create

Fill in the rest of the form and click Create Load Balancer. The detail page shows the Public host, for example https://3f9c2b7e-….lb.ibee.ai.

Verify

Open the Public host URL in a browser and check for the padlock, or run:

curl -v https://3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai/ 2>&1 | grep -E "subject:|issuer:|HTTP/"

You should see the certificate’s subject and issuer, then your app’s HTTP status.

For TLS passthrough, check that your backend’s certificate is presented:

openssl s_client -connect 3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai:8443 \
-servername 3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai </dev/null | head -20

Use your own domain

An L7 HTTPS load balancer can also answer on one domain of yours, such as shop.example.com, with a certificate IBEE issues for that domain automatically. This is available through the API only.

1

Create the CNAME record first

At your DNS provider, create a CNAME record for your domain that points directly to cname.lb.ibee.ai:

TypeNameTarget
CNAMEshop (for shop.example.com)cname.lb.ibee.ai

IBEE checks this record when you send the request, so it must exist and resolve first. Check it with dig +short CNAME shop.example.com, which should print cname.lb.ibee.ai.

2

Add the domain to the load balancer

curl -X PATCH "https://api.ibee.ai/v1/networking/load-balancers/l7/3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c?workspace_id=710995" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"custom_domain": {"hostname": "shop.example.com"}}'

You can also send custom_domain in the create request (POST /networking/load-balancers/l7).

3

Check the detail page

The Public endpoint section now also shows Custom domain and CNAME target. IBEE requests the certificate for your domain automatically; after it is issued, https://shop.example.com serves your app.

A domain can belong to only one load balancer. A root domain such as example.com usually can’t have a CNAME record at most DNS providers, so use a subdomain such as www or shop.

Certificates

  • IBEE manages every certificate. You don’t upload or renew it.
  • You can’t upload your own certificate yet. The API’s "certificate_source": "custom" with cert_pem and key_pem is refused.
  • TLS passthrough needs your certificate on every backend. The load balancer picks the backend by the hostname the client sends (SNI), and it matches only the load balancer’s own hostname. Clients must connect to that hostname, so the backends’ certificate must be valid for it, or the clients must be set up to trust it.

Limits

ItemValue
HTTPS port (Terminate)443
TLS passthrough port8443
Custom domains1 per L7 HTTPS load balancer; up to 253 characters
Custom domain on HTTP, TCP or TLS passthroughNot available
Longest request through an HTTPS load balancer30 seconds by default; set 100–300,000 ms as the Request timeout
Your own certificateNot available
Encryption from the load balancer to backendsNot applied yet

Security tips

  • Don’t send passwords or personal data over the HTTP protocol. Use HTTPS so traffic is encrypted between the client and the load balancer.
  • The hop from the load balancer to your backends is unencrypted, and it reaches them at their public addresses. When data must stay encrypted all the way to your server, use passthrough.

Troubleshooting

You seeWhat it meansWhat to do
400 “custom domain ‘shop.example.com’ does not exist in DNS”The domain has no DNS records yetCreate the CNAME record, wait for it to resolve, then send the request again.
400 “custom domain ‘shop.example.com’ must have a CNAME record to ‘cname.lb.ibee.ai‘“The domain resolves, but not through a CNAME (for example it has an A record)Replace the record with a CNAME to cname.lb.ibee.ai.
400 “custom domain ‘shop.example.com’ must point directly to ‘cname.lb.ibee.ai’, found ‘other.example.net‘“The CNAME points somewhere else, or through another CNAME firstPoint the record straight at cname.lb.ibee.ai. Turn off any DNS proxy for this record.
409 “custom domain ‘shop.example.com’ is already in use”Another load balancer already has this domainRemove it from the other load balancer first, or use another subdomain.
”custom_domain is only supported for l7 https load balancers”The load balancer is HTTP or Layer 4Create an L7 HTTPS load balancer.
”custom certificate_source is not yet supported for shared HTTPS listener reconciliation”You sent "certificate_source": "custom"Leave out certificate_source; IBEE manages the certificate.
The browser warns about the certificate on your domainThe certificate for your domain isn’t issued yet, or the CNAME changedCheck the CNAME with dig, then try again later. If it lasts, contact support.
Errors such as 400, 502 or 503 on an HTTPS load balancer whose backends only serve HTTPSThe load balancer talks plain HTTP to the backendsServe plain HTTP on the backend port, or use TLS passthrough.
Passthrough clients report a certificate name mismatchThe backend’s certificate doesn’t cover the load balancer’s hostnameIssue the backend certificate for that hostname, or configure the clients to trust it.