Add plugin example

Author: r4victor

examples/plugins/example_plugin/.python-version

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

examples/plugins/example_plugin/README.md

@@ -0,0 +1,52 @@
+## Overview
+
+This is a basic `dstack` plugin example.
+You can use it as a reference point when implementing new `dstack` plugins.
+
+## Steps
+
+1. Init the plugin package:
+
+    ```
+    uv init --library
+    ```
+
+2. Define `ApplyPolicy` and `Plugin` subclasses:
+
+    ```python
+    from dstack.plugins import ApplyPolicy, Plugin, RunSpec, get_plugin_logger
+
+
+    logger = get_plugin_logger(__name__)
+
+
+    class ExamplePolicy(ApplyPolicy):
+
+        def on_run_apply(self, user: str, project: str, spec: RunSpec) -> RunSpec:
+            # ...
+            return spec
+
+
+    class ExamplePlugin(Plugin):
+        
+        def get_apply_policies(self) -> list[ApplyPolicy]:
+            return [ExamplePolicy()]
+
+    ```
+
+3. Specify a "dstack.plugins" entry point in `pyproject.toml`:
+
+    ```toml
+    [project.entry-points."dstack.plugins"]
+    example_plugin = "example_plugin:ExamplePlugin"
+    ```
+
+4. Make sure to install the plugin and enable it in the `server/config.yml`:
+
+    ```yaml
+    plugins:
+    - example_plugin
+    projects:
+    - name: main
+      # ...
+    ```

examples/plugins/example_plugin/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "example-plugin"
+version = "0.1.0"
+description = "A dstack plugin example"
+readme = "README.md"
+authors = [
+    { name = "Victor Skvortsov", email = "victor@dstack.ai" }
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.entry-points."dstack.plugins"]
+example_plugin = "example_plugin:ExamplePlugin"

examples/plugins/example_plugin/src/example_plugin/__init__.py

@@ -0,0 +1,30 @@
+from dstack.plugins import ApplyPolicy, GatewaySpec, Plugin, RunSpec, get_plugin_logger
+
+logger = get_plugin_logger(__name__)
+
+
+class ExamplePolicy(ApplyPolicy):
+    def on_run_apply(self, user: str, project: str, spec: RunSpec) -> RunSpec:
+        # Forcing some limits
+        spec.configuration.max_price = 2.0
+        spec.configuration.max_duration = "1d"
+        # Setting some extra tags
+        if spec.configuration.tags is None:
+            spec.configuration.tags = {}
+        spec.configuration.tags |= {
+            "team": "my_team",
+        }
+        # Forbid something
+        if spec.configuration.privileged:
+            logger.warning("User %s tries to run privileged containers", user)
+            raise ValueError("Running privileged containers is forbidden")
+        return spec
+
+    def on_gateway_apply(self, user: str, project: str, spec: GatewaySpec) -> GatewaySpec:
+        # Forbid creating new gateways altogether
+        raise ValueError("Creating gateways is forbidden")
+
+
+class ExamplePlugin(Plugin):
+    def get_apply_policies(self) -> list[ApplyPolicy]:
+        return [ExamplePolicy()]