Add plugin server example

Author: Nadine-H

examples/plugins/example_plugin_server/.python-version

@@ -0,0 +1 @@
+3.11

examples/plugins/example_plugin_server/README.md

@@ -0,0 +1,30 @@
+## Overview
+
+If you wish to hook up your own plugin server through `dstack` builtin ` rest-plugin`, here's a basic example on how to do so.
+
+## Steps
+
+
+1. Install required dependencies for the plugin server:
+
+    ```bash
+    uv sync 
+    ```
+
+1. Start the plugin server locally:
+
+    ```bash
+    fastapi dev app/main.py 
+    ```
+
+1. Enable `rest-plugin` in `dstack` `server/config.yaml`:
+
+    ```yaml
+   plugins:
+    - rest_plugin
+    ```
+
+1. Point the `dstack` server to your plugin server:
+    ```bash
+    export DSTACK_PLUGIN_SERVICE_URI=http://127.0.0.1:8000
+    ```

examples/plugins/example_plugin_server/app/__init__.py

@@ -0,0 +1,43 @@
+import logging
+
+from fastapi import FastAPI
+
+from app.models import FleetSpecRequest, GatewaySpecRequest, RunSpecRequest, VolumeSpecRequest
+from app.utils import configure_logging
+
+configure_logging()
+logger = logging.getLogger(__name__)
+
+app = FastAPI()
+
+
+@app.post("/apply_policies/on_run_apply")
+async def on_run_apply(request: RunSpecRequest):
+    logger.info(
+        f"Received run spec request from user {request.user} and project {request.project}"
+    )
+    return request.spec
+
+
+@app.post("/apply_policies/on_fleet_apply")
+async def on_fleet_apply(request: FleetSpecRequest):
+    logger.info(
+        f"Received fleet spec request from user {request.user} and project {request.project}"
+    )
+    return request.spec
+
+
+@app.post("/apply_policies/on_volume_apply")
+async def on_volume_apply(request: VolumeSpecRequest):
+    logger.info(
+        f"Received volume spec request from user {request.user} and project {request.project}"
+    )
+    return request.spec
+
+
+@app.post("/apply_policies/on_gateway_apply")
+async def on_gateway_apply(request: GatewaySpecRequest):
+    logger.info(
+        f"Received gateway spec request from user {request.user} and project {request.project}"
+    )
+    return request.spec

examples/plugins/example_plugin_server/app/main.py

@@ -0,0 +1,22 @@
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+from dstack._internal.core.models.fleets import FleetSpec
+from dstack._internal.core.models.gateways import GatewaySpec
+from dstack._internal.core.models.runs import RunSpec
+from dstack._internal.core.models.volumes import VolumeSpec
+
+SpecType = TypeVar("SpecType", RunSpec, FleetSpec, VolumeSpec, GatewaySpec)
+
+
+class SpecRequest(BaseModel, Generic[SpecType]):
+    user: str
+    project: str
+    spec: SpecType
+
+
+RunSpecRequest = SpecRequest[RunSpec]
+FleetSpecRequest = SpecRequest[FleetSpec]
+VolumeSpecRequest = SpecRequest[VolumeSpec]
+GatewaySpecRequest = SpecRequest[GatewaySpec]

examples/plugins/example_plugin_server/app/models.py

@@ -0,0 +1,7 @@
+import logging
+import os
+
+
+def configure_logging():
+    log_level = os.getenv("LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(level=log_level)

examples/plugins/example_plugin_server/app/utils.py

@@ -0,0 +1,10 @@
+[project]
+name = "dstack-plugin-server"
+version = "0.1.0"
+description = "Example plugin server"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi[standard]>=0.115.12",
+    "dstack>=0.19.8"
+]