Control Plane

Fleet management for Sentinel reverse proxies. Declarative configuration distribution with safe rollouts, real-time monitoring, and audit logging.

The Sentinel Control Plane is a fleet management system for Sentinel reverse proxies. It handles configuration distribution, rolling deployments, and real-time node monitoring — built with Elixir/Phoenix and LiveView.

How It Works

KDL Config
Compile & Sign
Immutable Bundle
Rollout
Nodes Pull & Activate
  1. Define services, upstreams, certificates, and middleware through the web UI or API
  2. Compile into an immutable, signed bundle (.tar.zst with manifest, checksums, and SBOM)
  3. Create a rollout targeting nodes by labels, groups, or environments
  4. Deploy with batched progression, health gates, and automatic pause on failure
  5. Nodes pull the bundle, verify the Ed25519 signature, and activate

Every mutation is recorded in a tamper-evident audit log.

Architecture

┌─────────────────────────────────────────────────┐
│              Control Plane (Phoenix)             │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ LiveView │  │ REST API │  │    GitOps     │  │
│  │    UI    │  │ GraphQL  │  │   Webhooks    │  │
│  └────┬─────┘  └─────┬────┘  └────────┬──────┘  │
│       │              │                │          │
│  ┌────┴──────────────┴────────────────┴───────┐  │
│  │           Contexts (Business Logic)        │  │
│  │  Bundles · Nodes · Rollouts · Audit · WAF  │  │
│  └────┬──────────────┬────────────────────────┘  │
│       │              │                           │
│  ┌────┴─────┐  ┌─────┴──────┐                    │
│  │ Postgres │  │  S3/MinIO  │                    │
│  │  (state) │  │ (bundles)  │                    │
│  └──────────┘  └────────────┘                    │
└─────────────────────────────────────────────────┘
         │                          ▲
         │  Rollout assigns bundle  │  Heartbeat + status
         ▼                          │
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Sentinel   │  │  Sentinel   │  │  Sentinel   │
│   Node A    │  │   Node B    │  │   Node C    │
└─────────────┘  └─────────────┘  └─────────────┘

Features

Configuration Management

  • Services — Routes with upstream targets, load balancing, timeouts, retries, and caching
  • TLS Certificates — Upload or auto-provision via ACME/Let's Encrypt with expiry tracking
  • Middlewares — Rate limiting, CORS, caching, compression, request/response transforms
  • Auth Policies — JWT, API key, Basic, OAuth2, OIDC, and composite authentication
  • Secrets — AES-256-GCM encrypted at rest with rotation and per-environment scoping
  • Service Topology — Visual graph of services, upstreams, middlewares, and policies

Bundle Pipeline

  • Immutable Bundles — Content-addressed .tar.zst archives with SHA256 hashing
  • Ed25519 Signing — Cryptographic bundle verification on every node
  • SBOM Generation — CycloneDX 1.5 for supply chain visibility
  • Risk Scoring — Automatic risk assessment comparing each bundle against its predecessor
  • Config Validation — Custom rules (required fields, forbidden patterns, size limits, JSON Schema)
  • Promotion Pipeline — Promote bundles through dev, staging, and production

Deployment & Rollouts

  • Rolling — Deploy in batches with health gates between steps
  • Canary — Gradually shift traffic to the new configuration
  • Blue-Green — Deploy to standby slot, shift traffic, then swap
  • All at Once — Deploy to every node simultaneously
  • Health Gates — Heartbeat checks, error rate thresholds, latency limits
  • Approval Workflows — Require sign-off before rollouts execute
  • Freeze Windows — Block deployments during sensitive periods
  • Drift Detection — Automatic detection and remediation when nodes diverge

Node Management

  • Registration — Nodes self-register and receive a unique key
  • JWT Authentication — Exchange static keys for short-lived Ed25519 JWT tokens
  • Heartbeat Monitoring — Real-time health tracking with automatic staleness detection
  • Labels & Groups — Organize and target nodes by metadata
  • Version Pinning — Pin nodes to specific bundles to exclude from rollouts
  • Fleet Simulator — Built-in GenServer fleet for testing without real nodes

Security

  • WAF — ~60 OWASP CRS rules with policy system, anomaly detection, and analytics
  • SSO — OIDC (with PKCE) and SAML 2.0 with JIT provisioning and group-to-role mapping
  • TOTP MFA — Time-based one-time passwords with recovery codes
  • API Keys — Scoped keys with 9 permission categories
  • Audit Logging — Tamper-evident HMAC chain with cryptographic checkpoints

Observability

  • SLO/SLI Monitoring — Define SLOs with error budget tracking and burn rate alerts
  • Alert Rules — Threshold, anomaly, and SLO burn rate conditions with silencing
  • Prometheus Metrics — Fleet gauges, counters, and standard BEAM/Phoenix/Ecto/Oban metrics
  • OpenTelemetry — Distributed tracing across API, database, and compilation operations
  • Service Analytics — Per-service request counts, error rates, latency percentiles

Integrations

  • GitOps — Auto-compile bundles on push from GitHub, GitLab, Bitbucket, or Gitea
  • Notifications — Route events to Slack, PagerDuty, Microsoft Teams, Email, or webhooks
  • GraphQL API — Absinthe-powered with real-time subscriptions
  • Developer Portal — Auto-generated API documentation from OpenAPI specs
  • REST API — Full CRUD for all resources with scoped authentication

Quick Start

Docker Compose (recommended):

git clone https://github.com/raskell-io/sentinel-control-plane.git
cd sentinel-control-plane
docker compose up

This starts the control plane, PostgreSQL, and MinIO. Migrations run automatically. Visit localhost:4000.

Local development with hot-reloading:

mise install && mise run setup && mise run dev

Multi-Tenancy

The control plane supports multiple organizations, each with their own projects, members, and signing keys.

RolePermissions
AdminFull org control, manage members, signing keys, SSO
OperatorCreate/manage projects, bundles, rollouts, services
ReaderRead-only access to all resources

API

Nodes authenticate with registration keys or JWT tokens. Operators authenticate with scoped API keys.

Node API

POST /api/v1/projects/:slug/nodes/register    # Register
POST /api/v1/nodes/:id/heartbeat              # Heartbeat
GET  /api/v1/nodes/:id/bundles/latest          # Poll for updates

Operator API

POST /api/v1/projects/:slug/bundles            # Create bundle
POST /api/v1/projects/:slug/rollouts           # Create rollout
GET  /api/v1/projects/:slug/nodes/stats        # Fleet statistics
POST /api/v1/graphql                           # GraphQL endpoint

Full API reference and documentation available in the docs.

Tech Stack

Elixir / Phoenix 1.8LiveView for real-time UI
ObanReliable background job processing
AbsintheGraphQL with subscriptions
PostgreSQL / SQLiteProduction / development
S3 / MinIOBundle storage
Ed25519 / JOSESigning
PromEx + OpenTelemetryObservability

Get Started

Explore the source, read the docs, or join the discussion.

GitHub Repository Documentation Discussions