GitOps Bridge v2 poc

[csantanapr]

Related to #73

[xbuzz]

@csantanapr any traction on this? curious what the direction is after riv24.

[xbuzz]

Been playing with the branch since last year. Love the direction. Verified this on my end. Wanted to share w/ others as it's pretty subtle. Hope it's helpful.

(😊 feel weird about sharing ai responses but hey!)

Overview

When using ArgoCD’s matrix generator, placing a generator that emits a full metadata block alongside another generator that also produces metadata fields can result in silent key collisions. The later generator in the matrix silently overwrites earlier keys, which explains the comment:

"for reason this is need it as second in the matrix, if not the above extracting .tenants doesn't work"

This document explains the root cause, why ordering appeared to fix it, and how to properly resolve the issue.

---

Background

ArgoCD’s matrix generator combines two child generators by taking their Cartesian product, then merging each pair of output maps. If both child generators emit the same field key (e.g., metadata), the value from the child listed second wins and overwrites the first silently.

Example snippet from applicationsets.yaml:

generators:
  - matrix:
      generators:
        - clusters: {}
        - list:
            elements:
              - metadata:
                  labels:
                    tenant: foo
              - metadata:
                  labels:
                    tenant: bar

Here, both the clusters and the list generator emit metadata keys.

---

Problem: Silent Key Collision

• Key Overwrite: In a matrix generator, when two generators output the same key, the later one in the list silently overwrites the earlier value.
• Apparent "Fix" by Ordering: Placing the list generator second makes .metadata.labels.tenant available in the merged output, but only because it overwrote the cluster’s own metadata. Swapping the order removes the tenant label, breaking templates that expect it.

---

Root Cause

The core issue is the collision of the top-level metadata key between the two generators. Rather than a flaw in your template logic, it’s the merge behavior of the matrix generator.

---

Solutions

1. Avoid Key Collisions

Emit a unique key for tenant information instead of a full metadata block:

generators:
  - matrix:
      generators:
        - clusters: {}
        - list:
            elements:
              - tenant: foo
              - tenant: bar

Then reference {{ .tenant }} in your ApplicationSet template. No collision, no order dependency.

2. Use the Merge Generator with mergeKeys

If you need to combine fields from both generators, switch to a merge generator and explicitly declare mergeKeys:

generators:
  - merge:
      mergeKeys:
        - server
        - tenant
      generators:
        - clusters: {}
        - list:
            elements:
              - tenant: foo
              - tenant: bar

This ensures deterministic merging based on the declared keys.

3. Keep Generators Simple

Use simpler generators (e.g., a single list or git-directory) whenever possible. Reserve matrix or merge for truly orthogonal dimensions to avoid complexity and hidden merge behavior.

---

Next Steps

1. Update your applicationsets.yaml to remove the full metadata in the list generator.
2. Test both generator orders to confirm the collision is resolved.
3. Remove the comment about ordering once the merge logic is corrected.

This approach fixes the root cause and makes your ApplicationSet more maintainable.