Dienstkarte

Copied from the NETZlive docs

Copy of systeme/cluster/dienstkarte.md from the NETZlive docs site (~/Work/NETZlive/docs), taken 2026-10-09 while that directory was still uncommitted. The NETZlive site is authoritative; update there first. Code paths are prefixed with their repo so the links on this site resolve.

Inventory of services and clients across the four checked-out repos — redispatch, netzkoordinator, netzlive (umbrella), user-management — plus the nmk and grid_sensitivities hex packages they pull in. References carry the repo name as prefix; the rest of the path is relative to that repo’s root.

Snapshot

Taken 2026-10-08 from local checkouts. Services offered by repos that are not checked out (grid_state, BMH, the grid_sensitivities host) show up only as unmatched client targets. Regenerate rather than patch when it drifts: grep for use NL.Cluster.Service, use Netzlive.Cluster.Service, use NL.Cluster.Client, use Netzlive.Cluster.Client.

Library versions

Repo	Requirement	Locked
redispatch	"~> 2.9", repo: "netzlive" — redispatch/mix.exs:141	2.10.1
netzkoordinator	"~> 2.5" — netzkoordinator/mix.exs:100	2.5.0
netzlive	"~> 2.0" — netzlive/mix.exs:82	2.5.0
user-management	"~> 2.5.0" — user-management/mix.exs:77	2.5.0

Between 2.5.0 and 2.10.1 the registry, RPC and config modules differ only in docs and the added error_reporter option; unwrap: and compile-time option validation for clients came in 2.10. user-management’s ~> 2.5.0 pins it below 2.6.

Services

redispatch

Registered in a start phase, not as supervised children: redispatch/lib/redispatch/application.ex:341-348, declared in redispatch/mix.exs:58-61. They are tracked against the application-master process, so they stay registered as long as the application runs and there is no NL.Cluster.Monitor.

Name (= module)	NS	Version	Functions
Redispatch.Service.MasterDataV1	legacy	1.2.0	all_sr_ids_by_source/1,2, get_sr/1,2
Redispatch.Service.MasterDataV2	NL	2.2.0	same
Redispatch.Service.TopologiesV1	legacy	1.0.1	all_anschluss_uws/0, ust_uw_topology/0
Redispatch.Service.TopologiesV2	NL	2.0.0	same
Redispatch.Service.InfoV1	legacy	1.0.0	release_version/0, release_notes/0, release_build_time/0
Redispatch.Service.InfoV2	NL	2.0.0	same

Each V2 delegates to the V1 implementation modules. Source: redispatch/lib/redispatch/service/.

netzkoordinator

Added as supervisor children by add_configured_cluster_services/1 (netzkoordinator/lib/netzkoordinator/application.ex:204), driven by config and the Spannungsebene (voltage level, :hs high or :ms medium voltage) the instance runs for.

Name	NS	Version	Functions	Starts when
NL.Netzkoordinator.InfoService	legacy / NL	0.1.0 / 2.0.0	the three release_*	info_service_enabled and :hs
NL.Netzkoordinator.InfoServiceMs	legacy / NL	1.0.0 / 2.0.0	the three release_*	info_service_enabled and :ms
NK.Services.SwitchStateProjection	legacy	1.1.0	project/2	switch_state_projection_enabled and name set to this
NK.Services.SwitchStateProjection	legacy	2.2.0	project/1, aggregate/1	same
NK.Services.SwitchStateProjection	NL	3.0.0	project/1, aggregate/1	same
NK.Services.SwitchStateProjectionMS	legacy / NL	2.2.0 / 3.0.0	project/1, aggregate/1	name set to this

Production reads the switches from env (netzkoordinator/config/runtime.exs:119-124); the base deployment sets name NK.Services.SwitchStateProjection, both enabled, Spannungsebene hs (netzkoordinator/manifests/base/deployment.yaml:167-188). No checked-out overlay selects the MS variants.

Broken delegate in the MS service

netzkoordinator/lib/netzkoordinator/cluster_services/switch_state_projection_ms_v2.ex:54 delegates aggregate/1 to Netzkoordinator.Services.SwitchStateAggregationV1, which is not defined anywhere in the repo. Its siblings use Netzkoordinator.Application.SwitchStateAggregation. Calling it would crash on the provider and raise ServiceError on the client. Only reachable if an MS instance is deployed.

