Skip to content

feat(config): diff-based configuration updates #127

@raffaelschneider

Description

@raffaelschneider

Summary

Support atomic, diff-based configuration updates where individual changes (add backend, remove certificate, update route) can be applied at runtime without reloading the entire configuration file.

Motivation

Full config reloads are coarse-grained. When adding a single backend to an upstream pool, reloading the entire config is wasteful and introduces unnecessary risk (a typo elsewhere in the file could break unrelated routes). Diff-based updates allow precise, auditable changes with clear feedback on what changed and when.

This also enables better integration with external control planes, orchestrators, and Zentinel's agent architecture, where changes are typically incremental rather than wholesale.

Prior Art

sozu-proxy uses this as their primary configuration model. Their ConfigState maintains a full view of the current routing state and can:

  • Accept atomic commands ("add this backend", "remove this certificate")
  • Generate diffs between two states
  • Serialize/deserialize the full state for persistence and upgrades

All runtime changes go through a Unix socket command interface as protobuf-encoded messages. File-based config is only used for initial bootstrap.

Proposed Design

  • Maintain a ConfigState that represents the current live configuration
  • Accept diff commands via a control interface (UDS or gRPC)
  • Validate each change atomically before applying
  • Emit structured events for each applied change (for audit trails and observability)
  • Persist state snapshots for crash recovery
  • KDL file config remains the bootstrap mechanism, diffs layer on top

Relationship to Existing Features

This complements rather than replaces file-based config and hot-reload. The hierarchy would be:

  1. KDL file loaded at startup (bootstrap)
  2. Diff commands applied at runtime (incremental changes)
  3. State snapshot saved periodically (crash recovery)

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:configConfiguration (sentinel-config)area:proxyCore proxy (sentinel-proxy)effort:large3+ days, architectural impactmanifesto:explicitNo hidden behaviortype:featureNew functionality request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions