Add client-side configuration for deployment concurrency grace period

[devin-ai-integration]

Overview

Adds client-side configuration for deployment concurrency grace periods, allowing users to control how long infrastructure has to start before concurrency slots are released. This addresses #19410 and brings OSS feature parity with Prefect Cloud.

Previously, the grace period was hardcoded server-side (300s in OSS). Now users can configure it per-deployment via:

• prefect.yaml deployments
• flow.deploy() / flow.serve() with ConcurrencyLimitConfig
• Python deployment APIs

Changes

Schema & Models

• Added grace_period_seconds field to ConcurrencyOptions (server schema) and ConcurrencyLimitConfig (client schema)
• Field is optional with default of 600 seconds (10 minutes)
• Validated range: 60-86400 seconds (1 minute to 1 day)
• No database migration required - concurrency_options is already a JSON column

Orchestration

• Updated SecureFlowConcurrencySlots policy to use configured grace period when creating concurrency leases
• Handles concurrency_options as both dict and Pydantic model for backward compatibility
• Falls back to server setting (initial_deployment_lease_duration, default 300s) when concurrency_options is None

CLI & Deployment

• Added grace_period_seconds to ConcurrencyLimitSpec model
• Updated _run_single_deploy to extract and pass through grace period from YAML
• Updated RunnerDeployment to map grace period from ConcurrencyLimitConfig to deployment payload
• Fixed YAML serialization to exclude None values from concurrency_limit dict

Documentation

• Updated deployment concepts docs with grace period explanation and examples
• Updated prefect.yaml reference with grace period field description

Test Coverage

Added 9 tests covering:

• Boundary validation (5 tests): Min/max/default values for grace_period_seconds
• YAML deployment mapping (2 tests): Verify grace period flows from YAML to deployment, and None values aren't serialized
• Orchestration behavior (3 tests): Server setting fallback, model default, and custom grace period

All tests passing locally and in CI (49/51 checks passed, 2 cancelled due to infrastructure issues).

Important Review Points

1. Fallback behavior: When concurrency_options is None, uses server setting (300s). When concurrency_options exists but grace_period_seconds not set, uses model default (600s). This difference is intentional but worth verifying.

2. Type handling: Orchestration code handles concurrency_options as both dict and Pydantic model instance. This is necessary for backward compatibility but adds complexity.

3. YAML serialization: Now filters out None values from concurrency_limit dict to avoid cluttering configs. Verify this doesn't affect other optional fields.

4. Range validation: 60-86400 seconds (1 minute to 1 day). Confirm this range is appropriate for all use cases.

---

Link to Devin run: https://app.devin.ai/sessions/6a429e264eee42ffa97cffcdd6e0eada
Requested by: Nate Nowack (@zzstoatzz)

Checklist

• This pull request references any related issue by including "closes Add support for concurrency grace period #19410"
• If this pull request adds new functionality, it includes unit tests that cover the changes
• If this pull request removes docs files, it includes redirect settings in mint.json. (N/A)
• If this pull request adds functions or classes, it includes helpful docstrings.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[codspeed-hq]

CodSpeed Performance Report

Merging #19489 will not alter performance

_{Comparing devin/1763582330-add-deployment-concurrency-grace-period (6dd8a71) with main (63d071d)}

Summary

✅ 2 untouched

[desertaxle]

LGTM!