Great question — in Prefect 2.19.3 the concurrency limit is a property of the work pool itself (not the Kubernetes job template). If you’re managing the pool with Terraform, set it directly on the

prefect_work_pool

resource via the

concurrency_limit

attribute. Here’s a minimal example. Keep your existing Kubernetes job template as-is; just add

concurrency_limit

at the top level:

terraform {
  required_providers {
    prefect = {
      source = "PrefectHQ/prefect"
    }
  }
}

# Configure the Prefect provider (API URL / key), omitted for brevity

resource "prefect_work_pool" "k8s_pool" {
  name              = "my-k8s-pool"
  type              = "kubernetes"
  description       = "Kubernetes work pool"
  concurrency_limit = 5  # limit concurrent flow runs dispatched by this pool

  # Keep your existing job template; this is just an example of wiring it in
  # If you already have it defined elsewhere, reference that instead.
  base_job_template = jsonencode(var.k8s_job_template)
}

Notes: -

concurrency_limit

is a non-negative integer. Omit it (or set to null) for no limit. - This limit applies across all workers in the pool — it’s not part of the Kubernetes job/ConfigMap. - You don’t need to change your

base_job_template

to control concurrency; it’s a pool-level setting. Docs: - Terraform resource docs: prefect_work_pool - Getting started with the provider: Provider guide If you already created the pool outside Terraform, you can import it into state and then manage

concurrency_limit

via Terraform. Want me to help adapt this to your exact `kubernetes_config_map`/template setup?

Got it — since you’re deploying the worker via the

prefect-worker

Helm chart, there are two different “limits” you can set: 1) Pool-level concurrency (hard cap across ALL workers in the pool) - Set via the Prefect API, UI, CLI, or Terraform provider — not via Helm. - In Terraform, use the Prefect provider’s

prefect_work_pool

resource and set

concurrency_limit

. Example:

terraform {
  required_providers {
    prefect = {
      source = "PrefectHQ/prefect"
    }
    helm = {
      source = "hashicorp/helm"
    }
  }
}

# Pool with a global concurrency cap
resource "prefect_work_pool" "k8s_pool" {
  name              = "my-k8s-pool"
  type              = "kubernetes"
  concurrency_limit = 10
  description       = "K8s work pool with a global limit"

  # Optional: if you manage job template at the pool-level via API instead of ConfigMap
  # base_job_template = jsonencode(...)
}

# Worker via Helm (points at the pool above)
resource "helm_release" "prefect_worker" {
  name       = "prefect-worker"
  repository = "<https://prefecthq.github.io/prefect-helm>"
  chart      = "prefect-worker"
  namespace  = "prefect"

  values = [
    yamlencode({
      worker = {
        replicaCount = 2
        config = {
          workPool = prefect_work_pool.k8s_pool.name
          # Optional per-pod limit below
          limit    = 5
          type     = "kubernetes"
        }
        cloudApiConfig = {
          accountId    = var.prefect_account_id
          workspaceId  = var.prefect_workspace_id
          cloudUrl     = "<https://api.prefect.cloud/api>"
          apiKeySecret = {
            name = "prefect-api-key"
            key  = "key"
          }
        }
      }
    })
  ]
}

2) Worker-level concurrency (per worker pod) - Set via the Helm chart using

worker.config.limit

(this maps to

prefect worker start --limit

). - If you run multiple replicas, total potential concurrency =

limit * replicaCount

(but the pool-level limit above will still cap globally). Minimal Helm values snippet:

values = [
  yamlencode({
    worker = {
      config = {
        workPool = "my-k8s-pool"
        limit    = 5   # per-worker concurrency
        type     = "kubernetes"
      }
      cloudApiConfig = {
        accountId    = var.prefect_account_id
        workspaceId  = var.prefect_workspace_id
        cloudUrl     = "<https://api.prefect.cloud/api>"
        apiKeySecret = {
          name = "prefect-api-key"
          key  = "key"
        }
      }
    }
  })
]

Key points: - Helm can’t set the work pool’s `concurrency_limit`; use the Prefect Terraform provider for that. - Helm sets per-worker limits via

worker.config.limit

. - If you only want a single global cap across the pool, set

concurrency_limit

on the pool and omit

worker.config.limit

. If you also want to throttle each pod, set both. References: - Terraform provider: prefect_work_pool resource - Prefect Helm charts: prefect-helm repo Do you want a hard global cap (pool-level), per-pod throttling, or both? I can tailor the exact `helm_release`/`prefect_work_pool` snippets to your setup.

Short answer: use the Prefect Terraform provider v2.x. There isn’t a strict coupling between Prefect 2.19.3 and a specific provider version; the provider talks to the Prefect API and the v2 series supports the resources you need (including

prefect_work_pool

with

concurrency_limit

). Recommended constraint:

terraform {
  required_providers {
    prefect = {
      source  = "PrefectHQ/prefect"
      version = "~> 2.0"
    }
  }
}

Notes: -

prefect_work_pool

and its

concurrency_limit

attribute are available in the v2 provider line. - If you want to be extra conservative on Prefect 2, you can pin to a specific 2.x version that your team validates, but

~> 2.0

is generally safe and keeps you on stable updates without jumping majors. Docs: - Provider: Terraform Registry: Prefect provider - Work pool resource: prefect_work_pool resource If you’d like, share your Terraform version and whether you’re targeting Prefect Cloud or self-hosted Server, and I can suggest a pinned provider version we’ve seen used commonly with 2.19.x.

Thanks — that context helps. TL;DR - For Prefect 2.19.3 (self-hosted), use the Prefect Terraform provider v2.x — but note it’s officially tested against Prefect 3, so Prefect 2 support is “best effort.” - Your Terraform v1.8.1 is likely too old for current v2 provider builds. Either upgrade Terraform first, or manage pool concurrency via CLI/API until you upgrade both Terraform and Prefect. What I recommend for your setup today - If you must automate now with Terraform 1.8.1: - You can try pinning an earlier 2.x provider release and validate, but there are no guarantees with TF 1.8.1 and Prefect 2.x Server. - Safer: set pool concurrency outside Terraform (CLI or REST) until you upgrade. Examples (no provider required) - CLI (works with self-hosted):

prefect work-pool set-concurrency-limit <pool-name> <limit>
prefect work-pool inspect <pool-name>

- REST against self-hosted Server (make sure your URL includes /api):

curl -X PATCH \
  -H "Content-Type: application/json" \
  http://<your-prefect-server>:4200/api/work_pools/<pool-name> \
  -d '{"concurrency_limit": 10}'

When you upgrade - After upgrading to Prefect 3 and a newer Terraform binary, use the latest v2 provider with a standard constraint:

terraform {
  required_providers {
    prefect = {
      source  = "PrefectHQ/prefect"
      version = "~> 2.0"
    }
  }
}

provider "prefect" {
  # For self-hosted Server:
  endpoint = "http://<your-prefect-server>:4200/api"
}

- Then manage pool concurrency in Terraform:

resource "prefect_work_pool" "k8s_pool" {
  name              = "my-k8s-pool"
  type              = "kubernetes"
  concurrency_limit = 10
}

Useful links - Provider: Terraform Registry: Prefect provider - Work pool resource: prefect_work_pool - Helm charts (for your worker deployment): prefect-helm repo If you’d like, I can help you test a specific provider version against your TF 1.8.1 and Prefect 2.19.3 Server, or script the CLI/REST approach as a temporary step in your pipeline.