netzlive (umbrella)

One release containing all apps (netzlive/mix.exs:138-164).

Name	NS	Version	Offered by
Netzlive.Service.InfoV1	legacy and NL, same name and version	1.0.0	ui_app, start phase, netzlive/apps/ui_app/lib/ui_app/application.ex:62-63
NMK.Service.{Boundary, Context, Forecast, GridModelInstance, MeasurementLocalization, ResourceLookup, Search, Supply, VEBereiche}	NL (*V3 modules)	1.0.0 · 1.2.0 · 3.1.0 · 2.1.0 · 1.0.0 · 2.1.0 · 1.0.0 · 1.1.0 · 2.1.0	nmk_app, netzlive/apps/nmk_app/lib/nmk/application.ex:139-147
the same nine, name: __MODULE__ (e.g. NMK.Service.Supply)	legacy	same versions	netzlive/apps/nmk_app/lib/nmk/application.ex:130-138

The NMK service modules live in the nmk package (9.15.2 in netzlive). They declare retry: [after: 1_000, limit: 40_000] (Forecast [after: 5_000, limit: 60_000]).

user-management

Start phase, user-management/lib/user_management/application.ex:25-28.

Name	NS	Version	Functions
NL.UserManagement.AccountsService	NL	1.2.0	13: user and group queries, search/2, external-user CRUD
NL.UserManagement.EmailService	NL	1.2.0	send_email/1
NL.UserManagement.InfoService	NL	1.0.0	the three release_*

The EmailServiceV1 moduledoc’s client example uses to: UserManagement.ClusterServices.EmailServiceV1 — not the registered name. Copying it gives :noservice.

Clients

No repo calls NL.Cluster.call/4 directly, sets as: or a per-call timeout: on a client, or uses a do block. Each client is reached through a config key, so dev and test swap in RemoteServiceDoubles or Mox mocks.

Caller	Target	Version	NS	Provider
redispatch, NMK adapters (via nmk 9.18.0 clients)	NMK.Service.Supply / Boundary / Context / Search	1.1 / 1.0 / 1.1 / 1.0	NL	netzlive nmk_app ✓
redispatch, grid_sensitivities clients	GridSensitivities.Service.Submission / Query	1.1.0 / 1.4.0, with unwrap:	NL	not in these repos
redispatch, redispatch/lib/redispatch/adapters/grid_state_sensitivities.ex:5	GridState.Service.Sensitivities	2.0.0	legacy	not in these repos (grid_state)
redispatch, scenario-loadings adapter	GridState.Service.ScenarioProcess	1.1.0	legacy	not in these repos
redispatch, congestion-scenarios adapter	GridState.Service.Congestions	1.0.0	legacy	not in these repos
netzkoordinator, …/for_managing_users/user_management_service_adapter.ex:12	NL.UserManagement.AccountsService	1.1.0 / 1.2.0	NL	user-management ✓
netzkoordinator, …/for_sending_emails/email_service_adapter.ex:14	NL.UserManagement.EmailService	1.2.0	NL	user-management ✓
netzkoordinator, scenario_process_client.ex:5	GridState.Service.ScenarioProcess	1.0.0	legacy	not in these repos
netzkoordinator, switching_simulation_client.ex:6	GridState.Service.SwitchingSimulation	1.0.0	legacy	not in these repos
netzkoordinator, nmk_service_client.ex	NMK.Service.VEBereiche (calls the service module directly, legacy style)	2.1.0	legacy	netzlive nmk_app ✓
netzlive rd_grid_model_app	Redispatch.Service.TopologiesV1, Redispatch.Service.MasterDataV1	1.0.0	legacy	redispatch ✓
netzlive rd_grid_model_app	NMK.Service.Context	1.1.0	NL	netzlive nmk_app ✓ (same release)
netzlive gldpm2_app	BMH.Service.BetriebsmittelInfoV1	1.0.0	legacy	not in these repos
netzlive ui_app	Netzlive.Service.InfoV1	1.0.0	NL	itself
netzlive grid_state, congestions (via jobs package)	GridState.Service.Jobs, NL.Congestions.JobsService	0.1.0	legacy	not in these repos

