Docs / Architecture / Node

Node Architecture

Understand how GeoServer nodes process, route, and scale geospatial workloads across distributed environments.

Last updated: Nov 14, 2024 • v3.2.1

Overview

In GeoServer's distributed architecture, a Node represents an independent computational unit responsible for handling specific geospatial operations. Nodes communicate via a secure gossip protocol and can be dynamically provisioned to handle spikes in rendering requests, data ingestion, or spatial analytics.

💡 Architectural Note Nodes are stateless by default. Persistent spatial indices and tile caches are offloaded to the dedicated Storage Tier or managed via Redis-backed distributed caching.

Node Types

GeoServer supports four primary node profiles, each optimized for distinct workloads:

Type Primary Role Typical Scale Protocol
compute Vector rendering, spatial queries, geoprocessing 4–16 vCPUs gRPC / HTTP/2
edge Request routing, JWT validation, rate limiting 2–4 vCPUs HTTP/3 / WebSocket
storage Tile caching, raster indexing, backup coordination NVMe optimized S3 / POSIX
api REST/GraphQL gateway, schema management 4–8 vCPUs REST / GraphQL

Configuration

Nodes are configured via geoserver.yaml or environment variables. Below is a minimal example for a compute node:

geoserver.yaml
# Node identity & cluster membership
node:
  id: "compute-us-east-01"
  type: "compute"
  cluster: "prod-atlantic"
  region: "us-east-1"

# Resource limits & thread pools
resources:
  max-threads: 16
  memory-limit: "8Gi"
  geo-cpu-priority: 90

# Spatial processing defaults
processing:
  default-crs: "EPSG:4326"
  tile-size: 256
  cache-ttl: "3600s"
  vector-batch: 10000

# Network & health
network:
  listen: "0.0.0.0:8080"
  gossip-port: 45000
  health-interval: "15s"

API Reference

The Node Management API allows programmatic scaling, health inspection, and graceful shutdown. All endpoints require Bearer authentication with cluster admin privileges.

Method Endpoint Description Status
GET /api/v3/nodes List active nodes with metadata & load metrics Stable
POST /api/v3/nodes/{id}/scale Trigger horizontal scaling or resource rebalance Stable
GET /api/v3/nodes/{id}/health Deep health check: disk, memory, spatial index, network Stable
DELETE /api/v3/nodes/{id}/drain Gracefully drain connections before shutdown Beta

Health & Monitoring

Nodes expose a Prometheus-compatible metrics endpoint at /metrics on the management port. Key metrics include:

⚠️ Production Warning Do not disable the gossip protocol in production. Node isolation will cause spatial index fragmentation and render timeouts. Always configure health-interval ≤ 30s.

Next Steps

Now that you understand how nodes operate, you can configure your cluster topology or dive into the routing layer.

📖 Cluster Management Guide • ⚙️ YAML Configuration Reference • 🔌 WebSocket API Docs

"}