[3/n] [Serve] expose deployment topology in serve instance details

[abrarsheikh]

Summary

This PR exposes deployment topology information in Ray Serve instance details, allowing users to visualize and understand the dependency graph of deployments within their applications.

What's Changed

New Data Structures

Added two new schema classes to represent deployment topology:

• DeploymentNode - Represents a node in the deployment DAG

• DeploymentTopology - Represents the full dependency graph

Implementation

Controller Integration

• Updated ServeController to include deployment_topology in ApplicationDetails when serving instance details
• Topology is now accessible via the get_serve_details() API

---

Example Output:

{
    "app_name": "my_app",
    "ingress_deployment": "Ingress",
    "nodes": {
        "Ingress": {
            "name": "Ingress",
            "is_ingress": True,
            "outbound_deployments": [
                {"name": "ServiceA", "app_name": "my_app"}
            ]
        },
        "ServiceA": {
            "name": "ServiceA",
            "is_ingress": False,
            "outbound_deployments": [
                {"name": "Database", "app_name": "my_app"}
            ]
        },
        "Database": {
            "name": "Database",
            "is_ingress": False,
            "outbound_deployments": []
        }
    }
}

[cursor]

Bug: Ingress Conflict: Silent Overwrite, Lacks Validation.

When multiple deployments have ingress=True, the code silently overwrites self._ingress_deployment_name with each one in iteration order, causing the last deployment to become the ingress. This is non-deterministic and lacks validation, unlike the similar case for multiple route prefixes which raises a RayServeException. The test change on line 230 makes this more likely by marking all deployments with a route_prefix as ingress.

python/ray/serve/_private/application_state.py#L386-L389

ray/python/ray/serve/_private/application_state.py

Lines 386 to 389 in 0e03017

	else:
	for name, info in deployment_infos.items():
	if info.ingress:
	self._ingress_deployment_name = name

 

---

Bug: Missing name corrupts Deployment ID.

The docs_path property creates a DeploymentID with self._ingress_deployment_name as the name without checking if it's None. When no ingress deployment exists, this passes None to DeploymentID(name=None, ...), which violates the type contract since DeploymentID.name expects a str. This will cause errors when trying to look up the deployment or use the ID.

python/ray/serve/_private/application_state.py#L279-L288

ray/python/ray/serve/_private/application_state.py

Lines 279 to 288 in 0e03017

	@property
	def docs_path(self) -> Optional[str]:
	# get the docs path from the running deployments
	# we are making an assumption that the docs path can only be set
	# on ingress deployments with fastapi.
	ingress_deployment = DeploymentID(self._ingress_deployment_name, self._name)
	return self._deployment_state_manager.get_deployment_docs_path(
	ingress_deployment
	)

 

---

[abrarsheikh]

@cursoragent its currently implicit in the code that there will always be exactly one ingress. So i odnt think we need special handling for this.

[cursor]

Unable to authenticate your request. Please make sure to connect your GitHub account to Cursor. Go to Cursor