Update packaging guide for multi-node fleet topology

Reflect that the platform now spans multiple nodes (rift for compute,
svc for public edge routing, orion provisioned but offline). Add Fleet
Topology section, update deploy steps to include TLS cert provisioning
from Metacrypt CA, DNS registration in MCNS, and gRPC-based mc-proxy
route registration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-02 15:14:23 -07:00
parent 0b11899a9b
commit 979a64a854

View File

@@ -9,8 +9,8 @@ the platform's internals.
## Platform Overview ## Platform Overview
Metacircular is a multi-service infrastructure platform. Services are Metacircular is a multi-service infrastructure platform. Services are
Go binaries running as containers on Linux nodes, managed by these core Go binaries running as containers across a fleet of Linux nodes,
components: managed by these core components:
| Component | Role | | Component | Role |
|-----------|------| |-----------|------|
@@ -21,8 +21,27 @@ components:
| **MCNS** (DNS) | Authoritative DNS for `*.svc.mcp.metacircular.net` | | **MCNS** (DNS) | Authoritative DNS for `*.svc.mcp.metacircular.net` |
The operator workflow is: **build image → push to MCR → write service The operator workflow is: **build image → push to MCR → write service
definition → deploy via MCP**. MCP handles port assignment, route definition → deploy via MCP**. MCP handles port assignment, TLS cert
registration, and container lifecycle. provisioning, route registration, DNS registration, and container
lifecycle.
### Fleet Topology
The platform runs across multiple nodes connected via Tailnet:
| Node | Role | OS | Arch | Purpose |
|------|------|----|------|---------|
| **rift** | Compute + core infra | NixOS | amd64 | Runs most services (Metacrypt, MCR, MCNS, etc.) |
| **svc** | Edge | Debian | amd64 | Public-facing mc-proxy, routes traffic over Tailnet to compute nodes |
| **orion** | Compute | NixOS | amd64 | Provisioned, currently offline |
**Node roles:**
- **Compute nodes** (rift, orion, future RPis) run the full container
lifecycle via rootless Podman.
- **Edge nodes** (svc) run mc-proxy for public traffic routing only.
The MCP agent on edge nodes manages mc-proxy routes but does not run
application containers.
--- ---
@@ -34,7 +53,7 @@ registration, and container lifecycle.
| Container engine | Docker or Podman (for building images) | | Container engine | Docker or Podman (for building images) |
| `mcp` CLI | Installed on the operator workstation | | `mcp` CLI | Installed on the operator workstation |
| MCR access | Credentials to push images to `mcr.svc.mcp.metacircular.net:8443` | | MCR access | Credentials to push images to `mcr.svc.mcp.metacircular.net:8443` |
| MCP agent | Running on the target node (currently `rift`) | | MCP agent | Running on the target node (`rift` for services, `svc` for edge routing) |
| MCIAS account | For `mcp` CLI authentication to the agent | | MCIAS account | For `mcp` CLI authentication to the agent |
--- ---
@@ -320,14 +339,20 @@ recreates the containers.
### What Happens During Deploy ### What Happens During Deploy
1. Agent assigns a free host port (1000060000) for each declared route. 1. Agent assigns a free host port (1000060000) for each declared route.
2. Agent starts containers with `$PORT` / `$PORT_<NAME>` environment 2. For L7 routes, agent provisions a TLS certificate from Metacrypt CA
(via `POST /v1/engine/request`). Certs are written to
`/srv/mc-proxy/certs/<service>.pem` and `.key`. Existing valid certs
(more than 30 days from expiry) are reused.
3. Agent starts containers with `$PORT` / `$PORT_<NAME>` environment
variables set to the assigned ports. variables set to the assigned ports.
3. Agent registers routes with mc-proxy (hostname → `127.0.0.1:<port>`, 4. Agent registers routes with mc-proxy via gRPC (hostname →
mode, TLS cert paths). `<node-address>:<port>`, mode, TLS cert paths).
4. Agent records the full state in its SQLite registry. 5. Agent registers DNS entries in MCNS for
`<service>.svc.mcp.metacircular.net`.
6. Agent records the full state in its SQLite registry.
On stop (`mcp stop <service>`), the agent reverses the process: removes On stop (`mcp stop <service>`), the agent reverses the process: removes
mc-proxy routes, then stops containers. DNS entries, removes mc-proxy routes, then stops containers.
--- ---
@@ -747,9 +772,9 @@ For reference, these services are operational on the platform:
|---------|---------|------|---------| |---------|---------|------|---------|
| MCIAS | v1.9.0 | (separate) | Identity and access | | MCIAS | v1.9.0 | (separate) | Identity and access |
| Metacrypt | v1.4.1 | rift | Cryptographic service, PKI/CA | | Metacrypt | v1.4.1 | rift | Cryptographic service, PKI/CA |
| MC-Proxy | v1.2.1 | rift | TLS proxy and router | | MC-Proxy | v1.2.1 | rift, svc | TLS proxy and router (svc handles public edge) |
| MCR | v1.2.1 | rift | Container registry | | MCR | v1.2.1 | rift | Container registry |
| MCNS | v1.1.1 | rift | Authoritative DNS | | MCNS | v1.1.1 | rift | Authoritative DNS |
| MCDoc | v0.1.0 | rift | Documentation server | | MCDoc | v0.1.0 | rift | Documentation server |
| MCQ | v0.4.0 | rift | Document review queue | | MCQ | v0.4.0 | rift | Document review queue |
| MCP | v0.7.6 | rift | Control plane agent | | MCP | v0.7.6 | rift, svc | Control plane agent |