Deploying Grid with Containers, Kubernetes, and Cloud Infrastructure: Diagnostics, Failure Modes, and Production Practices

1. Diagnostic sequence for containerized Grid

1. Preserve the first failing test evidence and container/Grid logs.
2. Record Selenium client, Grid image tag, returned browser capabilities, Docker/Compose/Kubernetes versions.
3. Confirm target URL, synthetic data, and environment selection.
4. Confirm session ID, current URL, browser context, and Grid readiness.
5. Check DNS/TCP reachability from the browser runtime to the AUT.
6. Check AUT/browser/network evidence.
7. Check Grid queue, Node health, container/pod restarts, CPU/memory/shared memory, disk, and artifact growth.
8. Apply the least destructive correction and rerun the smallest scenario.

2. Broken example: host/localhost confusion

This variant is intentionally wrong:

The following example makes the Broken example: host/localhost confusion behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

from selenium import webdriver
from selenium.webdriver.common.by import By

with webdriver.Remote("http://127.0.0.1:4444", options=webdriver.ChromeOptions()) as driver:
    # BROKEN: localhost is the browser container itself.
    driver.get("http://127.0.0.1:8000/")
    assert driver.find_element(By.CSS_SELECTOR, "[data-testid=status]").text == "container-grid-ok"

The session can be created successfully, proving the host-to-Grid path works. Navigation then fails or lands nowhere useful because the browser resolves loopback inside its own container. The correct repair in the Compose lab is http://aut:8000/. Preserve the navigation exception and Grid/container logs before changing anything.

3. Prove network state from the right namespace

The following example makes the Prove network state from the right namespace behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

docker compose ps
docker network inspect selenium-ch20-lab
# Inspect DNS/network configuration without installing ad-hoc tools into the browser image:
docker inspect selenium-ch20-lab-selenium-1 --format '{{json .NetworkSettings.Networks}}' 2>/dev/null || true
docker compose logs --no-color aut | tail -n 40

Do not mutate a production browser container by installing curl/debug packages during an incident. Prefer orchestration metadata, logs, a disposable debug container on the same network, or application-side access logs.

4. Incompatible image/version assumptions

A Grid image tag is a bundle, not just a browser label. If CI uses a different tag than local development, compare the actual image ID, Grid status, and returned capabilities. Do not “fix” version skew by manually replacing a driver binary inside an official container. Upgrade/downgrade the image as a unit unless the official image contract explicitly supports your customization.

docker compose images
docker inspect --format '{{.Config.Image}} {{.Image}}' selenium-ch20-lab-selenium-1 2>/dev/null || true
curl -fsS http://127.0.0.1:4444/status

5. Shared memory, CPU, memory, disk, and session overcommit

Browser renderer crashes under container pressure can produce WebDriver disconnections, session deletions, or blank-page symptoms. The official browser images recommend shm_size: 2gb. That is not permission to run unlimited sessions. A host with insufficient CPU/memory/disk will still fail.

docker stats --no-stream
docker system df
docker compose ps

6. Artifact growth and secret leakage

Videos, downloads, page source, browser logs, and URLs may contain tokens or PII. Per-session names prevent collisions, but they do not make content safe. Bound collection, redact before persistence when possible, restrict access, and expire artifacts. Never pass cloud/API secrets as plain environment variables if your platform exposes them in logs or inspection output; use your CI/Kubernetes secret mechanism and avoid echoing values.

7. Kubernetes readiness is not browser readiness

A ready pod means its readiness probe passed. It does not prove a matching browser slot is free, a session can be created, the browser can reach the AUT, or the AUT is ready for the next interaction. Treat these as different state machines and correlate them by timestamps/session ID.

8. Production runbook boundaries

For a real incident, attach: image tags/digests, Grid status, session ID/capabilities, relevant container/pod restart/resource state, browser/AUT error evidence, sanitized network endpoints, and CI run/attempt ID. Do not delete failed artifacts just because a retry later passes. Do not restart the entire cluster before preserving state unless safety/availability requires it.

Knowledge check

Official references and current-version notes

• SeleniumHQ/docker-selenium — official images, Compose, Dynamic Grid, troubleshooting
• Docker Selenium 4.47.0-20260808 release
• Official Selenium Grid Helm chart
• Selenium Grid documentation
• Grid CLI/configuration options