Support gateway events in API, CLI, and UI (#3499)

Author: jvstme

frontend/src/pages/Events/List/hooks/useColumnDefinitions.tsx

@@ -125,6 +125,19 @@ export const useColumnsDefinitions = () => {
                                 </div>
                             );
 
+                        case 'gateway':
+                            return (
+                                <div>
+                                    Gateway{' '}
+                                    {target.project_name && (
+                                        <NavigateLink href={ROUTES.PROJECT.DETAILS.FORMAT(target.project_name)}>
+                                            {target.project_name}
+                                        </NavigateLink>
+                                    )}
+                                    /{target.name}
+                                </div>
+                            );
+
                         default:
                             return '---';
                     }

frontend/src/pages/Events/List/hooks/useFilters.ts

@@ -18,6 +18,7 @@ type RequestParamsKeys = keyof Pick<
     | 'target_runs'
     | 'target_jobs'
     | 'target_volumes'
+    | 'target_gateways'
     | 'within_projects'
     | 'within_fleets'
     | 'within_runs'
@@ -33,6 +34,7 @@ const filterKeys: Record<string, RequestParamsKeys> = {
     TARGET_RUNS: 'target_runs',
     TARGET_JOBS: 'target_jobs',
     TARGET_VOLUMES: 'target_volumes',
+    TARGET_GATEWAYS: 'target_gateways',
     WITHIN_PROJECTS: 'within_projects',
     WITHIN_FLEETS: 'within_fleets',
     WITHIN_RUNS: 'within_runs',
@@ -50,6 +52,7 @@ const multipleChoiseKeys: RequestParamsKeys[] = [
     'target_runs',
     'target_jobs',
     'target_volumes',
+    'target_gateways',
     'within_projects',
     'within_fleets',
     'within_runs',
@@ -65,6 +68,7 @@ const targetTypes = [
     { label: 'Run', value: 'run' },
     { label: 'Job', value: 'job' },
     { label: 'Volume', value: 'volume' },
+    { label: 'Gateway', value: 'gateway' },
 ];
 
 export const useFilters = () => {
@@ -162,6 +166,11 @@ export const useFilters = () => {
             operators: ['='],
             propertyLabel: 'Target volumes',
         },
+        {
+            key: filterKeys.TARGET_GATEWAYS,
+            operators: ['='],
+            propertyLabel: 'Target gateways',
+        },
 
         {
             key: filterKeys.WITHIN_PROJECTS,

frontend/src/types/event.d.ts

@@ -1,4 +1,4 @@
-declare type TEventTargetType = 'project' | 'user' | 'fleet' | 'instance' | 'run' | 'job' | 'volume';
+declare type TEventTargetType = 'project' | 'user' | 'fleet' | 'instance' | 'run' | 'job' | 'volume' | 'gateway';
 
 declare type TEventListRequestParams = Omit<TBaseRequestListParams, 'prev_created_at'> & {
     prev_recorded_at?: string;
@@ -9,6 +9,7 @@ declare type TEventListRequestParams = Omit<TBaseRequestListParams, 'prev_create
     target_runs?: string[];
     target_jobs?: string[];
     target_volumes?: string[];
+    target_gateways?: string[];
     within_projects?: string[];
     within_fleets?: string[];
     within_runs?: string[];
@@ -17,7 +18,7 @@ declare type TEventListRequestParams = Omit<TBaseRequestListParams, 'prev_create
 };
 
 declare interface IEventTarget {
-    type: 'project' | 'user' | 'fleet' | 'instance' | 'run' | 'job' | 'volume';
+    type: 'project' | 'user' | 'fleet' | 'instance' | 'run' | 'job' | 'volume' | 'gateway';
     project_id?: string;
     project_name?: string;
     id: string;

src/dstack/_internal/cli/commands/event.py

@@ -6,6 +6,7 @@
 from dstack._internal.cli.utils.common import (
     get_start_time,
 )
+from dstack._internal.core.errors import CLIError
 from dstack._internal.core.models.events import EventTargetType
 from dstack._internal.server.schemas.events import LIST_EVENTS_DEFAULT_LIMIT
 from dstack.api import Client
@@ -59,6 +60,13 @@ def _register(self):
                 dest="target_volumes",
                 help="Only show events that target the specified volumes",
             )
+            target_filters_group.add_argument(
+                "--target-gateway",
+                action="append",
+                metavar="NAME",
+                dest="target_gateways",
+                help="Only show events that target the specified gateways",
+            )
             within_filters_group = parser.add_mutually_exclusive_group()
             within_filters_group.add_argument(
                 "--within-fleet",
@@ -120,6 +128,17 @@ def _build_filters(args: argparse.Namespace, api: Client) -> EventListFilters:
             api.client.volumes.get(project_name=api.project, name=name).id
             for name in args.target_volumes
         ]
+    elif args.target_gateways:
+        filters.target_gateways = []
+        for name in args.target_gateways:
+            id = api.client.gateways.get(api.project, name).id
+            if id is None:
+                # TODO(0.21): Remove this check once `Gateway.id` is required.
+                raise CLIError(
+                    "Cannot determine gateway ID, most likely due to an outdated dstack server."
+                    " Update the server to 0.20.7 or higher or remove --target-gateway."
+                )
+            filters.target_gateways.append(id)
 
     if args.within_fleets:
         filters.within_fleets = [

src/dstack/_internal/cli/services/events.py

@@ -17,6 +17,7 @@ class EventListFilters:
     target_fleets: Optional[list[uuid.UUID]] = None
     target_runs: Optional[list[uuid.UUID]] = None
     target_volumes: Optional[list[uuid.UUID]] = None
+    target_gateways: Optional[list[uuid.UUID]] = None
     within_projects: Optional[list[uuid.UUID]] = None
     within_fleets: Optional[list[uuid.UUID]] = None
     within_runs: Optional[list[uuid.UUID]] = None

src/dstack/_internal/core/models/events.py

@@ -17,6 +17,7 @@ class EventTargetType(str, Enum):
     RUN = "run"
     JOB = "job"
     VOLUME = "volume"
+    GATEWAY = "gateway"
 
 
 class EventTarget(CoreModel):

src/dstack/_internal/core/models/gateways.py

@@ -1,4 +1,5 @@
 import datetime
+import uuid
 from enum import Enum
 from typing import Dict, Optional, Union
 
@@ -93,6 +94,9 @@ class GatewaySpec(CoreModel):
 
 
 class Gateway(CoreModel):
+    # ID is only optional on the client side for compatibility with pre-0.20.7 servers.
+    # TODO(0.21): Make required.
+    id: Optional[uuid.UUID] = None
     name: str
     configuration: GatewayConfiguration
     created_at: datetime.datetime

src/dstack/_internal/server/routers/events.py

@@ -45,6 +45,7 @@ async def list_events(
             target_runs=body.target_runs,
             target_jobs=body.target_jobs,
             target_volumes=body.target_volumes,
+            target_gateways=body.target_gateways,
             within_projects=body.within_projects,
             within_fleets=body.within_fleets,
             within_runs=body.within_runs,

src/dstack/_internal/server/schemas/events.py

@@ -91,6 +91,17 @@ class ListEventsRequest(CoreModel):
             max_items=MAX_FILTER_ITEMS,
         ),
     ] = None
+    target_gateways: Annotated[
+        Optional[list[uuid.UUID]],
+        Field(
+            description=(
+                "List of gateway IDs."
+                " The response will only include events that target the specified gateways"
+            ),
+            min_items=MIN_FILTER_ITEMS,
+            max_items=MAX_FILTER_ITEMS,
+        ),
+    ] = None
     within_projects: Annotated[
         Optional[list[uuid.UUID]],
         Field(

src/dstack/_internal/server/services/events.py

@@ -14,6 +14,7 @@
     EventModel,
     EventTargetModel,
     FleetModel,
+    GatewayModel,
     InstanceModel,
     JobModel,
     MemberModel,
@@ -87,6 +88,7 @@ def __post_init__(self):
     def from_model(
         model: Union[
             FleetModel,
+            GatewayModel,
             InstanceModel,
             JobModel,
             ProjectModel,
@@ -102,6 +104,13 @@ def from_model(
                 id=model.id,
                 name=model.name,
             )
+        if isinstance(model, GatewayModel):
+            return Target(
+                type=EventTargetType.GATEWAY,
+                project_id=model.project_id or model.project.id,
+                id=model.id,
+                name=model.name,
+            )
         if isinstance(model, InstanceModel):
             return Target(
                 type=EventTargetType.INSTANCE,
@@ -222,6 +231,7 @@ async def list_events(
     target_runs: Optional[list[uuid.UUID]],
     target_jobs: Optional[list[uuid.UUID]],
     target_volumes: Optional[list[uuid.UUID]],
+    target_gateways: Optional[list[uuid.UUID]],
     within_projects: Optional[list[uuid.UUID]],
     within_fleets: Optional[list[uuid.UUID]],
     within_runs: Optional[list[uuid.UUID]],
@@ -298,6 +308,13 @@ async def list_events(
                 EventTargetModel.entity_id.in_(target_volumes),
             )
         )
+    if target_gateways is not None:
+        target_filters.append(
+            and_(
+                EventTargetModel.entity_type == EventTargetType.GATEWAY,
+                EventTargetModel.entity_id.in_(target_gateways),
+            )
+        )
     if within_projects is not None:
         target_filters.append(EventTargetModel.entity_project_id.in_(within_projects))
     if within_fleets is not None: