Great question. When you have many similar deployments, the key is to encode only the dimensions that actually vary between them and keep everything else in tags/labels. Quick facts (Prefect 3.x): - Deployment names are unique per flow. The fully qualified name is

flow_name/deployment_name

. - Keep names short, lowercase, hyphen-separated; avoid slashes and special characters. - Use tags and labels for richer filtering and metadata instead of stuffing everything into the name. Recommended naming patterns Pick the axes that differ for your deployments (e.g., environment, schedule, region, runtime, customer) and compose a simple, consistent pattern: - Within a single flow (most common): - Pattern:

{env}-{schedule}[-{region}][-{runtime}]

- Examples: -

prod-daily

-

prod-hourly-eu

-

staging-manual-docker

-

dev-backfill

- If you need broader context or cross-team standardization: - Pattern:

{team|domain}-{purpose}-{env}-{frequency}

- Examples: -

data-warehouse-sync-prod-hourly

-

ml-batch-scoring-prod-daily

-

finance-recon-staging-manual

- For customer/tenant or variant-heavy setups: - Pattern:

{customer}-{env}-{schedule}[-v{n}]

- Examples: -

acme-prod-daily

-

globex-prod-weekly-v2

Use tags and labels for everything else - Tags: great for filtering and grouping in the UI/API. - Labels: key/value metadata for ownership, SLAs, etc. Example

from prefect import flow

@flow
def orders_etl():
    ...

if __name__ == "__main__":
    orders_etl.deploy(
        name="prod-daily",
        work_pool_name="k8s-prod",
        tags=["prod", "daily", "orders", "etl"],
        labels={"owner": "data-platform", "sla": "p1", "region": "eu-west-1"},
    )

Tips - Let the flow name carry the business context. Use the deployment name to encode only the differences (env/schedule/region/etc.). - If your work pool or queue already signals environment/runtime (e.g.,

k8s-prod

), you can omit that from the deployment name to reduce redundancy. - Be consistent: choose an order for tokens (e.g., env -> frequency -> region) and stick to it across teams. Would you share which axes actually vary across your deployments (env, schedule, region, runtime, tenant, etc.)? I can propose a concrete schema tailored to your setup and give you examples for your flows.

Short answer: it’s better to model “environment” with deployments + infrastructure, not with a flow parameter. Recommended pattern in Prefect 3.x: - Use separate deployments per environment (e.g.,

my-flow-dev

,

my-flow-staging

,

my-flow-prod

). - Point each to an environment-specific work pool/queue and set environment-specific job variables (env vars, images, resources, etc.). - Keep secrets/config in Prefect Variables and Blocks, resolved at runtime. - Avoid a flow parameter like

env="prod"

to toggle behavior; it couples business logic to infra and is easy to misconfigure. A minimal example:

# prefect.yaml
deployments:
  - name: my-flow-dev
    entrypoint: flows/my_flow.py:my_flow
    work_pool:
      name: dev-pool
      job_variables:
        env:
          ENVIRONMENT: development
          DATABASE_URL: <postgresql://dev-db:5432/mydb>

  - name: my-flow-prod
    entrypoint: flows/my_flow.py:my_flow
    work_pool:
      name: prod-pool
      job_variables:
        env:
          ENVIRONMENT: production
          DATABASE_URL: <postgresql://prod-db:5432/mydb>

In code, read env:

import os
from prefect import flow

@flow(log_prints=True)
def my_flow():
    print("ENV:", os.environ.get("ENVIRONMENT"))
    # use DATABASE_URL, etc.

When to consider a parameter? - Use parameters for true business inputs (dates, IDs, feature flags), not for infra/environment selection. - If you must, keep it as a small override and default everything via job variables/variables/blocks. Docs: - Multiple deployments in prefect.yaml - Customize job variables - Prefect Variables - Secrets and Blocks - Work Pools If you share which parts vary by env (image, creds, resources, schedules, queues), I can sketch a concrete layout for your repo and prefect.yaml.