[cawthorne]

Summary

Adds per-DON-family gateway↔workflow pairing for local CRE topologies. Every nodeset declares don_family; workflow DONs connect only to gateway DONs in the same family, and each gateway worker serves only workflow DONs in that family.

The same don_family value flows through capabilities registry (DonFamilies), workflow registry (SetDONLimit per family), and env workflow deploy.

Previously, env start injected all gateway connectors into every workflow DON and registered every gateway worker against all workflow DONs — separate gateway nodesets in TOML did not isolate families.

Solution

Every nodeset requires don_family (workflow, gateway, capabilities, bootstrap, etc.). Gateway topologies validate the workflow↔gateway graph at env start and fail if any family is missing or unmatched.

[[nodesets]]
  name = "feeds-zone-a"
  don_family = "feeds-zone-a"
  don_types = ["workflow"]

[[nodesets]]
  name = "gateway-zone-a"
  don_family = "feeds-zone-a"
  don_types = ["gateway"]

Component	Before	After
Workflow DON config	All gateway connectors	GatewayConnectorsForDonFamily
Gateway worker jobs	All workflow DONs	GatewayServiceConfigsForGateway
Capabilities registry	Hardcoded default family	Each nodeset's don_family (required)
Workflow registry setup	Single family limit	SetDONLimit per workflow family
Workflow deploy (DON selection)	First workflow DON in state	--don-family (+ --shard-index), or --workflow-don-name
Workflow deploy (docker cp)	Manual --container-name-pattern	Defaults to {nodesets.name}-node from resolved DON
Env start logging	—	DonFamilyGatewayPairingSummary()

Matching is by don_family string equality at env start — not index, zone name, or nodeset order. Existing single-family CI topologies use don_family = "test-don-family" on every nodeset.

Example env-start log:

Gateway don_family pairs: feeds-zone-a → gateway-zone-a (don_family=feeds-zone-a), feeds-zone-b → gateway-zone-b (don_family=feeds-zone-b)

don_family must match across the stack

Stage	What uses don_family
Topology TOML (env start)	Pairing, node config, resolver defaults
Capabilities registry	DonFamilies: [don_family]
Workflow registry	SetDONLimit per family
Workflow deploy	Written into UpsertWorkflow
Workflow nodes (runtime)	Registry workflow sync filter

Workflow deploy target resolution

When local CRE state exists, deploy picks the workflow DON in this order:

1. --workflow-don-name — exact match on nodesets.name (escape hatch for shards and ambiguous families)
2. --don-family — unique workflow DON with that family; use --shard-index when several shard DONs share the family (e.g. shard0 / shard1 both test-don-family)
3. Single workflow DON — auto-selected when the topology has only one

--container-name-pattern is copy-only (docker cp substring). When omitted, it defaults to {resolvedDon.Name}-node (matches feeds-zone-a-node0, etc.).

Deploy guard: when both --workflow-don-name and --don-family are set, deploy errors if they disagree with local CRE state.

Multi-zone deploy (one family per zone — --don-family is enough):

go run . env workflow deploy \
  --don-family feeds-zone-a \
  --don-id <id> \
  ...

Sharded deploy (same family, multiple shard DONs):

go run . env workflow deploy \
  --don-family test-don-family \
  --shard-index 0 \
  ...

Explicit DON name:

go run . env workflow deploy \
  --workflow-don-name feeds-zone-a \
  ...

Deploy without local CRE state requires --don-family explicitly (no default family).

Test plan

• go test ./system-tests/lib/cre/...
• go test ./core/scripts/cre/environment/environment/...
• go build ./core/scripts/cre/environment/...
• CI CRE smoke/regression (grpc_source, E2E)
• Multi-zone Docker E2E via chainlink-data-feeds monitoring/local-cre

[github-actions]

✅ No conflicts with other open PRs targeting develop

[trunk-io]

     

View Full Report ↗︎ ⋅ Docs

[cl-sonarqube-production]

Quality Gate passed

Issues
1 New issue
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube

[bolekk]

Technically one DON can belong to multiple families. We will need that for sharding but can be extended later. Also it might be better to use "zone-a" here to reflect what's in prod.