Zum Hauptinhalt springen

Service Discovery (Service Locator) — TOGETHER/CCA Platform

Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Status: Draft Author: Martin Riemann Date: 2026-07-21 Stakeholders: Platform / Operations, Architecture, Development Leads, Security

A platform-wide concept for how a service finds out where another service currently lives — without every consumer hardcoding hosts, and without a proxy sitting on the internal hot path. The goal is a single model where each application owns and publishes its own location, consumers resolve a stable logical name to the current address and connect directly, and moving or adding a service touches only that service — never its consumers, and never a central config file.

FieldValue
ScopeInternal service-to-service address resolution (HTTP/REST + SOAP-over-HTTP) across the on-prem app fleet, Fachtest + Prod
Primary jobLocation source of truth — resolve logical name → current base URL, connect directly. No forwarding, no load-balancing, no failover (yet)
RegistrationApp-owned manifest, published by the app's own delivery pipeline. Runtime self-registration is a documented upgrade path
Explicit non-goal (this doc)Runtime health-aware failover, client-side load-balancing, and the public api.togethercca.com route table — all designed for, none built here
ConsumersModern .NET (10/8/6) is the design target — the platform is consolidating onto it. The catalog is a plain JSON document, so not-yet-migrated apps can still read it during the transition, but legacy .NET Framework / Java are not design targets
Related workmonitoring-concept.md (health endpoints this can later consume); service-ip-ranges.md (the same "publish a machine-readable catalog" pattern)

How this relates to what already exists. Today there is no service-discovery layer: consumers hardcode targets in appsettings.json, some still point at the old internal proxy, and the YARP gateways carry their own static cluster/route config. This concept introduces the missing resolution layer. It does not replace the public YARP gateway (api.togethercca.com), IdentityServer, or per-app configuration wholesale — it removes physical location from consumer config and puts it behind a logical name.

Problem Statement​

Background — why now​

