Thanks for flagging this. On the Docker worker in Prefect 3.x,

extra_hosts

won’t be applied if you set it as a top-level job variable. It must be nested under

container_create_kwargs

, which is passed straight through to Docker’s container.create API. What to do - Put your hosts under

container_create_kwargs.extra_hosts

- You can use either dict or list-of-strings format; both are supported Examples - Dictionary format (preferred):

{
  "container_create_kwargs": {
    "extra_hosts": {
      "mydb": "10.0.0.15",
      "kafka": "192.168.1.20"
    }
  }
}

- List format (also works):

{
  "container_create_kwargs": {
    "extra_hosts": [
      "mydb:10.0.0.15",
      "kafka:192.168.1.20"
    ]
  }
}

Common gotchas - If you put

extra_hosts

at the top level of job variables (not under

container_create_kwargs

), it will be ignored by the Docker worker. - There was a bug in older Prefect 3.x releases where user-provided

extra_hosts

could clash with Prefect’s auto-injected host entry on Linux. This was fixed by merging values in Prefect 3.4.9+. If you’re on an older version, please upgrade. - Fix PR: prefect#18192 - Related issue: prefect#18187 - Docker API reference for

extra_hosts

(dict or list accepted): docker-py containers API How to verify - After running, check the container’s HostConfig.ExtraHosts:

docker inspect <container_id> | jq '.[0].HostConfig.ExtraHosts'

If you want to double-check where this belongs in your work pool template, you can fetch the default Docker base job template:

prefect work-pool get-default-base-job-template --type docker

If you’re still not seeing it propagate, can you share: - Your Prefect version (

prefect version

) - The worker type (confirm it’s “docker”) - The exact job variables JSON you’re using (sanitized)