Several legacy clients wrap calls in their own Retry loops (exponential_backoff() |> cap(10_000) |> expiry(120_000), rescuing NodeError) — the legacy API had no built-in retry.

Every NL client found has a provider in the same namespace and major version, except the grid_sensitivities ones, whose provider is outside these repos. The redispatch V2 services, all Info services, SwitchStateProjection 3.0.0 and user-management’s InfoService have no client in these repos.

Argument order mismatch: update_external_user

Provider, user-management/lib/cluster_services/accounts_service.ex:231:

defapi update_external_user(user_id, attrs, source), to: Dispatcher

Client, netzkoordinator/lib/netzkoordinator/driven_adapters/for_managing_users/user_management_service_adapter.ex:36:

defdelegate_api update_external_user(user_id, source, attrs),
  to: NL.UserManagement.AccountsService,

The client passes source as the second argument, the provider reads it as attrs. Both have arity 3, so lookup succeeds and nothing fails at the cluster layer. The netzkoordinator double (netzkoordinator/lib/netzkoordinator/driven_adapters/for_managing_users/remote_service_double.ex) follows the provider’s order, so dev and test do not show it. What the provider does with swapped arguments was not traced.

Effective call options

All NL.Cluster services above use the delegate form of defapi with options on use. Because of the delegate-form bug, those options are dropped:

Declared on use	Who	What actually runs
retry: [after: 1000, limit: 10]	redispatch V2s, netzkoordinator NL services, user-management Accounts and Info	60 s timeout, retry every 10 s, 210 s budget
retry: [after: 1000, limit: 3]	NL.UserManagement.EmailService	same
retry: [after: 1_000, limit: 40_000]	NMK V3 services	same

limit is in milliseconds. [after: 1000, limit: 10] reads like “ten attempts a second apart”, which is what the legacy retry_after/retry_limit options looked like — but if the bug were fixed today, it would mean one attempt plus one retry 0.1 s later (measured). Fixing the library changes every service’s retry behaviour at once; the declared values should be reviewed first.

For send_email/1 the current state matters most: a send that runs over 60 s is retried up to four more times — see A timeout re-runs the function.

Deployment und Knotennamen

Repo	Kind	RELEASE_NAME (rel/env.sh.eex:5)	Hostname annotation
redispatch	StatefulSet	${HOSTNAME}@${EXTERNAL_DNS}	yes, redispatch/manifests/base/statefulset.yaml:18
netzlive	StatefulSet	${HOSTNAME}@${EXTERNAL_DNS}	yes, netzlive/manifests/base/statefulset.yaml:17
netzkoordinator	Deployment	${HOSTNAME}@${EXTERNAL_DNS}	yes, netzkoordinator/manifests/base/deployment.yaml:15
user-management	Deployment	${HOSTNAME}@${POD_IP}	none — IP fallback

All four carry the netzlive/pod-type: cluster-service label and take RELEASE_COOKIE from their own secret. Whether the four secrets hold the same value cannot be seen from the repos.

Consequences, following Ein Aufruf → Was bei einem Deploy passiert:

• redispatch, netzlive: StatefulSet pod names are stable (…-0), so the node name survives a restart. The retry loop can bridge it.
• netzkoordinator, user-management: Deployment pod names change on every rollout, so the node name does too. In-flight retries keep calling the old name; clients of AccountsService and EmailService see RPCError or :noservice during a user-management rollout rather than a delay.

Prod topology config: redispatch uses the current form (redispatch/config/prod.exs:11-23, NL.Cluster.Strategy.Kubernetes). The other three still use the legacy config :netzlive_cluster, :config, topologies: … with Netzlive.Cluster.Strategy.Kubernetes (netzkoordinator/config/prod.exs:46-58, netzlive/config/prod.exs:22-34, user-management/config/prod.exs:8-20), which 2.x translates with a deprecation warning. redispatch sets topologies: [] in redispatch/config/config.exs:39 so dev and test do not try to reach a Kubernetes API.