LiteSwitch Ingress Proxy

This document explains how to deploy and operate LiteSwitch in Ingress Proxy mode in a client-hosted environment. Use this mode when LiteSwitch must sit inline on the bid request path between the caller and your downstream Supplier bidding endpoint.

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

For the common container bootstrap flow, this guide follows the same structure as LiteSwitch SSP-hosted setup guide. The ingress-specific parts are the downstream route map and load-balancer routing.

Prerequisites

The client-hosted environment requires the following:

  • 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 SSP 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

Warning

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

The following resources and values are provided by LiteSwitch:

  • 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_registry.json"

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

gcloud auth configure-docker <registry-host>

Pull the image supplied by LiteSwitch:

docker pull <image-ref>:<tag>

Use the exact image reference and tag provided for the deployment.

Agent Environment File

Create .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.

Please make sure the following requirements are met:

  • 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 URI.

  • 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 \
  <image-ref>:<tag>

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

The container is ready after the agent status endpoint returns OK.

Health Checks

Agent health:

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

Expected response: OK

Metrics endpoint:

curl -fsS http://localhost:42285/agent/metrics

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 /agent/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

For image upgrades, create a new pool of containers, verify health, shift traffic, and then remove the old pool.

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.