kestra-io / kestra-io/docs

[Docs] Document the reworked Assets dependencies graph (Tree/DAG, freshness, group-by, node panel) for 2.0

Open
#5,534 0 comments 0 reactions 1 assignee Claimed by @aj-emerich View on GitHub
area/docs
Dominant language
Astro
Stars
155
Forks
177
Avg merge
1d 20m
Merged PRs (30d)
192

Description

### Describe what's missing in our docs

### Describe what's missing in our docs

The Assets page (`src/contents/docs/07.enterprise/02.governance/01.assets/index.md`) documents declaring assets, types, auto-generation, triggers, export and dashboards, but has no section on the interactive **Dependencies graph** UI. Kestra 2.0 reworks that graph (epic k[estra-ee#10031](https://github.com/kestra-io/kestra-ee/issues/10031)), and none of the new behaviour is documented. Add one new section covering the four shipped pieces as a single feature.

**Ships in:** Kestra 2.0 (EE / Cloud).

### OSS vs EE (writer guidance, not published copy)

The whole new experience is asset-graph only and is EE / Cloud. The underlying dependencies-graph component is shared OSS code that also renders the flow, execution and namespace dependency graphs; those three views are unchanged in 2.0 (still force layout, no freshness, no group-by, no node panel). Do not imply Tree/DAG, freshness or group-by appear on non-asset dependency graphs, and do not touch their docs pages. The one OSS code change (edge `relation` plumbing) is invisible to users, so there is nothing to document there.

### Claude Suggested Placement

New H2, **"Explore the dependencies graph"**, after "Quick start: minimal asset flow" (the reader has declared assets and can now see them in the graph).

### What to document

1. **Tree / DAG toggle** ([kestra-ee#10207](https://github.com/kestra-io/kestra-ee/issues/10207)). DAG lays assets out deterministically (same layout every reload, ranked by longest path so a dbt staging-to-marts flow reads left to right). Tree keeps the force layout for exploring dense graphs. Explain when to reach for each.
2. **Freshness on every node** ([kestra-ee#10208](https://github.com/kestra-io/kestra-ee/issues/10208)). The five states (`fresh`, `stale`, `failed`, `never run`, `not tracked`), each shown by icon and colour (colour is never the only signal). A summary line answers "is anything wrong" above the graph, and a legend lists only the states present. Cadence is read from the producing flow's Schedule trigger, so there is no freshness policy to declare. Cover the "never report green when unsure" rules: no cadence means `not tracked`, a cadence with no run means `never run`. Add one sentence distinguishing this visual freshness from the existing `FreshnessTrigger` (a flow trigger that remediates), and cross-link both ways (add a pointer from the Operational automation section back here).
3. **Group by** ([kestra-ee#10209](https://github.com/kestra-io/kestra-ee/issues/10209)). A field select plus a searchable group picker. Hover a group fades the rest, click pins it, click again unpins, clicking empty canvas clears. In DAG, grouping also orders members adjacently within a column. Producer and consumer grouping are out of scope here (see follow-up).
4. **Node details panel and interaction model** (optional, more of a UI improvement) ([kestra-ee#10210](https://github.com/kestra-io/kestra-ee/issues/10210)). Present the interactions as a compact table: single click selects a node and opens the right-hand panel (status, full asset id, metadata, recent runs each linking to its execution); double click opens the node's own page; clicking empty canvas clears selection and any pinned group; hovering a table row highlights its node.

### Out of scope (follow-up when they land)

- Producer grouping depends on [kestra-ee#10196](https://github.com/kestra-io/kestra-ee/issues/10196) (persist producing task type), still open.
- Consumer grouping is [kestra-ee#10201](https://github.com/kestra-io/kestra-ee/issues/10201), still open.

File a follow-up docs issue to document producer/consumer grouping once both ship.

### Source material

- Epic: [kestra-ee#10031](https://github.com/kestra-io/kestra-ee/issues/10031)
- Demo video: in the epic (behaviour reference only)

https://github.com/user-attachments/assets/94f9e937-cba0-4d39-bf2d-ea1a75d93049

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.