Skip to content

Commit a6cd7ff

Browse files
hyperpolymathhyperpolymath
committed
docs: substantive CRG C annotation (EXPLAINME.adoc)
1 parent a64b2df commit a6cd7ff

1 file changed

Lines changed: 95 additions & 19 deletions

File tree

‎EXPLAINME.adoc‎

Lines changed: 95 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,41 +3,117 @@
33
:toc:
44
:icons: font
55

6-
The README makes claims. This file backs them up.
6+
The README makes claims. This file backs them up with evidence from real code.
77

8-
[quote, README]
8+
== Core Claims & Evidence
9+
10+
=== Claim 1: "Join Kubernetes Nodes to ZeroTier Network via DaemonSet"
11+
12+
**From README** (lines 18-22, 49-52):
913
____
1014
Join Kubernetes nodes to a ZeroTier network and configure encrypted overlay routing.
15+
16+
* **Node join scripts** - DaemonSet-based ZeroTier agent deployment
17+
* **Routing table definitions** - Declarative route configuration
1118
____
1219

13-
== Technology Choices
20+
**Evidence**: `/var/mnt/eclipse/repos/zerotier-k8s-link/manifests/daemonset.yaml` defines a Kubernetes DaemonSet that deploys the ZeroTier agent to each node. `/var/mnt/eclipse/repos/zerotier-k8s-link/scripts/join-network.sh` automates network joining with node identity authorization.
1421

15-
[cols="1,2"]
16-
|===
17-
| Technology | Learn More
22+
**Caveat**: Implementation is *scaffolding stage*. DaemonSet manifest exists; full integration with Kubernetes node lifecycle management (node drain, taint/toleration) is incomplete.
1823

19-
| **Zig** | https://ziglang.org
20-
| **Idris2 ABI** | https://www.idris-lang.org
21-
|===
24+
=== Claim 2: "Declarative Route Configuration via Nickel Contracts"
25+
26+
**From README** (lines 72-73):
27+
____
28+
├── configs/
29+
│ ├── network.ncl # Nickel network definition
30+
│ ├── routes.ncl # Route table configuration
31+
│ └── firewall.ncl # Firewall rules
32+
____
33+
34+
**Evidence**: `/var/mnt/eclipse/repos/zerotier-k8s-link/configs/network.ncl` defines ZeroTier network parameters (network ID, IP range, DNS). `/var/mnt/eclipse/repos/zerotier-k8s-link/configs/routes.ncl` specifies overlay routing rules as Nickel contracts (validated at load time). `/var/mnt/eclipse/repos/zerotier-k8s-link/scripts/configure-routes.sh` applies validated route tables to live cluster.
35+
36+
**Caveat**: Routes are *syntactically valid* (Nickel validation). No formal proof that routing rules avoid loops, partitions, or blackholes.
37+
38+
=== Claim 3: "Integration Points: Twingate (External Access) + IPFS (Overlay Services)"
39+
40+
**From README** (lines 122-128):
41+
____
42+
=== With FlatRacoon Stack
43+
44+
* **twingate-helm-deploy** - External access routes through Twingate
45+
* **ipfs-overlay** - IPFS binds exclusively to ZeroTier interface
46+
* **poly-observability-mcp** - Mesh health monitoring
47+
____
48+
49+
**Evidence**: Integration specs at `/var/mnt/eclipse/repos/zerotier-k8s-link/docs/INTEGRATION.md`. Manifest references to Twingate deploy at `/var/mnt/eclipse/repos/zerotier-k8s-link/manifests/twingate-integration.yaml` (stub). IPFS peer discovery constrained to ZeroTier overlay via `/var/mnt/eclipse/repos/zerotier-k8s-link/configs/ipfs.ncl`.
50+
51+
**Caveat**: Integration is *planned*. Specs exist; implementation is partial. Twingate+ZeroTier handoff not tested in production.
2252

2353
== Dogfooded Across The Account
2454

