Mikuláš Poul
04/22/2026, 2:02 PMprefect server services start supported?Marvin
04/22/2026, 2:02 PMMarvin
04/22/2026, 2:06 PMprefect server services start --background enforces a single background services process per host (PID file guard). A second background instance on the same machine will be refused.
Supported/recommended pattern:
- Run a single background services instance for your deployment.
- Scale API servers separately with prefect server start --no-services (you can run multiple API instances behind a load balancer).
- For HA, back services with Redis/Docket and Redis-based messaging, but still run one services process in practice.
Controlling which services run:
- There isn’t a CLI to start a subset, but you can enable/disable services via env vars like PREFECT_API_SERVICES_<SERVICE>_ENABLED=true|false.
- See what’s enabled with:
prefect server services ls
Example:
# Disable just the scheduler, then start services
export PREFECT_API_SERVICES_SCHEDULER_ENABLED=false
prefect server services start
Helpful docs:
- Self-hosted architecture
- Service separation and background services
- Example topology (1 background services, multiple API servers)
If you’re trying to shard services (e.g., run disjoint subsets in separate processes) or achieve failover, can you share your goal? I can suggest a concrete setup that fits it.Mikuláš Poul
04/22/2026, 2:10 PMprefect server services start on different server instances?
This ticket mentions "When running multiple background services" https://github.com/PrefectHQ/prefect/issues/20954, seemingly it suggest that it's supported?Marvin
04/22/2026, 2:10 PMMarvin
04/22/2026, 2:10 PMMikuláš Poul
04/22/2026, 2:10 PMprefect server services start on different server instances?Marvin
04/22/2026, 2:10 PMMarvin
04/22/2026, 2:11 PM--background enforces a single instance via a PID file.
- Different hosts: There’s no cross-host guard, so you can start multiple services processes. However, with default in-memory coordination (the defaults), they won’t coordinate and you can get duplicate scheduling/triggering and other oddities.
- If you really need multiple services processes for HA, you must put all instances on the same shared backends so they coordinate:
- Shared Postgres for the API database
- Redis-backed Docket (coordination) via PREFECT_SERVER_DOCKET_URL=redis://...
- Redis-backed messaging/ordering/lease storage so events and locks are shared
- Even with that in place, the typical and documented topology still runs one services instance.
Recommended topology:
- One background services process:
# Example: configure Redis-backed coordination for HA
export PREFECT_SERVER_DOCKET_URL="redis://<redis-host>:6379/1"
# (and configure Redis messaging/ordering/lease storage if you plan to multi-instance)
prefect server services start
- Multiple API servers (no services):
prefect server start --no-services --host 0.0.0.0 --port 4200
(Run as many as you need behind a load balancer.)
Docs:
- Self-hosted architecture
- Service separation and background services
- Example topology (1 background services, multiple API servers)
If your goal is HA/failover for services, I can outline a concrete setup (env vars and checks) tailored to your environment.Mikuláš Poul
04/22/2026, 2:12 PMMarvin
04/22/2026, 2:12 PMMarvin
04/22/2026, 2:18 PM# Database
PREFECT_API_DATABASE_CONNECTION_URL=<postgresql+asyncpg://user:pass@host:5432/prefect>
PREFECT_API_DATABASE_MIGRATE_ON_START=false # run migrations once, separately
# Redis-backed messaging/ordering/leases
PREFECT_MESSAGING_BROKER=prefect_redis.messaging
PREFECT_MESSAGING_CACHE=prefect_redis.messaging
PREFECT_SERVER_EVENTS_CAUSAL_ORDERING=prefect_redis.ordering
PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE=prefect_redis.lease_storage
PREFECT_REDIS_MESSAGING_HOST=<redis-host>
PREFECT_REDIS_MESSAGING_PORT=6379
# Docket (distributed background service coordination)
PREFECT_SERVER_DOCKET_URL=redis://<redis-host>:6379/1
Process layout (recommended)
- API (scale horizontally):
prefect server start --no-services --host 0.0.0.0 --port 4200
- Services (HA and burst scaling):
prefect server services start
Autoscaling guidance
- API: This is where most “traffic” load lives. Enable Prometheus metrics and scale on CPU/latency/requests.
- Enable metrics:
export PREFECT_API_ENABLE_METRICS=true # or PREFECT_SERVER_METRICS_ENABLED=true
- Scrape endpoint: http//<api host>4200/api/metrics
- Services: These loops are coordinated and often lightweight; adding replicas primarily improves HA and failover. If you want burst capacity during heavy automation/event churn:
- Run 2 replicas for HA by default; allow HPA to raise to 3–5 on CPU or a custom external metric (e.g., a Redis backlog you measure).
- There isn’t a built-in HTTP /metrics endpoint on the services process; common practice is to:
- Scale on CPU/memory as a simple proxy, or
- Expose a custom metric (e.g., queued event/backlog in Redis) via a sidecar/exporter and use a custom-metrics HPA.
- Optional sharding by service: You can enable/disable specific services per process with env vars (PREFECT_API_SERVICES_<SERVICE>_ENABLED=true|false) if you want to scale just one kind (e.g., Triggers) independently. Discover names/status with:
prefect server services ls
Then disable everything except the one you want to scale on that deployment.
Operational notes
- Run DB migrations once before bringing up multiple instances:
prefect server database upgrade -y
- Don’t use --background for orchestrated multi-replica deployments; keep processes in the foreground for clean liveness/readiness and restarts.
- Even with multiple services replicas, throughput gains may be modest because coordination ensures only one instance performs a given unit of work at a time. The big scaling lever is usually the API tier.
Docs
- Self-hosted architecture and patterns
- Service separation (API vs. background services)
- Example topology (API replicas + services)
Want me to sketch Kubernetes Deployments + HPAs for:
- API (metrics-based HPA), and
- Services (CPU-based HPA, with an option for a custom Redis backlog metric)?
If you’re not on K8s, tell me your platform (Docker Compose, Nomad, systemd), and I’ll tailor the setup.Mikuláš Poul
04/22/2026, 2:39 PM