Admit before routing
Registration proves control; admission verifies capability, configuration, and policy. A new node or endpoint remains pending until checks succeed. Quarantine, suspended, draining, and retired are distinct from offline.
Pool API Architecture
Node & Endpoint Pool API
Control-plane patterns for machine nodes and delivery endpoints: identity, admission, readiness, health, routing, retries, replay, maintenance, and failover.
What this pool coordinates
One policy boundary for shared capacity
Node and endpoint pools coordinate actors at the edge of a system. Nodes accept scheduled workloads. Endpoints accept events or API traffic. Both need durable identity, verified membership, health state, policy, and a safe way to stop receiving work. Their data planes differ, but the control-plane patterns are closely related.
Architecture priorities
Build the contract before the marketplace
Separate liveness and readiness
A heartbeat can prove that an agent is communicating while still reporting that it cannot accept work. Endpoint health can show reachability while circuit policy keeps it paused. Schedule only when all required states agree.
Expect duplicate and delayed messages
Heartbeats, callbacks, and delivery events can arrive twice or out of order. Use sequence numbers, incarnations, stable event IDs, leases, and idempotent transitions. Reconciliation resolves uncertainty after partitions.
Make maintenance and failover explicit
Cordon stops new work, drain handles existing work, and quarantine responds to risk. Webhook failover can duplicate side effects, so destinations need shared event identifiers and idempotency.
Reference modules
The control-plane pieces
Use these modules as separate services or bounded components. Their contracts matter more than how many repositories contain them.
Reference module
Enrollment
Identity, credentials, ownership, verification, and admission.
Reference module
Health
Liveness, readiness, dependencies, capacity, and circuit state.
Reference module
Leases
Node work claims, fencing, heartbeat renewals, and reconciliation.
Reference module
Delivery
Signed event envelopes, attempts, backoff, jitter, and timeout.
Reference module
Replay
Same event identity, new attempts, bounded retention, and audit.
Reference module
Maintenance
Cordon, drain, quarantine, suspend, and retire actions.
Conceptual request
A concrete API shape
This example is an architecture pattern, not a live PoolAPI.com endpoint. It shows explicit identifiers, units, limits, and idempotency rather than hidden defaults.
POST /endpoints
{
"tenant_id": "org_01",
"url": "https://events.example.com/pool",
"events": ["allocation.committed"],
"routing_mode": "active_passive",
"timeout_ms": 5000
}Frequently asked questions
Common design decisions
Is a heartbeat the same as health?
No. A heartbeat proves communication; health and readiness describe whether the member should receive work.
Are webhooks exactly once?
No. Design for at-least-once delivery and make consumers idempotent.
What is draining?
Draining stops new work and handles active workloads or deliveries according to an explicit deadline and policy.
Why use fencing tokens?
They stop a stale node or lease from writing after the control plane has assigned a newer replacement.
Field notes
Go deeper
Compute Infrastructure · January 13, 2026
Node Pool API Design
A control-plane blueprint for node identity, heartbeats, capabilities, leases, maintenance states, failure domains, and safe scheduling.
node poolshealth checks
API Operations · April 30, 2026
Webhook Pool Reliability
How to build a multi-endpoint event delivery pool that survives duplicates, delays, rotations, partial outages, and tenant isolation failures.
webhooksendpoint pools
Compute Infrastructure · July 2, 2025
Compute Pool API
A scheduler-oriented guide to leases, resource shapes, queues, fairness, images, security, and telemetry for pooled compute capacity.
gpu computecontainers