25-
Uses the hyperpolymath ABI/FFI standard (Idris2 + Zig). Same pattern used across
26-
https://github.com/hyperpolymath/proven[proven],
27-
https://github.com/hyperpolymath/burble[burble], and
28-
https://github.com/hyperpolymath/gossamer[gossamer].
55+
Uses hyperpolymath network stack (Nickel config + ZeroTier overlay + Kubernetes orchestration). Same pattern across:
56+
- https://github.com/hyperpolymath/flatracoon-netstack[flatracoon-netstack] — Network stack umbrella (parent)
57+
- https://github.com/hyperpolymath/twingate-helm-deploy[twingate-helm-deploy] — External gateway (integrates)
58+
- https://github.com/hyperpolymath/ipfs-overlay[ipfs-overlay] — IPFS on ZeroTier (integrates)
59+
- https://github.com/hyperpolymath/poly-observability-mcp[poly-observability-mcp] — Health monitoring (integrates)
60+
61+
All share: *Declarative Nickel config, Kubernetes DaemonSet deployment, mesh network abstractions.*
2962

3063
== File Map
3164

32-
[cols="1,2"]
65+
[cols="1,3"]
3366
|===
34-
| Path | What's There
67+
| Path | Contents & Purpose
3568

36-
| `src/` | Source code
37-
| `ffi/` | Foreign function interface
38-
| `test(s)/` | Test suite
69+
| `manifests/daemonset.yaml` | Kubernetes DaemonSet: ZeroTier agent pod on all nodes, mounts host network NS, performs join
70+
71+
| `manifests/configmap.yaml` | ConfigMap: ZeroTier network config (network ID, allowed routes), shared to all nodes
72+
73+
| `manifests/secret.yaml` | Secret: ZeroTier API token, network join authorization tokens (one per node)
74+
75+
| `manifests/networkpolicy.yaml` | NetworkPolicy: Kubernetes pod communication rules, controls inter-pod access on overlay network
76+
77+
| `scripts/join-network.sh` | Node join automation: authenticates node identity with ZeroTier Central API, assigns overlay IP
78+
79+
| `scripts/configure-routes.sh` | Route configuration: applies validated routing rules from routes.ncl to live cluster
80+
81+
| `scripts/health-check.sh` | Connectivity verification: validates peer-to-peer connectivity, latency measurement, mesh health
82+
83+
| `configs/network.ncl` | Nickel network definition: ZeroTier network ID, IPv4 range (10.147.17.0/24), IPv6 space (fd00:feed:face::/48), DNS configuration
84+
85+
| `configs/routes.ncl` | Nickel route table: overlay routing rules (static routes, BGP-style announcements), validated as contracts
86+
87+
| `configs/firewall.ncl` | Nickel firewall rules: nftables/firewalld config for overlay interface, inbound/outbound policies
88+
89+
| `docs/TOPOLOGY.md` | Network topology documentation: node layout, peer discovery, IPFS service location
90+
91+
| `docs/INTEGRATION.md` | Integration specs: Twingate external access, IPFS binding, observability hooks
92+
93+
| `.machine_readable/6a2/STATE.a2ml` | Project state: 10% completion, scaffolding phase, DaemonSet implementation next
94+
95+
| `.machine_readable/6a2/META.a2ml` | Architecture decisions: Nickel for contracts, DaemonSet for deployment, ZeroTier Central for coordination
96+
97+
| `.machine_readable/6a2/ECOSYSTEM.a2ml` | Related projects: FlatRacoon parent, Twingate/IPFS/observability satellites
3998
|===
4099

100+
== Status
101+
102+
**Honest Assessment**: Scaffolding stage. Infrastructure (manifests, scripts, Nickel config structure) is in place. Core implementation (DaemonSet lifecycle, route automation, integration tests) is partial.
103+
104+
**What's Ready**:
105+
- DaemonSet manifest
106+
- Node join script
107+
- Nickel config contracts
108+
- Route/firewall config structure
109+
110+
**What's Incomplete**:
111+
- Full DaemonSet lifecycle (node drain, taint/toleration)
112+
- Route automation against live cluster
113+
- Twingate integration tests
114+
- IPFS overlay binding
115+
- Health monitoring
116+
41117
== Questions?
42118

43-
Open an issue or reach out directly — happy to explain anything in more detail.
119+
Open an issue or reach out at j.d.a.jewell@open.ac.uk — happy to explain the ZeroTier mesh topology, Nickel config contracts, or FlatRacoon integration strategy.

0 commit comments

Comments
 (0)