flowfish/docs/migration-notes.md

Migration Notes

Operational upgrade notes for Flowfish.

---

v2.5.0 → v2.6.0

Summary

This release closes the L7 parity gap in the Integration Hub. L7 dependency summaries can now be filtered by annotation, label, owner/workload name and pod name (matching the L4 surface), and the Integration Hub fans BOTH-mode analyses out to L4 and L7 endpoints in parallel.

The release is backwards compatible for all existing API consumers. No data migration is required.

Breaking changes

None.

API surface changes

GET /api/v1/l7/dependencies/summary

New optional parameters:

Parameter	Type	Default	Notes
annotation_key	string	—	fnmatch glob supported
annotation_value	string	—	fnmatch glob supported
label_key	string	—	fnmatch glob supported
label_value	string	—	fnmatch glob supported
owner_name	string	—	Server-side alias for workload_name; workload_name takes precedence when both are supplied
pod_name	string	—	Case-insensitive substring match against L7Workload.name
workload_name	string	—	Case-insensitive substring match against L7Workload.name
filter_noise_annotations	boolean	false	Strips infrastructure annotation prefixes (kubectl.kubernetes.io/, kubernetes.io/, openshift.io/) from the response

Response shape additions:

• Every workload entry now includes is_matched: boolean.
  • With no filter active: is_matched=true on every entry (no neighbour expansion).
  • With any filter active: matched workloads are is_matched=true; their immediate neighbours are returned with is_matched=false so callers retain dependency context.
• The Neo4j query LIMIT is multiplied by 10 internally when a filter is active so post-filtering does not truncate results. Callers can still set their own limit upstream.

GET /api/v1/l7/dependencies/tree-summary

New optional parameter:

Parameter	Type	Default	Notes
workload_name_exact	boolean	true	Default preserves existing exact-match behaviour. Set false for case-insensitive substring match (mirrors L4 owner_name semantics).

OpenAPI

• analysis_id on both L7 endpoints is now typed as string to match the multi-cluster sub-analysis prefix already used at runtime.
• The namespace and include_metadata parameters on /l7/dependencies/summary are now explicitly listed in the spec (the runtime already supported them).

Frontend / Integration Hub changes

• The dedicated L7 Workload Search card has been removed. The unified Service Identification card now handles every analysis level.
• Namespace is now an orthogonal field — it applies to every identification method (annotation, label, namespace + deployment / workload, pod name, advanced), not just namespace_deployment.
• The namespace_deployment method label has been renamed to Namespace + Deployment / Workload for clarity across L4 and L7.
• BOTH-mode analyses fan out to L4 and L7 endpoints in parallel and render two preview tabs plus an L4/L7 snippet toggle.
• Snippet builders emit the full filter surface (annotation/label/owner_name/pod_name) for L4 and L7 alike. L7 tree snippets now always set workload_name_exact=false.

Behavioural changes operators should know

Behaviour	v2.5.0	v2.6.0
GET /l7/dependencies/summary with annotation filter	Filter parameters ignored; full namespace result returned.	Cypher CONTAINS pre-filter + Python fnmatch post-filter; only matched workloads + immediate neighbours returned.
Integration Hub with analysis_level=both	L4 endpoint only; L7 data missing in Preview and snippets.	Both endpoints queried in parallel; Network/Application tabs in Preview; L4/L7 toggle in Integration Code.
Integration Hub Service Identification card visibility	Hidden for L7 analyses (only the L7 Workload Search card shown).	Always visible.
tree-summary workload_name semantic	Exact match only.	Default exact (workload_name_exact=true); opt-in substring (workload_name_exact=false). The Integration Hub explicitly opts in.

Required actions

Audience	Action
Cluster operators	None — drop-in upgrade.
API consumers (read-only)	None — defaults preserve existing behaviour.
API consumers using the L7 tree-summary substring trick	Explicitly pass workload_name_exact=false.
Integration Hub snippet copy/paste users	Re-copy snippets after upgrading; new identification parameters are emitted.

Verification scenarios

After deploying v2.6.0, run the following smoke tests against any cluster:

1. L7 annotation filter parity. Start a BOTH analysis, then in the Integration Hub configure annotation_key=mycompany.com/project, annotation_value=NBA. Verify the workload count on the Application Dependencies (L7) tab matches what the Service Map renders for the same filter.
2. Pure L7 with namespace. Start an L7-only analysis, pick Namespace + Deployment / Workload, fill in a namespace + workload name. Verify the Preview lists matched workloads + neighbours and that the Integration Code emits the L7 query string.
3. Partial failure. Temporarily scale graph-query down (or simulate by blocking /l7/* at the gateway), launch a BOTH-mode query, and verify the L4 tab renders while the L7 tab shows an inline error banner.
4. Multi-cluster annotation. With two clusters connected, run the annotation filter scenario and verify workloads from both clusters appear with the correct cluster field. Frontend deduplication uses the (cluster, namespace, name) tuple — re-confirm there are no duplicates.
5. Backward compatibility. Call GET /api/v1/l7/dependencies/tree-summary from any existing pipeline without workload_name_exact; verify the response matches v2.5.0 exact-match behaviour.

---

Older releases

Pre-v2.5.0 release notes are not tracked in this file.