coulomb/railiance-fabric
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define deployment zone overlays

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-24 12:58:18 +02:00
parent e60e8d5bb4
commit ea2fa1203b
4 changed files with 316 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/FabricDiscoveryAndUpdate.md
View File

@@ -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 workstream, deployment stack, or business capability. Views do not define fabric
membership and should not mutate fabric boundaries. 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 ### Environment
An environment such as local, dev, staging, production, or lab is a deployment An environment such as local, dev, staging, production, or lab is a deployment
classification inside a fabric. It is not a fabric by itself. 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 ### Deployment Scenario
A deployment scenario is a realized or planned arrangement of services, A deployment scenario is a realized or planned arrangement of services,
machines, endpoints, automation, and configuration. It belongs inside a fabric machines, endpoints, automation, and configuration. It belongs inside a fabric
or subfabric but does not define the financial boundary. 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 ## Ownership Rule
Every node in the Fabric graph must carry owner information. 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; - king, lord, and tenant for financial responsibility actors;
- fabric and subfabric for durable responsibility boundaries; - fabric and subfabric for durable responsibility boundaries;
- view for diagnostic graph slices; - 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 ## State Hub Role

22
docs/financial-fabric-operator-guide.md
View File

@@ -26,6 +26,28 @@ It defines:
The baseline is not a security-zone model. Do not introduce realm, domain, or The baseline is not a security-zone model. Do not introduce realm, domain, or
identity-zone language into the Fabric core when updating it. 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 ## Refresh Loop
Run these checks from the `railiance-fabric` repo after changing declarations, Run these checks from the `railiance-fabric` repo after changing declarations,

33
docs/graph-explorer-contract.md
View File

@@ -89,6 +89,13 @@ Hosts should also include useful optional fields when available: `label`,
`freshnessState`, `confidence`, `visualSize`, `ownership`, `unresolved`, `freshnessState`, `confidence`, `visualSize`, `ownership`, `unresolved`,
`sourceReferences`, and `deepLinks`. `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: Edges may include layout hints used by the client-side layout engine:
`sameRepo`, `sourceRepo`, `targetRepo`, `layoutAffinity`, `sameRepo`, `sourceRepo`, `targetRepo`, `layoutAffinity`,
`layoutIdealLength`, and `layoutElasticity`. Fabric uses these hints to keep `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. | | `binding` | Binding assertions between consumer dependencies and providers. |
| `library` | Future library/SBOM inventory nodes. | | `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 Compatibility
Repo-scoping can adapt without a rewrite because its current graph payload Repo-scoping can adapt without a rewrite because its current graph payload
@@ -167,3 +198,5 @@ Host repos should own:
- authentication and authorization - authentication and authorization
- domain-specific graph modes - domain-specific graph modes
- deep links back to source systems - deep links back to source systems
- deployment overlay extraction from the route/proxy/deployment authority they
control

182
workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md Normal file
View File

@@ -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.