LiteSwitch Ingress Proxy

General Information

LiteSwitch is a traffic-optimization product for programmatic advertising. It runs as a Docker container inside an AdTech platform’s own infrastructure and applies machine-learning decisioning to OpenRTB bid traffic — recommending which demand partners should receive each request, shaping request volume against configured limits, and optimizing floor and bid prices. The goal is to reduce wasteful bid traffic and infrastructure cost while protecting revenue and win rates.

This guide covers running LiteSwitch in ingress proxy mode, where LiteSwitch sits inline on the bid-request path and forwards optimized traffic to your downstream endpoint. It walks through prerequisites, container setup, health checks, traffic testing, and day-to-day operations.

Use this setup when LiteSwitch must sit inline in the bid-request path:

../_images/lsw-ingress-proxy.png

Glossary

Term

Definition

Client Platform

Any AdTech platform (Buyer, Supplier, Exchange) in the middle of the chain that hosts LiteSwitch

QPS

Queries Per Second - request rate used to size the deployment

Ingress Proxy

The deployment mode where LiteSwitch sits inline and forwards requests downstream

OPD

Optimized Price Discovery — adjusts the reported price on winning bids (see below)

in_ba / out_ba

The bid price before / after OPD optimization

Yes-bid

A win notification used to keep LiteSwitch models current

Docker container

The packaged, runnable LiteSwitch instance deployed in client infrastructure

Load Balancer

Service that routes bid traffic across LiteSwitch containers

What Ingress Proxy Does

LiteSwitch receives OpenRTB bid requests, applies LiteSwitch decisioning, forwards the allowed request to the downstream Supplier bidding endpoint, and returns the downstream response to the original caller.

Runtime behavior relevant to the integration:

  • LiteSwitch forwards only the request headers enabled for the integration.

  • LiteSwitch returns only the response headers enabled for the integration.

  • LiteSwitch adds X-LiteSwitch-Proxy: 1 to forwarded requests.

  • LiteSwitch returns HTTP 204 when there is no bid response to return.

  • LiteSwitch returns an error response when the downstream endpoint cannot be reached or returns an invalid response.

  • When Optimized Price Discovery (OPD) is enabled for the integration, LiteSwitch can rewrite the reported price on winning bids in the response

Prerequisites

The client-hosted environment needs:

  • x86 or ARM Linux hosts or VMs with Docker installed

  • at least 8 CPU cores and 8 GB RAM per container host

  • outbound access to: - the container registry supplied by LiteSwitch - the LiteSwitch configuration endpoint supplied by LiteSwitch - the configured LiteSwitch data, metrics, and log destinations - the downstream Supplier bidding endpoint

  • inbound traffic from the client load balancer to the LiteSwitch traffic port, default 43539

  • private health-check and metrics access to the LiteSwitch agent port, default 42285

Do not expose port 42285 publicly unless the network policy restricts it to trusted monitoring systems.

Information Supplied By LiteSwitch

LiteSwitch will provide:

  • container image reference and tag

  • registry authentication instructions

  • LSW_ONPREM_SSP_ID

  • LSW_ONPREM_BACKEND_HOST

  • LSW_ONPREM_API_KEY

  • LSW_ONPREM_AUTH_PASSWORD

  • required LSW_ONPREM_LOCATION value for each deployment location

  • request and response headers enabled for the integration

Keep these values private. Do not commit them to source control.

Docker Registry Login

Follow the registry login instructions supplied by LiteSwitch If LiteSwitch provides a service account key for registry access, the login flow is:

mkdir -p "$HOME/.config/gcloud"
vi "$HOME/.config/gcloud/liteswitch_onprem_scout.json"
# paste the scout service account key into the file

gcloud auth activate-service-account \
  --key-file="$HOME/.config/gcloud/liteswitch_onprem_scout.json"

gcloud auth configure-docker us-east1-docker.pkg.dev

Pull the image supplied by LiteSwitch:

docker pull us-east1-docker.pkg.dev/iow-liteswitch/uverse-docker-local/tenant/liteswitch/liteswitch-onprem/releases:x.y.z

Use the exact image reference and tag provided for the deployment. You can pin a cut tag such as releases:x.y to receive the latest patch (z) version automatically.

Agent Environment File

Create agent.env on each host.

Minimum ingress proxy example:

LSW_ONPREM_SSP_ID=<client_ssp_id>
LSW_ONPREM_BACKEND_HOST=<liteswitch_config_host>
LSW_ONPREM_API_KEY=<api_key>
LSW_ONPREM_AUTH_PASSWORD=<auth_password>
LSW_ONPREM_LOCATION=<region_or_pool_id>
LSW_ONPREM_INGRESS_PROXY_ROUTES={"/broker/bid":"https://downstream-ssp.example.com"}

