browser-controller

• Group/Version: browser.selenosis.io/v1 · Kind: Browser · Scope: Namespaced
• Resource: browsers · Short name: brw · Categories: selenosis
• Status subresource: enabled (/status)

Printer columns: Browser (.spec.browserName), Version (.spec.browserVersion), Phase (.status.phase), PodIP (.status.podIP), StartTime (.status.startTime), Age.

Spec

• browserName (string, required, minLength=1) — e.g. chrome, firefox.
• browserVersion (string, required, minLength=1) — e.g. 120.0, or latest if supported.

Status (populated by the controller)

• podIP (string) — IP assigned to the pod.
• phase (PodPhase) — Pending / Running / Succeeded / Failed / Unknown.
• message (string) — human-readable condition description.
• reason (string) — short machine reason (e.g. Evicted).
• startTime (Time) — when the pod started.
• containerStatuses (array) — per-container name, state, image, restartCount, ports.

kubectl get brw
kubectl describe brw <name>
kubectl get brw <name> -o yaml

BrowserConfig centrally manages defaults (template) and overrides them per browser name and version. Group/Version browserconfig.selenosis.io/v1, Kind BrowserConfig, namespaced, /status subresource enabled.

spec.template — base pod config applied to all browsers/versions unless overridden. Supported fields (all optional): labels, annotations, env, resources, imagePullPolicy, volumes, volumeMounts, nodeSelector, affinity, tolerations, hostAliases, initContainers, sidecars, privileged, imagePullSecrets, dnsConfig, securityContext, command, args, workingDir.

sidecars must include seleniferous. Every browser pod carries the sidecar proxy that terminates all session traffic; the hub proxies to it and never to the browser directly. The container name is reserved — the controller recognises browser and seleniferous by name and treats the termination of either as fatal for the Browser — so renaming it is not supported. Declare it once in spec.template.sidecars and every browser version inherits it:

template:
  sidecars:
  - name: seleniferous
    image: alcounit/seleniferous:v2.0.8
    env:
    - name: POD_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP

Nothing validates this today: a config without the sidecar is accepted and its pods are created, but sessions against them never come up.

spec.browsers — required map of browser-specific, version-specific config:

browsers:
  chrome:
    "120.0":
      image: selenium/standalone-chrome:120.0
  firefox:
    "118.0":
      image: selenium/standalone-firefox:118.0

command / args override the container ENTRYPOINT / CMD at three levels: template (default for the main browser container), browser version (override per version), and per sidecar/init container. nil inherits from the template.

# Custom entrypoint to start a Playwright server
browsers:
  playwright-chromium:
    "1.59.1":
      image: mcr.microsoft.com/playwright:v1.59.1
      command: ["sh", "-c", "cd /opt/pw && exec ./node_modules/.bin/playwright-core run-server --port 4444 --host 0.0.0.0"]

# CLI args for an MCP image that already has an entrypoint
  playwright-mcp:
    "0.0.75":
      image: mcr.microsoft.com/playwright/mcp:v0.0.75
      args: ["--port", "8808", "--host", "0.0.0.0"]

Merge semantics — two tiers, later overrides earlier: spec.template (base) → the per-version entry at spec.browsers[name][version].

• nil fields inherit from the template.
• Maps and lists are merged with deduplication (override wins on key conflict), not replaced.
• Merge keys: sidecars/init containers by name, env vars by name, volumes by name, tolerations by key, host aliases by IP, image pull secrets by name, container ports by port number, volume mounts by mount path.

This keeps configuration reusable and avoids Pods rejected for duplicate entries.

Status: version (config version id), lastUpdated (timestamp).

Two internal primitives:

• deletePod — force-deletes the Pod (gracePeriodSeconds=0); ignores NotFound.
• deleteBrowser — removes the finalizer, then Deletes the CR (Kubernetes completes deletion immediately once the finalizer is gone).

When a failure is detected, the controller handles it in a single reconcile: force-delete the Pod (if any), write status.phase=Failed with a message, and call deleteBrowser. As a safety net, a guard at the top of Reconcile re-runs deletePod + deleteBrowser whenever it observes a Browser already in Failed, so an interrupted cleanup is retried idempotently on the next reconcile.

Example status.message values: Browser configuration not found, pods "b1" is forbidden: exceeded quota: ..., Browser did not start within 5m0s, pod container browser terminated: OOMKilled (exit code 137), Browser pod container browser failed: CrashLoopBackOff - back-off restarting failed container.

When the cluster runs out of Pod quota (or another admission plugin blocks Pod creation), the controller keeps retrying and the Browser CR stays Pending indefinitely. This flag gives a deterministic deadline: if a Browser has lived without a Pod longer than the configured duration, the next reconcile marks it Failed (reason PendingTimeoutExceeded, message Browser did not start within <timeout>), and the following reconcile removes it.

The timeout is measured against Browser.metadata.creationTimestamp (not when the controller first saw the CR), so a controller restart does not reset the window. The default 0 disables it and preserves retry-forever behavior.

REGISTRY and VERSION are expected to be supplied externally so the same Makefile works locally and in CI.