selenium/keda-external-scaler

Selenium Grid KEDA External Scaler

This image provides a standalone KEDA external scaler for Selenium Grid. It is a gRPC server that reads the Grid's GraphQL state and tells KEDA how many browser Nodes it should scale to.

It is a functional extraction of KEDA's built-in selenium-grid scaler, so that Selenium's autoscaling logic can be released on the docker-selenium cadence instead of KEDA's. The scaling algorithm — capability matching (mirroring the Grid's DefaultSlotMatcher), slot reservation and the on-going session count conventions — is ported verbatim from upstream and is covered by KEDA's own test table.

How it differs from the built-in scaler

The behaviour is identical. The only user-visible change is the trigger wiring:

The credential difference matters: KEDA does not forward TriggerAuthentication authParams to external scalers. The Grid URL and credentials therefore have to reach the scaler another way (see below).

Use trigger type external, not external-push — the Grid exposes no push signal, so StreamIsActive is deliberately unimplemented.

How to run this image

The Selenium Grid Helm chart wires this scaler up for you when autoscaling.enabled=true; see the chart https://github.com/SeleniumHQ/docker-selenium/blob/trunk/charts/selenium-grid/CONFIGURATION.md. To deploy it by hand:

bash
docker pull selenium/keda-external-scaler:4.48.0-20260905

yaml
# Deployment (excerpt) — the scaler serves gRPC on :8080
containers:
  - name: selenium-grid-scaler
    image: selenium/keda-external-scaler:4.48.0-20260905
    ports:
      - containerPort: 8080
    env:
      - name: SE_GRID_URL
        value: http://selenium-router:4444/graphql
    readinessProbe:
      grpc:
        port: 8080

yaml
# ScaledObject / ScaledJob trigger (excerpt)
triggers:
  - type: external
    metadata:
      scalerAddress: selenium-grid-scaler.selenium.svc.cluster.local:8080
      url: http://selenium-router:4444/graphql
      browserName: chrome
      nodeMaxSessions: "1"

Reference manifests for both ScaledObject and ScaledJob live in https://github.com/SeleniumHQ/docker-selenium/tree/trunk/.keda-external-scaler/deploy. The scaler exposes the standard gRPC health service (grpc.health.v1.Health), so Kubernetes grpc probes work out of the box.

Trigger metadata

All keys mirror the built-in scaler, plus scalerAddress, which KEDA consumes itself:

Any key may also be supplied as <key>FromEnv, which KEDA resolves from the scale target's container environment before sending it.

On-going sessions

The metric this scaler returns is the number of Nodes the Grid needs. On-going sessions are work the Grid is already serving, so whether they belong in that number depends on which count KEDA's executor already deducts for you:

accurate and eager never re-add running work, so counting on-going sessions there double-counts sessions already in progress and produces runaway Node creation that never scales back down. The Selenium Grid Helm chart derives this for you from autoscaling.scaledJobOptions.scalingStrategy.strategy; set <node>.hpa.includeOngoingSessions to override it.

Authentication

Because authParams are not forwarded to external scalers, resolve the Grid URL and credentials by one of the following (highest precedence first, per key):

1. Trigger metadata — url, username, password, accessToken directly in the trigger metadata. Visible in the ScaledObject, so fine for the URL, best avoided for secrets.
2. *FromEnv metadata — for example usernameFromEnv: SE_ROUTER_USERNAME; KEDA resolves it from the scale target's container environment.
3. Scaler environment — mount the secret into this Deployment as SE_GRID_URL, SE_GRID_AUTH_TYPE, SE_USERNAME, SE_PASSWORD, SE_ACCESS_TOKEN. This keeps secrets out of the ScaledObject entirely.

Runtime flags

Setting both TLS flags serves the gRPC endpoint over TLS; KEDA connects with enableTLS / caCert on its side.

How to choose the correct tag for you

This image follows the same release convention as the other Grid components, so it is tagged with the Selenium Grid version:

selenium/keda-external-scaler-<Major>.<Minor>.<Patch>-<YYYYMMDD>

Example of a release with Selenium Grid Server 4.48.0, released on 20260909

    Selenium Server 4.48.0
    Release date 20260909


e126989f151e        selenium/keda-external-scaler   4
e126989f151e        selenium/keda-external-scaler   4.48
e126989f151e        selenium/keda-external-scaler   4.48.0
e126989f151e        selenium/keda-external-scaler   4.48.0-20260909

Besides that, you also can use image tag latest or nightly.

Further reading: the scaler's own https://github.com/SeleniumHQ/docker-selenium/blob/trunk/.keda-external-scaler/README.md and the Selenium Grid chart https://github.com/SeleniumHQ/docker-selenium/blob/trunk/charts/selenium-grid/CONFIGURATION.md.

Full documentation

The Docker-Selenium project in GitHub has an extensive https://github.com/SeleniumHQ/docker-selenium that will help you find the correct way to get this images up and running for your use case.

License

The project is made possible by volunteer contributors who have put in thousands of hours of their own time, and made the source code freely available under the https://raw.githubusercontent.com/SeleniumHQ/selenium/trunk/LICENSE.