Enhancement: Disable Deployments

docs/3.0rc/api-ref/rest-api/server/deployments/disable-deployment.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /api/deployments/{id}/disable
+---

docs/3.0rc/api-ref/rest-api/server/deployments/enable-deployment.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /api/deployments/{id}/enable
+---

docs/3.0rc/api-ref/rest-api/server/schema.json

@@ -3573,6 +3573,112 @@
                 }
             }
         },
+        "/api/deployments/{id}/disable": {
+            "post": {
+                "tags": [
+                    "Deployments"
+                ],
+                "summary": "Disable Deployment",
+                "description": "Set a deployment to disabled. Any auto-scheduled runs will be deleted and\nno new runs can be created until the deployment is enabled.",
+                "operationId": "disable_deployment_deployments__id__disable_post",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "The deployment id",
+                            "title": "Id"
+                        },
+                        "description": "The deployment id"
+                    },
+                    {
+                        "name": "x-prefect-api-version",
+                        "in": "header",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "title": "X-Prefect-Api-Version"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/deployments/{id}/enable": {
+            "post": {
+                "tags": [
+                    "Deployments"
+                ],
+                "summary": "Enable Deployment",
+                "description": "Set a deployment to enabled. Runs can be scheduled and created.",
+                "operationId": "enable_deployment_deployments__id__enable_post",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "The deployment id",
+                            "title": "Id"
+                        },
+                        "description": "The deployment id"
+                    },
+                    {
+                        "name": "x-prefect-api-version",
+                        "in": "header",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "title": "X-Prefect-Api-Version"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/api/saved_searches/": {
             "put": {
                 "tags": [
@@ -15743,6 +15849,12 @@
                         "description": "Whether or not the deployment is paused.",
                         "default": false
                     },
+                    "disabled": {
+                        "type": "boolean",
+                        "title": "Disabled",
+                        "description": "Whether or not the deployment is disabled.",
+                        "default": false
+                    },
                     "schedules": {
                         "items": {
                             "$ref": "#/components/schemas/DeploymentScheduleCreate"
@@ -15979,6 +16091,17 @@
                         ],
                         "description": "Filter criteria for `Deployment.paused`"
                     },
+                    "disabled": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/components/schemas/DeploymentFilterDisabled"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "description": "Filter criteria for `Deployment.disabled`"
+                    },
                     "tags": {
                         "anyOf": [
                             {
@@ -16062,6 +16185,26 @@
                 "title": "DeploymentFilterConcurrencyLimit",
                 "description": "Filter by `Deployment.concurrency_limit`."
             },
+            "DeploymentFilterDisabled": {
+                "properties": {
+                    "eq_": {
+                        "anyOf": [
+                            {
+                                "type": "boolean"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "title": "Eq ",
+                        "description": "Only returns where deployment is/is not disabled"
+                    }
+                },
+                "additionalProperties": false,
+                "type": "object",
+                "title": "DeploymentFilterDisabled",
+                "description": "Filter by `Deployment.disabled`."
+            },
             "DeploymentFilterId": {
                 "properties": {
                     "any_": {
@@ -16484,6 +16627,12 @@
                         "description": "Whether or not the deployment is paused.",
                         "default": false
                     },
+                    "disabled": {
+                        "type": "boolean",
+                        "title": "Disabled",
+                        "description": "Whether or not the deployment is disabled.",
+                        "default": false
+                    },
                     "schedules": {
                         "items": {
                             "$ref": "#/components/schemas/DeploymentSchedule"
@@ -16947,7 +17096,8 @@
                 "type": "string",
                 "enum": [
                     "READY",
-                    "NOT_READY"
+                    "NOT_READY",
+                    "DISABLED"
                 ],
                 "title": "DeploymentStatus",
                 "description": "Enumeration of deployment statuses."
@@ -16982,6 +17132,12 @@
                         "description": "Whether or not the deployment is paused.",
                         "default": false
                     },
+                    "disabled": {
+                        "type": "boolean",
+                        "title": "Disabled",
+                        "description": "Whether or not the deployment is disabled.",
+                        "default": false
+                    },
                     "schedules": {
                         "items": {
                             "$ref": "#/components/schemas/DeploymentScheduleCreate"

docs/mint.json

@@ -467,7 +467,9 @@
                     "3.0rc/api-ref/rest-api/server/deployments/read-deployment-schedules",
                     "3.0rc/api-ref/rest-api/server/deployments/create-deployment-schedules",
                     "3.0rc/api-ref/rest-api/server/deployments/delete-deployment-schedule",
-                    "3.0rc/api-ref/rest-api/server/deployments/update-deployment-schedule"
+                    "3.0rc/api-ref/rest-api/server/deployments/update-deployment-schedule",
+                    "3.0rc/api-ref/rest-api/server/deployments/disable-deployment",
+                    "3.0rc/api-ref/rest-api/server/deployments/enable-deployment"
                   ]
                 },
                 {

src/prefect/cli/deployment.py

@@ -259,6 +259,50 @@ async def inspect(name: str):
     app.console.print(Pretty(deployment_json))
 
 
+@deployment_app.command()
+async def disable(name: str):
+    """
+    Disable a deployment.
+
+    \b
+    Example:
+        \b
+        $ prefect deployment disable "hello-world/my-deployment"
+    """
+    assert_deployment_name_format(name)
+
+    async with get_client() as client:
+        try:
+            deployment = await client.read_deployment_by_name(name)
+        except ObjectNotFound:
+            exit_with_error(f"Deployment {name!r} not found!")
+
+        await client.disable_deployment(deployment.id)
+        exit_with_success(f"Disabled deployment {name!r}.")
+
+
+@deployment_app.command()
+async def enable(name: str):
+    """
+    Enable a deployment.
+
+    \b
+    Example:
+        \b
+        $ prefect deployment enable "hello-world/my-deployment"
+    """
+    assert_deployment_name_format(name)
+
+    async with get_client() as client:
+        try:
+            deployment = await client.read_deployment_by_name(name)
+        except ObjectNotFound:
+            exit_with_error(f"Deployment {name!r} not found!")
+
+        await client.enable_deployment(deployment.id)
+        exit_with_success(f"Enabled deployment {name!r}.")
+
+
 @schedule_app.command("create")
 async def create_schedule(
     name: str,

src/prefect/client/orchestration.py

@@ -1664,6 +1664,7 @@ async def create_deployment(
         infrastructure_document_id: Optional[UUID] = None,
         parameter_openapi_schema: Optional[Dict[str, Any]] = None,
         paused: Optional[bool] = None,
+        disabled: Optional[bool] = None,
         pull_steps: Optional[List[dict]] = None,
         enforce_parameter_schema: Optional[bool] = None,
         job_variables: Optional[Dict[str, Any]] = None,
@@ -1675,16 +1676,36 @@ async def create_deployment(
             flow_id: the flow ID to create a deployment for
             name: the name of the deployment
             version: an optional version string for the deployment
+            schedules: an optional list of schedules for the deployment
+            concurrency_limit: an optional concurrency limit for flow runs
+              created by this deployment
+            parameters: an optional parameter schema for this deployment
+            parameter_openapi_schema: an optional OpenAPI schema for this deployment's parameters
+            description: an optional text description of this deployment
+            work_queue_name: the work queue associated with this deployment (optional)
+            work_pool_name: the work pool associated with this deployment (optional)
             tags: an optional list of tags to apply to the deployment
             storage_document_id: an reference to the storage block document
                 used for the deployed flow
+            path: The path to the working directory for the workflow, relative to remote storage or an absolute path
+            entrypoint: The path to the entrypoint for the workflow, relative to the `path`
             infrastructure_document_id: an reference to the infrastructure block document
                 to use for this deployment
+            paused: an optional boolean. If True, flow runs will be scheduled as
+              described by this deployment's schedules
+            disabled: an optional boolean. If True, no flow runs will be created
+              for this deployment by any mechanism including automations and
+              API requests
+            pull_steps: an optional list of steps that describe how a worker should
+              prepare a flow run created from this deployment
+            enforce_parameter_schema: an optional boolean. If True, the API will
+              enforce the provided parameter schema when flow runs are created
             job_variables: A dictionary of dot delimited infrastructure overrides that
                 will be applied at runtime; for example `env.CONFIG_KEY=config_value` or
                 `namespace='prefect'`. This argument was previously named `infra_overrides`.
                 Both arguments are supported for backwards compatibility.
 
+
         Raises:
             httpx.RequestError: if the deployment was not created for any reason
 
@@ -1709,6 +1730,7 @@ async def create_deployment(
             job_variables=dict(job_variables or {}),
             parameter_openapi_schema=parameter_openapi_schema,
             paused=paused,
+            disabled=disabled,
             schedules=schedules or [],
             concurrency_limit=concurrency_limit,
             pull_steps=pull_steps,
@@ -1728,6 +1750,9 @@ async def create_deployment(
         if deployment_create.paused is None:
             exclude.add("paused")
 
+        if deployment_create.disabled is None:
+            exclude.add("disabled")
+
         if deployment_create.pull_steps is None:
             exclude.add("pull_steps")
 
@@ -1750,6 +1775,16 @@ async def set_deployment_paused_state(self, deployment_id: UUID, paused: bool):
             f"/deployments/{deployment_id}", json={"paused": paused}
         )
 
+    async def disable_deployment(self, deployment_id: UUID):
+        await self._client.post(
+            f"/deployments/{deployment_id}/disable",
+        )
+
+    async def enable_deployment(self, deployment_id: UUID):
+        await self._client.post(
+            f"/deployments/{deployment_id}/enable",
+        )
+
     async def update_deployment(
         self,
         deployment_id: UUID,

src/prefect/client/schemas/actions.py

@@ -153,6 +153,7 @@ def convert_to_strings(cls, values):
     name: str = Field(..., description="The name of the deployment.")
     flow_id: UUID = Field(..., description="The ID of the flow to deploy.")
     paused: Optional[bool] = Field(None)
+    disabled: Optional[bool] = Field(None)
     schedules: List[DeploymentScheduleCreate] = Field(
         default_factory=list,
         description="A list of schedules for the deployment.",
@@ -229,6 +230,9 @@ def remove_old_fields(cls, values):
     paused: Optional[bool] = Field(
         default=None, description="Whether or not the deployment is paused."
     )
+    disabled: Optional[bool] = Field(
+        default=None, description="Whether or not the deployment is disabled."
+    )
     schedules: Optional[List[DeploymentScheduleCreate]] = Field(
         default=None,
         description="A list of schedules for the deployment.",

src/prefect/client/schemas/objects.py

@@ -128,6 +128,7 @@ class DeploymentStatus(AutoEnum):
 
     READY = AutoEnum.auto()
     NOT_READY = AutoEnum.auto()
+    DISABLED = AutoEnum.auto()
 
 
 class WorkQueueStatus(AutoEnum):
@@ -1113,6 +1114,10 @@ class Deployment(ObjectBaseModel):
             "Whether or not the deployment should enforce the parameter schema."
         ),
     )
+    disabled: bool = Field(
+        default=False,
+        description="If true, no flow runs will be created for the deployment.",
+    )
 
 
 class ConcurrencyLimit(ObjectBaseModel):