[serve] Add ControllerOptions for configurable controller runtime_env

[kouroshHakha]

Summary

• Add new public ControllerOptions config object (alpha), symmetric with HTTPOptions / gRPCOptions, that lets serve.start() / serve.run() / serve run foo.yaml pass a strictly-validated runtime_env into the Serve controller actor.
• v0 scope: runtime_env only, and within runtime_env only the env_vars key is accepted. Other keys (pip, working_dir, py_modules, container, ...) would mutate Serve's own dependencies on a detached, long-lived controller actor and are rejected with a message pointing operators at deployment-level runtime_env.

Motivation

Today if there are env variables that need to be passed to the HAProxy layer (e.g. RAY_SERVE_HAPROXY_TCP_NO_DELAY) we have to set them at cluster level, instead of doing something like RAY_SERVE_HAPROXY_TCP_NO_DELAY=1 serve run foo.yaml or setting the env var in runtime envs in the yaml. which would be much more convenient for tuning.

API

# Python
serve.start(
    controller_options=ControllerOptions(
        runtime_env={\"env_vars\": {\"RAY_SERVE_HAPROXY_NBTHREAD\": \"16\"}},
    ),
)

serve.run(
    app,
    controller_options={\"runtime_env\": {\"env_vars\": {\"FOO\": \"bar\"}}},  # dict also accepted
)

# serve run foo.yaml
controller_options:
  runtime_env:
    env_vars:
      RAY_SERVE_HAPROXY_TCP_NODELAY: \"1\"
      RAY_SERVE_HAPROXY_NBTHREAD: \"16\"

http_options:
  host: 0.0.0.0
  port: 8000

applications:
  - ...

Validator catches typos and disallowed fields at parse time:

>>> ControllerOptions(runtime_env={\"pip\": [\"numpy\"]})
ValidationError: ControllerOptions.runtime_env only supports ['env_vars'] in this
version; got disallowed keys ['pip']. Per-replica runtime_env belongs on the
deployment (serve.deployment(runtime_env=...)), not on the controller actor.

>>> ControllerOptions(runtime_env={\"env_vars\": {\"X\": 1}})
ValidationError: env_vars['X'] must be str (got int); coerce explicitly.

Test plan

• python/ray/serve/tests/unit/test_config.py::TestControllerOptions — 12 methods (parametrized) covering accept/reject paths: default None, dict coerce via model_validate, valid env_vars, empty env_vars, every non-env_vars runtime_env key (pip, working_dir, py_modules, conda, container, nsight), non-dict runtime_env, non-dict env_vars, non-str values across types, empty/non-string env-var keys, extra top-level fields, mixed allowed-and-disallowed keys.
• python/ray/serve/tests/unit/test_config.py::TestGetControllerImpl — 3 cases asserting runtime_env correctly threaded into the actor class's _default_options (or omitted when not requested).
• python/ray/serve/tests/unit/test_schema.py::TestServeDeploySchema — 4 cases on the YAML schema: default-None, valid passthrough, rejects disallowed runtime_env keys, rejects non-str env values.
• python/ray/serve/tests/test_standalone.py::test_serve_start_controller_options — parametrized e2e (model + dict input) that asserts the requested env vars actually land on the live controller actor's os.environ.
• python/ray/serve/tests/test_standalone.py::test_serve_start_controller_options_rejects_disallowed_runtime_env — verifies bad runtime_env raises ValidationError at the caller, not from a Ray task.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces ControllerOptions to allow passing configuration, specifically runtime_env.env_vars, to the Ray Serve controller actor during initialization. This new configuration is integrated into serve.start, serve.run, the YAML deployment schema, and the CLI. Feedback includes a suggestion to use the built-in dict type for consistency in type hints and a recommendation to improve the validation logic for env_vars to correctly handle cases where the key might be explicitly set to null.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 010a8c6. Configure here.}