[Serve] [Docs] Clarify that the Serve config only supports remote URIs (

#34212)

The Serve config only supports remote URIs within its `runtime_env` for safety purposes. However, this behavior is poorly documented and only guarded by a pydantic validator with an unclear error message.

This change documents the remote URI requirements and clarifies the error message.

Behavior when you run the following config with an invalid `runtime_env`:

```yaml
import_path: fruit:graph

runtime_env: {
  "working_dir": "src"
}
```

1. Without the change:

```console
% serve run config.yaml
...
pydantic.error_wrappers.ValidationError: 1 validation error for ServeApplicationSchema
runtime_env
  Invalid protocol for runtime_env URI src. Supported protocols: ['GCS', 'CONDA', 'PIP', 'HTTPS', 'S3', 'GS', 'FILE']. Original error: '' is not a valid Protocol (type=value_error)
```

2. With the change:

```console
% serve run config.yaml
...
pydantic.error_wrappers.ValidationError: 1 validation error for ServeApplicationSchema
runtime_env
  runtime_envs in the Serve config support only remote URIs in working_dir and py_modules. Got error when parsing URI: Invalid protocol for runtime_env URI "src". Supported protocols: ['GCS', 'CONDA', 'PIP', 'HTTPS', 'S3', 'GS', 'FILE']. Original error: '' is not a valid Protocol (type=value_error)
```

doc/source/serve/production-guide/config.md

@@ -34,7 +34,7 @@ deployments:
 The file contains the following fields:
 
 - An `import_path`, which is the path to your top-level Serve deployment (or the same path passed to `serve run`). The most minimal config file consists of only an `import_path`.
-- A `runtime_env` that defines the environment that the application will run in. This is used to package application dependencies such as `pip` packages (see {ref}`Runtime Environments <runtime-environments>` for supported fields). Note that the `import_path` must be available _within_ the `runtime_env` if it's specified.
+- A `runtime_env` that defines the environment that the application will run in. This is used to package application dependencies such as `pip` packages (see {ref}`Runtime Environments <runtime-environments>` for supported fields). The `import_path` must be available _within_ the `runtime_env` if it's specified. The Serve config's `runtime_env` can only use [remote URIs](remote-uris) in its `working_dir` and `py_modules`; it cannot use local zip files or directories.
 - `host` and `port` are HTTP options that determine the host IP address and the port for your Serve application's HTTP proxies. These are optional settings and can be omitted. By default, the `host` will be set to `0.0.0.0` to expose your deployments publicly, and the port will be set to `8000`. If you're using Kubernetes, setting `host` to `0.0.0.0` is necessary to expose your deployments outside the cluster.
 - A list of `deployments`. This is optional and allows you to override the `@serve.deployment` settings specified in the deployment graph code. Each entry in this list must include the deployment `name`, which must match one in the code. If this section is omitted, Serve launches all deployments in the graph with the settings specified in the code.
 

python/ray/_private/runtime_env/packaging.py

@@ -190,7 +190,7 @@ def parse_uri(pkg_uri: str) -> Tuple[Protocol, str]:
         protocol = Protocol(uri.scheme)
     except ValueError as e:
         raise ValueError(
-            f"Invalid protocol for runtime_env URI {pkg_uri}. "
+            f'Invalid protocol for runtime_env URI "{pkg_uri}". '
             f"Supported protocols: {Protocol._member_names_}. Original error: {e}"
         )
 

python/ray/serve/schema.py

@@ -116,7 +116,14 @@ def runtime_env_contains_remote_uris(cls, v):
 
         for uri in uris:
             if uri is not None:
-                parse_uri(uri)
+                try:
+                    parse_uri(uri)
+                except ValueError as e:
+                    raise ValueError(
+                        "runtime_envs in the Serve config support only "
+                        "remote URIs in working_dir and py_modules. Got "
+                        f"error when parsing URI: {e}"
+                    )
 
         return v
 
@@ -361,7 +368,14 @@ def runtime_env_contains_remote_uris(cls, v):
 
         for uri in uris:
             if uri is not None:
-                parse_uri(uri)
+                try:
+                    parse_uri(uri)
+                except ValueError as e:
+                    raise ValueError(
+                        "runtime_envs in the Serve config support only "
+                        "remote URIs in working_dir and py_modules. Got "
+                        f"error when parsing URI: {e}"
+                    )
 
         return v