133 lines
5.0 KiB
Markdown
133 lines
5.0 KiB
Markdown
# Agent Zones
|
|
|
|
## Purpose
|
|
|
|
An Agent Zone is MinerOps' durable network-reachability boundary. A Site is an
|
|
operational location and may contain networks that cannot be reached by one
|
|
Agent computer. Agent Zones let those networks remain within one Site without
|
|
making Site identity determine control routing.
|
|
|
|
The implemented relationship is:
|
|
|
|
```text
|
|
Site
|
|
-> Agent Zone
|
|
-> Agent installation
|
|
-> miners reachable through that Zone
|
|
```
|
|
|
|
`agent_id` remains the durable Agent-installation identity. Agent Zone identity
|
|
is a UUID independent of the Agent computer assigned to it.
|
|
|
|
## Site, Zone, And Agent
|
|
|
|
A Site groups rooms and operational records. An Agent Zone groups one or more
|
|
CIDR network ranges that are reachable from an Agent installation. The ranges
|
|
are factual Zone configuration for future enrollment and do not implement an
|
|
arbitrary routing table.
|
|
|
|
A Site can contain multiple Zones. For example:
|
|
|
|
```text
|
|
Plexus Mining Site
|
|
Main Room 10.30.0.0/24 -> Agent A
|
|
Room 2 10.40.0.0/24 -> Agent B
|
|
Immersion Room 10.50.0.0/24 -> Agent C
|
|
```
|
|
|
|
Zone names are unique case-insensitively among enabled Zones at the same Site.
|
|
They are not globally unique. A Zone can contain multiple canonical PostgreSQL
|
|
`CIDR` ranges.
|
|
|
|
## Routing Authority
|
|
|
|
Miner control resolves only from Hub-owned facts:
|
|
|
|
```text
|
|
miner UUID
|
|
-> miners.agent_zone_id
|
|
-> Agent assigned to that Zone
|
|
-> miner current IP recorded by MinerOps
|
|
-> local API3 operation
|
|
```
|
|
|
|
A control request from a browser contains none of the routing inputs. It cannot
|
|
select an IP address, Agent, Agent Zone, raw vendor command, credentials, or a
|
|
dry-run mode. MinerOps never falls back to another Agent merely because it is
|
|
assigned to the same Site.
|
|
|
|
A miner without a Zone is unavailable with `agent_zone_unassigned`. A missing
|
|
or disabled Zone is unavailable with `agent_zone_disabled`. A Zone without an
|
|
assigned Agent is unavailable with `agent_unavailable`.
|
|
|
|
## Durable Miner Ownership
|
|
|
|
`miners.agent_zone_id` is the authoritative reachability assignment. Snapshot
|
|
and discovery ingestion can assign a currently unassigned miner when the
|
|
authenticated Agent has a valid enabled Zone and Site boundaries agree.
|
|
|
|
An observation from a different Zone does not move an assigned miner. MinerOps
|
|
records or returns `agent_zone_conflict` or `site_conflict` while preserving the
|
|
existing assignment. Snapshot and discovery payloads may still be staged as
|
|
factual observations. Explicit administrative reassignment is deferred.
|
|
|
|
## Agent Assignment
|
|
|
|
Agent Zones v1 permits at most one Agent installation per non-null Zone. A Site
|
|
can therefore have multiple Agents when they occupy different Zones. Primary
|
|
and standby Agents, automatic failover, and Agent high availability are not
|
|
implemented.
|
|
|
|
An enabled Zone is usable for transitional check-in and control routing. A
|
|
disabled Zone preserves its durable associations but cannot be selected for a
|
|
new check-in and cannot route miner control.
|
|
|
|
## Check-In Compatibility
|
|
|
|
The Windows Agent may send `site_id` and optional `agent_zone_id` during
|
|
check-in. Existing configurations that omit `agent_zone_id` remain compatible:
|
|
|
|
- An established valid assignment is preserved.
|
|
- An unassigned Agent can resolve automatically only when the supplied Site has
|
|
exactly one enabled Zone.
|
|
- Zero enabled Zones returns `agent_zone_unavailable`.
|
|
- Multiple enabled Zones returns `agent_zone_ambiguous`.
|
|
- MinerOps never chooses the first Zone.
|
|
|
|
An explicit Zone must exist, be enabled, and belong to the supplied Site. An
|
|
Agent cannot move its established Zone or Site through check-in. Later
|
|
administrative Agent management will own reassignment.
|
|
|
|
## Permissions And APIs
|
|
|
|
The implemented management foundation reuses existing permissions:
|
|
|
|
- `GET /api/agent-zones` requires `agents.view`.
|
|
- `POST /api/agent-zones` requires `agents.manage`.
|
|
- `POST /api/agent/checkin` requires authenticated Agent identity.
|
|
|
|
The existing role matrix grants `agents.view` to Admin, Manager, Technician,
|
|
and Read Only. `agents.manage` is granted to Admin and Manager. No Agent Zone UI
|
|
is implemented in this milestone.
|
|
|
|
## Migration Compatibility
|
|
|
|
Migration 0016 creates one deterministic `Default Zone` for each pre-existing
|
|
Site. Existing miners and Agent assignments with a durable `site_id` are
|
|
backfilled to that Site's default Zone. Existing snapshots and discoveries are
|
|
associated when their durable Agent assignment makes that association factual.
|
|
Rows without a safe Site association remain unassigned.
|
|
|
|
Downgrade to migration 0015 is allowed only when the Zone configuration can be
|
|
represented by its one-Agent-per-Site model. Downgrade refuses before
|
|
structural changes when a Site has multiple Agents, non-default Zone topology,
|
|
custom Zone state, or network ranges.
|
|
|
|
## Future Relationship
|
|
|
|
One-time Agent enrollment tokens, Settings -> Agents, installer downloads,
|
|
Linux Agents, update management, administrative reassignment, and primary or
|
|
standby Agents are future work. An enrollment flow can use a Zone's configured
|
|
network ranges, but enrollment tokens and automatic range delivery are not
|
|
implemented by Agent Zones v1.
|