my prefect server setup
prefect-metrics.waow.tech
python
orchestration
document uv run --with pattern and tangled data source
- CLAUDE.md: fix stale worker image (3.11→3.14), add command override
pattern, per-deployment python version, requires-python rationale
- journey.md: add steps 10-11 covering ephemeral flow environments,
per-deployment python overrides, tangled.org data pipeline, and
upstream improvement candidates
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+77
-1
+5
-1
CLAUDE.md
+5
-1
CLAUDE.md
···
7
7
- push to both remotes: `origin` (tangled.org) and `github` (github mirror)
8
8
- after server restart, re-fetch kubeconfig with `just kubeconfig`
9
9
- flow code never goes in worker images or ConfigMaps — it's pulled at runtime via `git_clone`
10
-
- worker image is `prefecthq/prefect:3-python3.11-kubernetes` (the `-kubernetes` tag matters)
10
+
- worker image is `prefecthq/prefect:3-python3.14-kubernetes` (the `-kubernetes` tag matters; uv is pre-installed)
11
11
- `PREFECT_INTEGRATIONS_KUBERNETES_OBSERVER_NAMESPACES=prefect` is what makes namespace-scoped RBAC work
12
12
- kubernetes work pool base job template defaults namespace to `default` — must be `prefect`
13
+
- flow pods install deps via `uv run --with 'my-prefect-server @ git+https://github.com/...'` in the `command` job variable — this creates an ephemeral venv before pull steps run
14
+
- per-deployment overrides (e.g. `--python 3.13` for dbt compat) go in `work_pool.job_variables.command`, not at the deployment root
15
+
- requires-python is >=3.13 (not 3.14) so the enrich flow can run dbt under python 3.13
16
+
- we maintain prefect-dbt — never suggest replacing PrefectDbtOrchestrator with subprocess calls
+72
notes/journey.md
+72
notes/journey.md
···
264
264
└─────────────────────────────────────────────────────┘
265
265
```
266
266
267
+
## step 10: ephemeral flow environments with `uv run --with`
268
+
269
+
the original approach baked dependencies into the worker image or tried to install them during pull steps. this doesn't work because pull steps run *after* the container process starts — so the process needs deps before pull steps can provide them.
270
+
271
+
the solution is overriding the `command` job variable to use `uv run --with`:
272
+
273
+
```yaml
274
+
definitions:
275
+
work_pools:
276
+
k8s: &k8s
277
+
name: kubernetes-pool
278
+
job_variables:
279
+
command: >-
280
+
uv run
281
+
--with 'my-prefect-server @ git+https://github.com/zzstoatzz/my-prefect-server.git'
282
+
prefect flow-run execute
283
+
```
284
+
285
+
this creates an ephemeral venv per flow run with the project and all its deps installed, before `prefect flow-run execute` invokes pull steps. uv is pre-installed in the `prefecthq/prefect:3-python3.14-kubernetes` image.
286
+
287
+
references: [discussion #21185](https://github.com/PrefectHQ/prefect/discussions/21185), [discussion #18223](https://github.com/PrefectHQ/prefect/discussions/18223).
288
+
289
+
### per-deployment python version overrides
290
+
291
+
dbt-core doesn't support python 3.14 yet (mashumaro + pydantic v1 shim issues). rather than downgrading everything, the enrich deployment overrides `command` to use `--python 3.13`:
292
+
293
+
```yaml
294
+
- name: enrich
295
+
entrypoint: flows/enrich.py:enrich
296
+
work_pool:
297
+
name: kubernetes-pool
298
+
job_variables:
299
+
command: >-
300
+
uv run --python 3.13
301
+
--with 'my-prefect-server @ git+https://github.com/zzstoatzz/my-prefect-server.git'
302
+
prefect flow-run execute
303
+
```
304
+
305
+
uv downloads cpython 3.13 on-demand in the pod. this required lowering `requires-python` to `>=3.13` in both root and `packages/mps` pyproject.toml files.
306
+
307
+
### pitfall: `job_variables` placement
308
+
309
+
`job_variables` must go under `work_pool`, not at the deployment root level. prefect silently ignores it in the wrong location.
310
+
311
+
### pitfall: tangled.sh git protocol errors
312
+
313
+
`git+https://tangled.sh/...` intermittently fails with `fatal: protocol error: bad pack header` during uv resolution. using the github mirror (`git+https://github.com/...`) in the `--with` URL avoids this. the pull step still tries tangled.sh first (with github fallback), which works fine since git clone is more tolerant.
314
+
315
+
## step 11: tangled.org as a second hub data source
316
+
317
+
added tangled.org issues/PRs alongside github as a data source for the hub (hub.waow.tech).
318
+
319
+
### data pipeline
320
+
321
+
1. **`flows/tangled_items.py`** — fetches issues, PRs, and comments from the PDS (`pds.zzstoatzz.io`) via `com.atproto.repo.listRecords`. no auth needed — PDS records are public. resolves repo names from `sh.tangled.repo` records.
322
+
2. **`packages/mps/src/mps/tangled.py`** — models (`TangledItem`), PDS fetch helpers, URL builders for tangled.org
323
+
3. **`packages/mps/src/mps/db.py`** — `write_tangled_items()` persists to `raw_tangled_items` table in DuckDB
324
+
4. **dbt models**:
325
+
- `stg_tangled_items` — dedup view, excludes comments
326
+
- `int_tangled_items_scored` — scoring (recency only, no engagement data from PDS)
327
+
- `hub_action_items` — cross-source union mart replacing `github_action_items`
328
+
5. **hub frontend** — updated to read from `hub_action_items`, handles both sources with appropriate URL helpers
329
+
330
+
### what we learned about tangled/AT Protocol data
331
+
332
+
- issue/PR **state (open/closed) is NOT on the PDS** — the knot/appview tracks it server-side. `sh.tangled.repo.issue.state` records exist but are empty.
333
+
- the `repo` field on issues/PRs is an `at://` URI, not a name — need to resolve via `sh.tangled.repo` records
334
+
- labels are tracked via `sh.tangled.label.op` records (add/delete operations on AT URI subjects)
335
+
- activity volume is very low currently — full resync each run is fine
336
+
267
337
## what's next
268
338
269
339
- CI for flow registration on tangled (.tangled CI, not github actions)
270
340
- more interesting deployments with automations
271
341
- file upstream issue on prefecthq/prefect-helm for docket URL
272
342
- contribute guide back to prefect docs
343
+
- upstream: `job_variables` placement should be validated or warned about (silent ignore is surprising)
344
+
- upstream: consider a prefect recipe/docs page for the `uv run --with` pattern on kubernetes work pools