docs: beef up "submit flows to dynamic infra" with realistic k8s example#20997
Draft
devin-ai-integration[bot] wants to merge 2 commits intomainfrom
Draft
docs: beef up "submit flows to dynamic infra" with realistic k8s example#20997devin-ai-integration[bot] wants to merge 2 commits intomainfrom
devin-ai-integration[bot] wants to merge 2 commits intomainfrom
Conversation
Add detailed examples showing how dependencies get into pods via custom images, a table of available k8s job variables, a dynamic memory sizing example, and a 'how it works under the hood' section explaining the relationship between the decorator, work pool base job template, and worker. Co-authored-by: Nate Nowack <nate@prefect.io>
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
zzstoatzz
requested changes
Mar 6, 2026
| ```python | ||
| @kubernetes( | ||
| work_pool="my-kubernetes-pool", | ||
| work_pool="my-k8s-pool", |
| To submit a flow to specific infrastructure, use the appropriate decorator for that infrastructure type. | ||
|
|
||
| Here's an example using `@kubernetes`: | ||
| Here's a basic example using `@kubernetes`: |
Collaborator
There was a problem hiding this comment.
you should have added an additional example, keeping the first one simple and adding this more idiosyncratic one second. furthermore making the example more complex and adding the word "basic" makes no sense
Comment on lines
+247
to
+253
| Here's what happens when you run `ml_pipeline()` on your laptop: | ||
|
|
||
| 1. `ml_pipeline` executes **locally** on your machine | ||
| 2. When it calls `train_model`, Prefect serializes the function and its arguments, uploads them to the object storage configured on `my-k8s-pool`, and submits a flow run to the work pool | ||
| 3. A worker polling `my-k8s-pool` picks up the run and creates a Kubernetes job using the work pool's **base job template** — a manifest that defines the shape of the `Job` spec (image, env vars, resource requests, etc.) | ||
| 4. Because `image` is passed in the decorator, it overrides the `{{ image }}` placeholder in the job template, so the pod runs **your custom image** with PyTorch installed | ||
| 5. The pod starts, downloads the serialized flow from object storage, executes it, and reports results back |
Collaborator
There was a problem hiding this comment.
why are you explaining all this? the goal was to add a scrutable example for someone who just "wants function on a k8s pod", not add concept docs
Comment on lines
+295
to
+303
| ## How it works under the hood | ||
|
|
||
| Understanding the relationship between the decorator, the work pool, and the resulting Kubernetes job helps demystify this feature: | ||
|
|
||
| 1. **Work pool** — A work pool of type `kubernetes` stores a **base job template**: a Kubernetes `Job` manifest with `{{ placeholder }}` variables like `{{ image }}`, `{{ namespace }}`, and `{{ env }}`. You can view and customize this template in the Prefect UI or via the CLI. | ||
|
|
||
| 2. **`@kubernetes` decorator** — When you add `@kubernetes(work_pool="my-k8s-pool", image="...")` to a flow, the extra keyword arguments (`image`, `namespace`, etc.) become **job variable overrides**. These replace the corresponding `{{ placeholder }}` values in the base job template when a run is created. | ||
|
|
||
| 3. **Worker** — A worker process polling the work pool receives the flow run, renders the final job manifest by merging the base template with the job variable overrides, and creates the Kubernetes `Job`. |
…age example Restore the original first example and customization section untouched. Remove the job variables table, numbered walkthrough, dynamic sizing example, and 'how it works' section. Keep only the new 'Running a flow with custom dependencies' subsection showing Dockerfile + image kwarg. Co-authored-by: Nate Nowack <nate@prefect.io>
devin-ai-integration
bot
changed the title
Contributor
Author
|
Addressed all comments — restored the original examples untouched, cut the job variables table / numbered walkthrough / dynamic sizing / "how it works" section. The only net-new content is the "Running a flow with custom dependencies" subsection (Dockerfile + |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves the "Submit Flows Directly to Dynamic Infrastructure" docs page to make the feature more approachable — specifically, making it obvious how dependencies get into the pod.
Motivated by a Bluesky conversation where the existing docs were too abstract for someone who just wants to "send a function to k8s."
Changes
image=in the@kubernetesdecorator so the pod runs your custom image instead of the default Prefect image/v3/how-to-guides/deployment_infra/manage-work-pools#base-job-template→/v3/advanced/customize-base-job-templatesAll existing examples and content are preserved as-is; the new content is purely additive.
Updates since last revision
Addressed reviewer feedback ("doing too much") — removed the job variables table, numbered walkthrough, dynamic infrastructure sizing example, and "How it works under the hood" section. Kept only the focused custom image example.
Checklist for reviewers
/v3/advanced/customize-base-job-templates,/v3/deploy/infrastructure-concepts/work-pools<Tip>block anddockerfilecode fence render correctly in Mintlify{{ image }}placeholder explanation is technically accurateChecklist
<link to issue>"mint.json.Link to Devin session: https://app.devin.ai/sessions/20f3e4d9c79447a6bf0359793371c702
Requested by: Nate Nowack (@zzstoatzz)