Use the exact downstream endpoint and route paths agreed for the integration.

Rules:

  • LSW_ONPREM_INGRESS_PROXY_ROUTES must be a single-line JSON object.

  • Every route key must start with /.

  • Every route key must contain at least two characters.

  • Route values are downstream origins, for example https://bidder.example.com.

  • LiteSwitch forwards to route value + original request URL.

  • If the load balancer rewrites paths, configure routes for the path LiteSwitch receives after rewriting.

  • Define /broker/bid explicitly if client traffic uses /broker/bid.

Running The Container

Run the container:

docker run \
  --env-file agent.env \
  --name liteswitch-ingress \
  --detach \
  --pull always \
  --restart unless-stopped \
  -p 43539:43539 \
  -p 127.0.0.1:42285:42285 \
  us-east1-docker.pkg.dev/iow-liteswitch/uverse-docker-local/tenant/liteswitch/liteswitch-onprem/releases:x.y.z

Port 43539 is the traffic port. Port 42285 is shown bound to localhost for same-host health checks and metrics; bind it to a private monitoring interface instead if checks come from a load balancer or monitoring network.

Keep the public load balancer pointed only at port 43539.

Check logs:

docker logs liteswitch-ingress -f

Wait for the Started onprem agent service server on port 42285 log line. The container is ready to process requests once curl http://localhost:43539/status returns OK.

Health Checks

The /status handler reports container health on both the traffic port (43539) and the agent port (42285). When the server is ready it responds with OK. Use it at launch to confirm readiness and for ongoing health checks.

Agent port:

curl -fsS http://localhost:42285/status

Traffic port:

curl -fsS http://localhost:43539/status

Expected response:

OK

To prevent resource exhaustion, the server applies failed-save logic: under load it drops a small share of requests (5% by default) and responds with HTTP 503 and body ServiceUnavailable: too many requests. Set up monitoring and autoscaling on your side; the LiteSwitch team can provide server metrics, including the volume of dropped requests, on request.

If port 42285 is not published to the host, run health checks from the container network or bind the port to a private interface.

Traffic Test

Send a test request to the configured route:

curl -i \
 -X POST "http://localhost:43539/broker/bid" \
 -H "Content-Type: application/json" \
 -H "X-Openrtb-Version: 2.5" \
 --data @sample-openrtb-request.json

Expected outcomes:

  • HTTP 200 with the downstream bid response when there is a bid response to return.

  • HTTP 204 when there is no bid response to return.

  • HTTP 503 when LiteSwitch cannot call the downstream endpoint or the service is not ready.

Validate that the downstream endpoint receives X-LiteSwitch-Proxy: 1 and the expected forwarded headers.

Load Balancer Routing

The client load balancer should:

  • route bid traffic to port 43539

  • use GET /status on port 42285 for health checks

  • preserve the request URI expected by LSW_ONPREM_INGRESS_PROXY_ROUTES

  • preserve the OpenRTB headers agreed for the integration

  • remove unhealthy containers from rotation before draining or replacing hosts

If the load balancer rewrites paths, keep the route map aligned with the post-rewrite path that LiteSwitch receives.

Operations

Changes that usually require a container restart:

  • Docker image tag changes

  • agent.env changes

  • host port mappings

  • network policy changes

Scale horizontally by adding containers to the pool behind the load balancer. The number of instances depends on the instance type and the number of ad slots and buyer seats (wseats) per request; Google N2 and N2D instances give optimal QPS per core.

Troubleshooting

Container exits during startup

Check logs:

docker logs liteswitch-ingress --tail 200

Common causes:

  • missing LSW_ONPREM_BACKEND_HOST

  • missing LSW_ONPREM_SSP_ID

  • missing LSW_ONPREM_LOCATION

  • malformed LSW_ONPREM_INGRESS_PROXY_ROUTES

  • credentials supplied to the container are invalid

  • the container cannot reach required outbound endpoints

Route returns 503

Check:

  • the route exists in LSW_ONPREM_INGRESS_PROXY_ROUTES

  • the route value is reachable from inside the container

  • downstream TLS certificates are valid for the host

  • downstream endpoint returns a valid response for valid requests

  • LiteSwitch health check returns OK

Downstream does not receive expected headers

Confirm that the client load balancer preserves those headers and contact LiteSwitch support to confirm they are enabled for forwarding.

Client does not receive expected response headers

Contact LiteSwitch support to confirm those headers are enabled in the response header allowlist for the integration.

Wrong regional configuration is loaded

Check that LSW_ONPREM_LOCATION matches the deployment location value supplied by LiteSwitch exactly.