The platform is ~73 active services (App Insights, Feb 2026) spread across three application servers per environment, in three environments, with real drift between them and a set of "everyone depends on it" services. Service-to-service addresses are configured per consumer: a host or IP plus a path (https://TISAPP01/tis.my.service, sometimes https://1.2.3.4/tis.my.service) baked into each caller's appsettings.json.

An earlier attempt to fix this — api-intern, an internal reverse proxy — took the server-side approach: dependents only needed to know the proxy, and the real locations lived in one place (the proxy's config). It forwarded every call, which put a component on the internal hot path; that introduced latency/throughput problems and other caveats, and it was largely abandoned. The result today is the worst of both worlds: some apps still route through api-intern, most hardcode their targets, and there is no single, trustworthy answer to "where is service X right now?"

The trigger is concrete: replacing TISAPP003 (Windows Server end-of-support) with TISAPP03 in Fachtest. Several heavily-depended-on apps are blocking the migration, because moving one of them means editing and redeploying the appsettings.json of every consumer that points at it. The physical move is easy; the fan-out of configuration changes is what stalls.

Note: api-intern is not documented anywhere in the repository; its exact implementation and failure profile are taken from institutional memory and should be confirmed in review. It does not change the recommendation — the deliberate pivot below is away from any forwarding component, whatever the old one was built on.

Pain — the current state​

  • Location is copy-pasted, not referenced. The same host/IP lives in dozens of appsettings.json files. There is no source of truth; there are many stale copies.
  • A move = a fan-out of redeploys. Relocating one popular service forces coordinated config edits and redeploys across all its consumers. This is exactly what is blocking TISAPP003 → TISAPP03.
  • Environment drift is invisible. Because each consumer holds its own copy, Fachtest and Prod addresses diverge silently and nobody can see the whole picture.
  • The old fix made a new bottleneck. api-intern centralised the knowledge but did it by forwarding traffic — a proxy on every internal call. That is the mistake this concept must not repeat.
  • Mixed addressing. Some consumers target hostnames, some raw IPs — the IP-based ones are the most brittle of all.

Impact​

  • Migrations and decommissions are slow and risky — the direct cause of the current Fachtest blocker, and a recurring tax on every server refresh.
  • Onboarding a new dependency is manual — a developer hunts for the right host, per environment, and hardcodes it.
  • A relocation can cause an outage if one consumer's config is missed.
  • Two paths, no standard — new developers copy whichever pattern they saw last, so the inconsistency compounds.

Goals​

  • A stable logical name per service (reusing the existing tis.* taxonomy) that consumers bind to instead of a host/IP/path.
  • Apps own and publish their own location — adding or moving a service edits only that service's own manifest/deploy, never a central file and never a consumer.
  • Resolve-then-connect-directly — the resolution layer hands back an address; traffic never flows through it (no repeat of api-intern).
  • Off the hot path — resolution is cached locally with last-known-good fallback, so a discovery outage cannot take a consumer down.
  • First-class modern .NET resolution — via the Microsoft.Extensions.ServiceDiscovery client, on a language-neutral JSON contract that also bridges not-yet-migrated apps during the .NET consolidation.
  • Per-environment isolation — a Fachtest consumer resolves only Fachtest peers.
  • No cloud dependency for on-prem resolution — the resolution path stays available even if the Azure link is down.
  • Defined as code, reviewed, audited — manifests in git, published by pipeline (consistent with the platform's IaC direction).

Non-Goals (explicitly out of scope for this proposal):

  • Runtime health-aware failover and client-side load-balancing. There are no redundant instances yet; this is a future extension the model is designed for, not built here.
  • Replacing the public API gateway (api.togethercca.com) or its YARP routing. Discovery is internal. The .forward-files convergence is discussed as an alignment goal, not delivered here.
  • A service mesh (Istio/Linkerd/Consul Connect), mTLS-by-mesh, or sidecars. Far beyond the need.
  • Replacing IdentityServer or per-app configuration generally — only physical location moves out of consumer config.
  • First-class support for legacy .NET Framework and Java/Wildfly consumers. The platform is migrating everything to modern .NET, and new solutions may target it. The catalog stays language-neutral as cheap transitional insurance, but these runtimes are not design targets.

Foundational Principles (MUST)​

This section fixes the vocabulary and the few load-bearing decisions, so the team can apply the model consistently without re-litigating it. It is written as the ruleset this proposal asks to adopt.

1. Client-side discovery, not server-side​

There are two textbook shapes (microservices.io):

  • Server-side discovery — the consumer calls a router/proxy, which looks up the target and forwards the request. A load balancer or API gateway does this. This is what api-intern was, and its cost is a component on every internal call.
  • Client-side discovery — the consumer asks a registry "where is X?", gets an address back, and connects directly. The registry is consulted, not traversed.

The platform MUST use client-side discovery. It is precisely the "tell the caller the location instead of forwarding" behaviour asked for, and it structurally removes the bottleneck: the resolution component is off the data path, so it cannot throttle throughput or add per-call latency the way a proxy does.

2. Logical identity is stable; physical location is not​

A consumer MUST bind to a logical name — tis.gf.wgp — and nothing else. The host, IP, port, path, and even the environment binding are implementation details that MAY change at any time without touching the consumer. This single abstraction is what eliminates the migration fan-out: relocating a service changes what its name resolves to, not who knows about the service. The logical namespace MUST reuse the existing tis.* service taxonomy — no new naming scheme to learn.

3. Apps own their location; the platform only aggregates it​

The source of truth for "where am I and how do you reach me" MUST be a manifest that lives in the service's own repository, and it MUST be published by that service's own delivery pipeline. The discovery plane MUST NOT hold hand-maintained config; it is a read-model assembled from what each app declares. Adding or moving a service is a change to that service only. (This is the same principle behind the desired .forward-files direction for the public gateway — see Alignment.)

4. The registry is off the hot path — cache and degrade gracefully​

The platform already has hard single points of failure — "Ausfall von IdentityServer oder api-gateway = gesamte Plattform offline". Discovery MUST NOT add another. Therefore:

  • Consumers MUST cache resolved addresses locally and MUST persist a last-known-good copy to disk.
  • If the plane is unreachable, consumers MUST keep using the cache. A resolution outage is never worse than today's hardcoded config — which is exactly a frozen, local copy of the answer.
  • The plane MUST be consulted on a schedule or on cache-miss, and MUST NOT be consulted synchronously in the critical path of a downstream call.

This is the non-negotiable safety property, and it is what makes it acceptable to introduce a shared component at all.

5. Modern .NET first, on a language-neutral contract​

The platform is consolidating onto modern .NET (10/8/6), and this solution targets it directly — the first-class path is the Microsoft.Extensions.ServiceDiscovery client. The resolution contract MUST nonetheless be plain HTTPS + JSON (a static catalog is a JSON document), which costs nothing and conveniently lets a not-yet-migrated .NET Framework or Java app read the same catalog during the transition. Legacy runtimes are a bridge, not a design target.

6. Per-environment isolation and least authority​

Discovery MUST be scoped per environment (Development / Fachtest / Prod), so that cross-environment resolution is impossible by construction. Registration MUST be authenticated, and resolution data MUST be integrity-protected (a compromised catalog could redirect traffic). See Security & Integrity.

What We Are Building​

Four layers, each independently simple:

   APP REPOSITORY (owned by the team)              DELIVERY (Azure DevOps pipeline)
┌───────────────────────────────┐ ┌─────────────────────────────────┐
│ service.manifest.json │ ─ publish ─► │ inject {host, environment} at │
│ name · path · health · │ │ deploy time → emit a resolvable │
│ owner · protocols │ │ record for this env │
└───────────────────────────────┘ └──────────────┬──────────────────┘
│
▼
DISCOVERY PLANE (per environment · on-prem authority)
┌──────────────────────────────────────────────────────┐
│ services.{env}.json — the aggregated catalog │
│ tis.gf.wgp → https://TISAPP03/tis.gf.wgp │
│ tis.identity → https://TISAPP01/tis.identity │
│ │
│ Option A: static catalog file (no runtime service) │
│ Option B: thin registry service (SQL-backed, live) │
│ Option C: HashiCorp Consul │
└──────────────┬──────────────────────────────────────────┘
│ resolve = pull + cache (never traverse)
┌──────────────────────────────┼───────────────────────────────────────┐
▼ ▼ ▼
.NET 8+ consumer .NET Framework 4.x / Java (future) projections:
Microsoft.Extensions. plain HTTPS GET + local cache · AD DNS logical names
ServiceDiscovery · api-gateway .forward table
│ │
└───────────── connect DIRECTLY to the service ──────────────┘
(no proxy, no forwarding on the hot path)

The layers: (1) an app-owned manifest, (2) a publish-on-deploy registration step, (3) a per-environment discovery plane (the one open decision), and (4) a caching resolver in the consumer.

The Service Manifest (app-owned source of truth)​

Two parts combine into one resolvable record: what the repo knows (identity, shape) and what the deploy knows (host, environment).

Repo-owned — service.manifest.json, committed to the service's repository, environment-agnostic:

{
"name": "tis.gf.wgp",
"path": "/tis.gf.wgp",
"protocols": ["rest"],
"health": "/health/ready",
"owner": "team-gf",
"public": false
}

Deploy-supplied — the pipeline already knows the target host and environment, so it stamps them on at publish time and emits the resolvable record:

{
"name": "tis.gf.wgp",
"environment": "fachtest",
"baseUrl": "https://TISAPP03/tis.gf.wgp",
"health": "https://TISAPP03/tis.gf.wgp/health/ready",
"protocols": ["rest"],
"owner": "team-gf",
"revision": "2026-07-21T09:00:00Z"
}

This split is what makes migration trivial: the repo manifest never mentions TISAPP003 or TISAPP03; the host is a deploy-time fact. Redeploying the service to the new server republishes the record with the new baseUrl — nothing else in the platform changes. The health field is deliberately aligned with the /health/ready endpoint standardised in monitoring-concept.md, so the same signal can drive future failover (Non-Goal today) for free.

The Discovery Plane — decision pending​

The one real decision. All three options serve the same read contract (GET → services.{env}.json), so consumers are identical regardless; they differ in how registration lands and how much runs.

OptionHow it worksProsConsRuns
A — Static catalog (registry-less)CI aggregates all app manifests into a signed services.{env}.json published to an HA on-prem location (IIS/file share; optional CDN mirror). Consumers pull + cache.No runtime service to own; mirrors the existing service-ip-ranges.md pattern; git = audit/history/PR review; cannot itself be a runtime SPOF; zero cloud dependency."Registration" is publish-on-deploy, not live; catalog updates only when a pipeline runs (fine for the stated scope).Nothing new (a file + a CI step)
B — Thin registry serviceSmall ASP.NET service: POST /register (from pipeline or app startup) + GET /resolve, SQL Server-backed, on-prem per env.Enables runtime self-registration and, later, heartbeat/health → failover; richest catalog/API.A new service to build, host, secure, and keep available per environment; closest to "another moving part".1 small service + DB per env
C — HashiCorp ConsulAdopt the industry-standard registry; agents self-register; DNS + HTTP API; health checks built in.Purpose-built; native self-registration + health; mature; the right answer if full dynamic discovery/failover is the real goal.Cluster (3–5 servers) per environment to operate; BUSL licence (since 2023) review; agents on every host; well beyond a "location source of truth".Consul cluster per env

Lean (not a final decision): start with Option A. It is the lightest thing that satisfies every stated requirement — app-owned config, no central file, no cloud dependency, universal HTTPS, and it literally reuses a pattern the team has already proposed (the AWS-style ip-ranges.json in service-ip-ranges.md, right down to a syncToken). Because your scope is "locations change infrequently, on deploys and migrations", you do not need a live registry to solve the actual pain.

Keep Option B as the declared upgrade path. The day you want runtime self-registration in the literal sense, or health-aware failover once redundant instances exist, promote the plane from a static file to the thin registry — consumers do not change, because the read contract is identical. Option C becomes attractive only if the platform later commits to full dynamic discovery, health, and mesh-adjacent features across the board; for a static-ish VM estate of this size it is more machinery than the problem warrants.

On the word "self-registration": in Option A the app owns its manifest and its pipeline publishes it — registration performed by the app's own delivery, honouring "apps bring their own config, nothing central is touched." Option B adds runtime self-registration (the app calls the registry as it starts). Both are app-owned; A is declarative and lighter, B is live. Given the scope, A first.

Resolution — the consumer side​

Modern .NET (8+): adopt, don't build. Microsoft ships Microsoft.Extensions.ServiceDiscovery (the .NET Aspire library, usable standalone). It resolves a logical scheme (https://tis.gf.wgp) to a real endpoint via a configuration provider or DNS SRV, and plugs straight into HttpClient:

builder.Services.AddServiceDiscovery();                 // Microsoft.Extensions.ServiceDiscovery
builder.Services.ConfigureHttpClientDefaults(h => h.AddServiceDiscovery());

builder.Services.AddHttpClient("wgp", c => c.BaseAddress = new Uri("https://tis.gf.wgp"));
// "tis.gf.wgp" is resolved from configuration fed by the discovery catalog, then the
// HttpClient connects DIRECTLY to https://TISAPP03/tis.gf.wgp.

We ship a thin Tis.Hosting.Extensions helper (AddTisServiceDiscovery()) that wires this up and points the configuration provider at the environment's catalog, with local caching, last-known-good persistence, and periodic refresh (Principle 4). This is the entire custom footprint for the modern-.NET path — it keeps the project small.

Not-yet-migrated apps (transitional only): because the catalog is plain JSON, a legacy .NET Framework or Java app can resolve by a simple HTTPS GET of services.{env}.json and reading baseUrl by name. This is a bridge for the migration window, not a supported first-class path — new work targets modern .NET.

The one .NET gotcha we handle explicitly. A pooled/singleton HttpClient (SocketsHttpHandler) caches connections and does not pick up a changed address by default, which can defeat discovery after a relocation. The helper sets PooledConnectionLifetime (e.g. 2 minutes) so connections recycle and re-resolve, and re-resolves logical names on that cadence. This is called out because it is the classic way "our discovery didn't take effect" happens.

Not a bottleneck, not a SPOF — how we avoid the api-intern mistake​

Two independent guarantees, both structural rather than best-effort:

  1. Off the data path. Resolution returns an address; the consumer then talks to the service directly. No bytes of business traffic traverse the plane, so it cannot become a throughput or latency bottleneck — the specific failure of api-intern.
  2. Off the availability-critical path. With local caching + last-known-good (Principle 4), the plane can be down and every consumer keeps resolving from cache. Contrast the existing gateway/IdentityServer SPOFs: those are on the request path; discovery deliberately is not. Worst case degrades to exactly today's behaviour (a frozen local copy), never worse.

Security & Integrity​

A platform-wide map of "what is where" is both sensitive and safety-critical (a poisoned entry redirects traffic). Controls:

  • Authenticated registration. Publishing a record requires an authenticated principal — the pipeline's service connection (Option A) or an OAuth2 token from IdentityServer (Option B, matching the platform's existing introspection pattern). No anonymous writes.
  • Integrity-protected catalog. The catalog carries a syncToken/revision and is signed (or served over trusted internal transport with a checksum); consumers validate before trusting it. Mirrors the service-ip-ranges.md syncToken idea.
  • Read scoping. Resolution data stays internal (internal network / authenticated read); it is not a public endpoint.
  • Auditability. Every registration is a git commit (Option A) or an audited API write (Option B) — the DORA-friendly change trail the platform is already building toward.
  • Per-environment isolation enforced by separate catalogs; no record can point across environments.

Alignment with the API gateway (.forward direction)​

Out of scope to build here, but the design is deliberately compatible. The intended direction for the public gateway (api.togethercca.com, formerly api.servicebytogether.at) is for .forward route definitions to live in each application's own context and be published to the gateway, instead of sitting in a config folder in the gateway's repo — the same apps-own-their-config principle as this proposal.

The convergence: one app-owned manifest, multiple projections. The manifest that declares a service's internal location can also carry its public route intent; CI then projects it to (a) the internal discovery catalog (this proposal) and (b) the gateway's route table (the .forward goal). Designing the manifest with an optional routes/edge block now means the future gateway work is a new projection of the same data, not a second parallel system. We reserve the shape; we do not implement the gateway projection here.

Relationship to DNS​

You have full control of AD-based DNS, so DNS is a useful complement, not the backbone. Its limits for you: an A/CNAME resolves the host but not the /path your addresses include, and SRV records carry host+port but still not paths or rich metadata — so DNS alone cannot express TISAPP03/tis.gf.wgp. Two sound uses:

  • Logical host aliases. Introduce stable internal names (e.g. wgp.svc.together.internal → TISAPP03) so even non-participating/legacy clients gain one level of indirection; a migration becomes a DNS repoint. The catalog can project these records into AD DNS automatically.
  • Migrate IP-based consumers to hostnames. The IP/path addresses are the most brittle; moving them onto logical names (or at least DNS aliases) is a quick win regardless of which plane option is chosen.

Worked Example — the TISAPP003 → TISAPP03 migration​

The live blocker, before and after.

Today. tis.gf.wgp runs on TISAPP003. Say N services hardcode https://TISAPP003/tis.gf.wgp in their appsettings.json. Moving it to TISAPP03 means: edit N config files, redeploy N services, coordinate the cutover, and pray none were missed. That fan-out is why the migration is stalled.

With discovery. Consumers bind to the logical name tis.gf.wgp. The migration is:

  1. Deploy tis.gf.wgp to TISAPP03. Its pipeline publishes a new record: tis.gf.wgp → https://TISAPP03/tis.gf.wgp (revision bumped).
  2. The catalog updates (a) — no other repo is touched.
  3. Within one cache-refresh interval, every consumer resolves the new address and connects to TISAPP03. Zero consumer redeploys.
  4. Decommission TISAPP003.

The blocking apps are unblocked because relocating a service is now a property of that service's own deploy, which is exactly the thing being deployed anyway.

Adding a new service is the same story in miniature: commit a service.manifest.json, deploy, and it appears in the catalog — no central file edited, no discovery-plane change.

Alternatives Considered​

AlternativeProContraDisposition
Status quo — hardcoded appsettingsNo effortIs the problem statement: copy-paste locations, migration fan-out, silent driftRejected
api-intern redux — a server-side gateway/proxyOne place to configure locationsPuts a component on every internal call — the exact latency/throughput bottleneck that got it droppedRejected (Principle 1)
DNS-only (AD A/CNAME or SRV)Zero new infra; universal; always-on; you own ADCan't express host + path; no self-registration of full URLs; no metadata/catalogRejected as the backbone; adopted as a complement (see DNS section)
Azure App Configuration as the runtime sourceManaged; .NET-native refreshCloud dependency for on-prem resolution — violates the stated constraint and the platform's on-prem-resilience postureRejected for the hot path
HashiCorp ConsulIndustry standard; native self-registration + healthCluster per env to operate; BUSL licence review; far more than a location source of truthDeferred → Option C, only if full dynamic discovery/failover is later adopted
Netflix EurekaProven registryJava/Spring-centric; .NET client support is community/datedRejected (poor fit for a .NET-first shop)
Build a full custom registry nowTotal controlRisk of becoming the "giant project" you want to avoid; reinvents Microsoft.Extensions.ServiceDiscovery + ConsulRejected in favour of adopt-the-client + minimal plane (Option A/B)

Dependencies, Constraints, Risks​

  • Constraint — no cloud dependency on the resolution path. Rules out a cloud service as the runtime authority; the plane and cache are on-prem/local. (Shaped the rejection of App Configuration for the hot path.)
  • Constraint — must not become a SPOF. Enforced by client caching + last-known-good (Principle 4); the plane's own availability is therefore not platform-critical.
  • Design target — modern .NET. The platform is consolidating onto modern .NET, so the first-class client is Microsoft.Extensions.ServiceDiscovery. The language-neutral JSON catalog remains as cheap insurance and a bridge for apps still mid-migration; legacy .NET Framework / Java are not targets.
  • Dependency — a service inventory & dependency map. We need "who calls whom" to prioritise onboarding. Bootstrap it cheaply from the App Insights application map / dependency telemetry already in place, rather than a manual audit.
  • Dependency — pipeline change. Every participating service adds one publish step to its azure-pipelines.yml; ideally a shared pipeline template so it is one line per repo.
  • Risk — scope creep into a "giant project". Mitigated by adopting Microsoft.Extensions.ServiceDiscovery for the client and Option A for the plane; v1 custom code is a schema + a CI step + a caching helper. Guard this boundary explicitly.
  • Risk — the HttpClient/SocketsHttpHandler connection-cache gotcha defeating a relocation. Mitigated by PooledConnectionLifetime + re-resolution in the shared helper.
  • Risk — catalog poisoning / stale records. Mitigated by authenticated registration, signing/syncToken, and revision timestamps (Security section).
  • Risk — IIS idle/recycle breaks naïve runtime self-registration (Option B) — apps unloaded when idle stop heartbeating. Not a concern for Option A (publish-on-deploy); a design note for B.
  • Open — the Development environment. The survey shows Dev has no documented server infrastructure. Discovery may be Fachtest+Prod only; confirm.

Success Criteria​

  • A consumer resolves any in-scope service by its logical tis.* name; no host/IP/path literals for those services remain in consumer appsettings.json.
  • Moving a service to a new server requires changes to only the moved service's own deploy — zero consumer redeploys. (Validated by completing TISAPP003 → TISAPP03.)
  • Adding a service requires no edit to any central config file and no change to the discovery plane itself.
  • Resolution keeps working from last-known-good cache during a full discovery-plane outage; the outage takes no consumer down.
  • Logical resolution works from modern .NET services via Microsoft.Extensions.ServiceDiscovery; the catalog stays a plain JSON document a not-yet-migrated app could read during the transition.
  • Per-environment isolation verified — a Fachtest consumer cannot resolve a Prod endpoint, and vice-versa.
  • The previously-blocked Fachtest migration is completed using discovery as the pilot.

Roadmap​

Phased, dependency-aware. Durations indicative.

PhaseFocusKey outputsDepends on
0 — InventoryMap who-calls-whom and host-vs-IP addressingDependency map bootstrapped from App Insights; list of IP-based consumers—
1 — ContractManifest schema + logical naming (reuse tis.*) + catalog read formatAgreed service.manifest.json + services.{env}.json schemas0
2 — PlaneDecide A/B/C; stand it up in Fachtest firstDiscovery plane live in Fachtest; CI publish step (shared pipeline template)1 (plane decision)
3 — ResolverTis.Hosting.Extensions helper over Microsoft.Extensions.ServiceDiscovery + caching/fallback (modern .NET); document the raw-JSON bridge for apps still mid-migrationClient library + docs; DNS-refresh gotcha handled1
4 — Pilot = the migrationOnboard the blocked apps; complete TISAPP003 → TISAPP03Migration unblocked and done via discovery2, 3
5 — RolloutOnboard remaining services by criticality tier; retire hardcoded targets; migrate IP consumers to names; add AD DNS projectionHardcoded locations removed; Prod plane live4
6 — Future extensions(When needed) runtime self-registration / health-aware failover (Option B); .forward gateway projectionFailover-capable plane; unified manifest → gateway routes5

Open Questions / Decisions Needed​

QuestionContextNeeded by
Discovery plane — A (static catalog), B (thin registry), or C (Consul)?Lean is A now, B as upgrade path; C only for full dynamic discoveryPhase 2
Registration timing — publish-on-deploy (A/B) vs runtime self-registration (B)?Scope says static → publish-on-deploy suffices; runtime enables future failoverPhase 2
Where is the on-prem plane hosted, and how is it kept available?e.g. an IIS site on a web server per env + optional mirror; recall caching means brief downtime is tolerablePhase 2
Logical naming scheme — confirm reuse of tis.* verbatim as service IDs?Zero new naming to learn if yesPhase 1
Is the Development environment in scope?Survey shows no Dev server infrastructurePhase 0
Do we migrate IP-based consumers to hostnames as part of rollout?The most brittle addresses todayPhase 5
Confirm api-intern specifics (tech + failure profile)Undocumented; does not change the recommendation, but sharpens the write-upPhase 0
Ownership of the manifest schema, catalog, and client libraryA shared platform asset needs an ownerPhase 1

Next Steps​

  1. Stakeholder review of this proposal (Architecture, Platform/Ops, Dev Leads, Security).
  2. Decide the plane option (at least A-vs-B) and confirm the manifest/naming contract.
  3. Run Phase 0 — pull the dependency map from App Insights and list the IP-based consumers.
  4. Stand up the chosen plane in Fachtest and onboard the migration-blocking apps as the pilot.
  5. Graduate this document from proposal to living strategy once approved (alongside monitoring-concept.md).

Appendix​

References​

  • monitoring-concept.md — health-endpoint standard (/health/ready) this design can later consume for failover
  • service-ip-ranges.md — the same "publish a signed machine-readable catalog with a syncToken" pattern
  • api-services/project-structure.md — Tis.Hosting.Extensions, YARP usage, LTS/tis.* conventions
  • Repo README.md — the tis.* service taxonomy reused as the logical namespace

Review Notes:

DateReviewerFeedbackStatus
YYYY-MM-DDOpen