From ea2fa1203b856269855ea92fa3fa477d8bef27a3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 24 May 2026 12:58:18 +0200 Subject: [PATCH] docs: define deployment zone overlays --- docs/FabricDiscoveryAndUpdate.md | 80 +++++++- docs/financial-fabric-operator-guide.md | 22 +++ docs/graph-explorer-contract.md | 33 ++++ ...deployment-zone-discovery-visualization.md | 182 ++++++++++++++++++ 4 files changed, 316 insertions(+), 1 deletion(-) create mode 100644 workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md diff --git a/docs/FabricDiscoveryAndUpdate.md b/docs/FabricDiscoveryAndUpdate.md index 9e278f9..c927380 100644 --- a/docs/FabricDiscoveryAndUpdate.md +++ b/docs/FabricDiscoveryAndUpdate.md @@ -91,17 +91,87 @@ Views can filter by repository, service, environment, machine, endpoint, tenant, workstream, deployment stack, or business capability. Views do not define fabric membership and should not mutate fabric boundaries. +Zone views are a special kind of view. They group the subgraph by deployment +environment, deployment scenario, routing authority, or access zone. They are +useful for questions such as: + +- which services are currently visible in private dev, shared test, or + production; +- which control surfaces appear in user-facing zones; +- which production surfaces still have unrestricted developer access; +- which routes exist in production but not in test; +- which early-access interfaces lack an explicit policy authority. + ### Environment An environment such as local, dev, staging, production, or lab is a deployment classification inside a fabric. It is not a fabric by itself. +Railiance uses these baseline environment terms: + +| Environment | Meaning | +|-------------|---------| +| `dev` | Private developer-local execution. Useful for debugging and discovery, but not shared truth for other developers unless explicitly published. | +| `test` | Shared central test stage for collaborators and friendly early-access users. | +| `prod` | Production execution. Alpha-stage developer access may exist now, but production must be able to move toward restricted operator access and applicable security and data-privacy controls. | + ### Deployment Scenario A deployment scenario is a realized or planned arrangement of services, machines, endpoints, automation, and configuration. It belongs inside a fabric or subfabric but does not define the financial boundary. +Current Railiance scenario names: + +| Scenario | Environment | Meaning | +|----------|-------------|---------| +| `bernd-laptop` | `dev` | Private local workstation scenario. It may discover useful loopback services and ports, but it is not a shared developer environment. | +| `coulombcore` | `test` | Central shared test-stage server for developers and friendly early-access users. | +| `railiance01` | `prod` | Production host. It is still alpha-accessible to developers, but the intended direction is restricted production access. | + +### Routing Authority + +A routing authority is the deployment component that maps an external name, +local URL, ingress host, or port to a backend service. Fabric discovers routing +authority output; it does not allocate ports or author routes. + +Examples: + +- local loopback process launch configuration for developer tools; +- Makefile or script defaults for local-only bootstrap surfaces; +- Docker Compose published ports; +- Kubernetes `Service`, `Ingress`, or controller-specific route manifests; +- Traefik, nginx, Caddy, HAProxy, or other reverse-proxy configuration; +- DNS records and TLS/certificate automation when they prove reachable names. + +### Access Zone + +An access zone is a visualization and discovery overlay that describes who a +surface is intended to be reachable by in a deployment scenario. It is not a +fabric boundary and does not define the policy itself. + +Useful initial access zones: + +| Access zone | Intended reach | +|-------------|----------------| +| `private-dev` | One developer's local machine. | +| `collaborator-test` | Collaborating developers in the shared test stage. | +| `early-access` | Friendly users participating in early access. | +| `production-public` | Production user-facing surfaces. | +| `production-admin` | Production administrative or control surfaces. | + +### Policy Authority + +A policy authority is the system expected to enforce access rules for a surface. +Fabric may record which authority is in play, such as NetKingdom IAM, an ingress +policy, network policy, or local-only loopback binding, but Fabric does not +define or enforce those rules. + +These terms let the graph say: "this service belongs to the Railiance primary +fabric, runs in the `coulombcore` test scenario, is routed by Traefik, and is +intended for the `early-access` zone." That is a deployment and access overlay, +not a change to fabric membership. + ## Ownership Rule Every node in the Fabric graph must carry owner information. @@ -277,7 +347,15 @@ For now, use: - king, lord, and tenant for financial responsibility actors; - fabric and subfabric for durable responsibility boundaries; - view for diagnostic graph slices; -- environment for deployment classification. +- environment for deployment classification; +- deployment scenario for a concrete place where services run; +- routing authority for the component that maps names or ports to services; +- access zone for the visualization overlay that groups intended reachability; +- policy authority for the external system expected to enforce access rules. + +Access zones may be security-relevant, but they are not Fabric security policy. +They are discovered and visualized evidence that helps operators spot misplaced +surfaces, missing policy authorities, or accidental exposure. ## State Hub Role diff --git a/docs/financial-fabric-operator-guide.md b/docs/financial-fabric-operator-guide.md index 6cf107f..ea9ee75 100644 --- a/docs/financial-fabric-operator-guide.md +++ b/docs/financial-fabric-operator-guide.md @@ -26,6 +26,28 @@ It defines: The baseline is not a security-zone model. Do not introduce realm, domain, or identity-zone language into the Fabric core when updating it. +## Deployment Overlay Baseline + +Fabric membership is not the same as deployment environment. Use these current +Railiance deployment overlays when interpreting discovery evidence: + +| Scenario | Environment | Access zone baseline | Notes | +|----------|-------------|----------------------|-------| +| `bernd-laptop` | `dev` | `private-dev` | Local machine used by one developer. Its loopback ports and local tools are useful evidence for debugging, but are not shared truth for other developers. | +| `coulombcore` | `test` | `collaborator-test`, `early-access` | Central test-stage server for collaborating developers and friendly early-access users. | +| `railiance01` | `prod` | `production-public`, `production-admin` | Production host. Developer access exists during alpha, but production should be able to move toward restricted operator access and applicable security and data-privacy controls. | + +The routing authority is the source that maps names or ports to services in a +scenario. For local dev this may be a Makefile, script, process launcher, or +loopback binding. For test and production this should usually come from +Kubernetes `Service` and `Ingress`, Traefik/nginx/Caddy/HAProxy configuration, +DNS, and TLS automation. + +Fabric should discover those routes and visualize the resulting zones. It +should not allocate ports, author reverse-proxy config, or define the access +policy. The policy authority is external evidence, such as NetKingdom IAM, +ingress policy, network policy, or local-only loopback binding. + ## Refresh Loop Run these checks from the `railiance-fabric` repo after changing declarations, diff --git a/docs/graph-explorer-contract.md b/docs/graph-explorer-contract.md index beb5d23..23a82f0 100644 --- a/docs/graph-explorer-contract.md +++ b/docs/graph-explorer-contract.md @@ -89,6 +89,13 @@ Hosts should also include useful optional fields when available: `label`, `freshnessState`, `confidence`, `visualSize`, `ownership`, `unresolved`, `sourceReferences`, and `deepLinks`. +Fabric hosts should also include deployment overlay fields when available: +`deploymentEnvironment`, `deploymentScenario`, `routingAuthority`, +`accessZone`, `policyAuthority`, `exposure`, and `host`. These fields describe +where an element runs or is reachable in a concrete deployment scenario. They +do not define fabric membership and must remain filter/grouping metadata unless +the host explicitly promotes a separate graph relationship with evidence. + Edges may include layout hints used by the client-side layout engine: `sameRepo`, `sourceRepo`, `targetRepo`, `layoutAffinity`, `layoutIdealLength`, and `layoutElasticity`. Fabric uses these hints to keep @@ -132,6 +139,30 @@ The first Fabric manifest declares: | `binding` | Binding assertions between consumer dependencies and providers. | | `library` | Future library/SBOM inventory nodes. | +## Zone Overlay Modes + +The graph explorer should support zone-oriented modes for Fabric payloads: + +| Mode | Purpose | +|------|---------| +| `fabric` | Group by financial responsibility: fabric, subfabric, owner. | +| `environment` | Group by `dev`, `test`, `prod`, or other deployment environment. | +| `deployment-scenario` | Group by concrete scenario such as `bernd-laptop`, `coulombcore`, or `railiance01`. | +| `routing-authority` | Group by loopback launcher, Compose port mapping, ingress controller, reverse proxy, DNS, or equivalent route authority. | +| `access-zone` | Group by intended reachability such as `private-dev`, `collaborator-test`, `early-access`, `production-public`, or `production-admin`. | + +Zone modes are diagnostic views. They answer "where does this run or who can +reach it here?" without mutating the underlying Fabric responsibility boundary. + +Useful warnings for the graph explorer include: + +- control surfaces in user-facing access zones; +- production nodes with unrestricted developer access; +- early-access routes without a policy authority; +- services present in production but missing from test; +- local-only surfaces that appear in shared or production scenarios; +- conflicting port or host claims within the same deployment scenario. + ## Repo-Scoping Compatibility Repo-scoping can adapt without a rewrite because its current graph payload @@ -167,3 +198,5 @@ Host repos should own: - authentication and authorization - domain-specific graph modes - deep links back to source systems +- deployment overlay extraction from the route/proxy/deployment authority they + control diff --git a/workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md b/workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md new file mode 100644 index 0000000..1c4c316 --- /dev/null +++ b/workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md @@ -0,0 +1,182 @@ +--- +id: RAIL-FAB-WP-0020 +type: workplan +title: "Deployment Zone Discovery And Visualization" +domain: railiance +repo: railiance-fabric +status: ready +owner: codex +topic_slug: railiance +created: "2026-05-24" +updated: "2026-05-24" +state_hub_workstream_id: "e70820a9-d6f3-473d-a17c-b15fe3180773" +--- + +# RAIL-FAB-WP-0020 - Deployment Zone Discovery And Visualization + +## Goal + +Improve Fabric discovery and visualization so operators can see which services +run in dev, test, and production deployment overlays without making Fabric the +authority for ports, routes, or access policy. + +This work follows the terminology in `docs/FabricDiscoveryAndUpdate.md`: + +- fabric/subfabric remain financial responsibility boundaries; +- deployment environment classifies lifecycle target: `dev`, `test`, `prod`; +- deployment scenario names the concrete place where services run: + `bernd-laptop`, `coulombcore`, `railiance01`; +- routing authority maps names or ports to backend services; +- access zone groups intended reachability for visualization; +- policy authority is the external system expected to enforce access rules. + +## Background + +The current local collision between the Fabric graph explorer port and the +NetKingdom control surface showed that Fabric should detect routing reality, +not organize it. The NetKingdom control surface now uses local port `8876`; +the Fabric registry and graph explorer use `8765`. + +Railiance currently treats: + +- the operator laptop as private `dev`; +- `coulombcore` as shared `test` for collaborators and friendly early-access + users; +- `railiance01` as `prod`, currently alpha-accessible to developers but moving + toward restricted production access. + +## T01 - Extend Discovery Overlay Model + +```task +id: RAIL-FAB-WP-0020-T01 +status: todo +priority: high +state_hub_task_id: "b8cf7d91-7743-4e58-9b13-ce99f2d9eef1" +``` + +Define schema/export fields for deployment overlays. + +Fields should cover: + +- `deployment_environment`; +- `deployment_scenario`; +- `routing_authority`; +- `access_zone`; +- `policy_authority`; +- exposure class, such as local-only, collaborator-test, early-access, + production-public, or production-admin; +- host, port, hostname, protocol, and route evidence where applicable. + +Done when identity projection, financial export, and graph-explorer payloads +have a clear place to carry these fields without changing fabric membership. + +## T02 - Discover Local Dev Routing Evidence + +```task +id: RAIL-FAB-WP-0020-T02 +status: todo +priority: high +state_hub_task_id: "b072e11b-08b5-426f-9f98-001abf8afd70" +``` + +Discover private developer-local routing evidence for `bernd-laptop`. + +Initial sources: + +- Makefile or script defaults; +- local process launcher command lines where durable enough; +- loopback URLs in docs and manifests; +- Docker Compose published ports; +- current known local surfaces such as Fabric registry `8765`, NetKingdom + control surface `8876`, State Hub API `8000`, State Hub MCP `8001`, and State + Hub dashboard `3000`. + +Done when local-only surfaces are marked as `deployment_environment: dev`, +`deployment_scenario: bernd-laptop`, and `access_zone: private-dev` with +provenance. + +## T03 - Discover Test And Production Routing Authorities + +```task +id: RAIL-FAB-WP-0020-T03 +status: todo +priority: high +state_hub_task_id: "91fc3f28-fbb9-43d2-bb46-44d179f4b485" +``` + +Discover routing authority evidence for `coulombcore` and `railiance01`. + +Initial sources: + +- Kubernetes `Service` and `Ingress` manifests; +- Traefik, nginx, Caddy, HAProxy, or equivalent proxy configuration; +- DNS and TLS/cert-manager evidence when present; +- Railiance infra and NetKingdom deployment documentation until executable + manifests are complete. + +Done when test-stage routes can be attributed to `coulombcore` and production +routes can be attributed to `railiance01`, with access zones flagged as +candidate values for operator review. + +## T04 - Add Zone Overlay Graph Explorer Modes + +```task +id: RAIL-FAB-WP-0020-T04 +status: todo +priority: high +state_hub_task_id: "664c2688-f45b-47bf-90ff-b17096a326fb" +``` + +Add graph explorer support for overlay views: + +- by fabric/accountability; +- by deployment environment; +- by deployment scenario; +- by routing authority; +- by access zone. + +The UI should make it easy to answer: + +- what is running in private dev, shared test, and production; +- what is production-facing on `railiance01`; +- what is early-access reachable on `coulombcore`; +- which control surfaces appear in user-facing zones; +- which routes have no discovered policy authority. + +Done when the graph explorer can group/filter by overlay fields and surface the +basic warnings without making policy decisions. + +## T05 - Preserve State Hub Read-Model Compatibility + +```task +id: RAIL-FAB-WP-0020-T05 +status: todo +priority: medium +state_hub_task_id: "1a5ef6f9-357f-4803-a1f8-ebd1ff5443fb" +``` + +Ensure State Hub can ingest and query the new overlay fields. + +Done when Fabric exports remain backward compatible, State Hub keeps importing +valid v1alpha2 exports, and overlay fields are visible enough for dashboard or +search views. + +## T06 - Publish Current Zone Inventory + +```task +id: RAIL-FAB-WP-0020-T06 +status: todo +priority: medium +state_hub_task_id: "a1b208e3-3321-4792-ba44-d32aba682183" +``` + +Run the improved discovery against the current Railiance workspace and publish a +reviewable zone inventory. + +Done when there is a saved artifact answering: + +- which local dev services are visible on `bernd-laptop`; +- which test-stage services are visible on `coulombcore`; +- which production services are visible on `railiance01`; +- which routes or ports are ambiguous, conflicting, or missing a policy + authority.