Skip to content

Conversation

@lexfrei
Copy link

@lexfrei lexfrei commented Jan 13, 2026

Summary

Add support for hot reloading configuration without restarting cloudflared. This enables updating ingress rules, warp-routing settings, and origin request configuration on the fly.

Related issues: #240, #301, #512, #965

Changes

  • Add LocalConfigWatcher component that monitors config.yaml for changes via fsnotify
  • Add SIGHUP signal handling to trigger manual configuration reload
  • Reuse existing Orchestrator.UpdateConfig() mechanism (already used for remote-managed tunnels)
  • Include 500ms debounce to handle rapid file changes from editors

Usage

# Automatic: edit config.yaml while cloudflared is running
# Changes are detected and applied within ~500ms

# Manual: send SIGHUP signal
kill -HUP $(pgrep cloudflared)

What can be hot-reloaded

Parameter Hot Reload
ingress rules
warp-routing
originRequest
tunnel UUID
credentials-file
protocol

Limitations

  • Only works for locally managed tunnels (not token-based)
  • Invalid configuration is rejected and previous config is preserved
  • Immutable parameters (tunnel UUID, credentials) require restart

Test plan

  • Unit tests for config conversion (TestConvertLocalConfigToJSON*)
  • Unit tests for validation (TestValidateLocalConfig*)
  • Unit tests for file watcher (TestLocalConfigWatcher*)
  • Unit tests for SIGHUP handling (TestSignalShutdown)
  • Manual testing with local tunnel

@lexfrei lexfrei force-pushed the feat/hot-reload-config branch 3 times, most recently from f25e7e7 to f8b2a3a Compare January 13, 2026 10:40
@lexfrei lexfrei marked this pull request as ready for review January 13, 2026 10:40
@lexfrei lexfrei force-pushed the feat/hot-reload-config branch from f8b2a3a to 2e8a997 Compare January 13, 2026 10:43
Add hot reload capability for locally-managed tunnels. When a config file
is specified (without --token), cloudflared now watches for changes and
automatically reloads the configuration.

Features:
- File watching via fsnotify with 500ms debounce
- Fallback polling every 30s for symlink rotation (Kubernetes ConfigMaps)
- Manual reload via SIGHUP signal
- Graceful handling of invalid configs (keeps current config)
- Thread-safe with TryLock to skip concurrent reloads

New files:
- orchestration/local_config.go: Config file reading and validation
- orchestration/local_watcher.go: File watcher with reload logic

Co-Authored-By: Claude <[email protected]>
Signed-off-by: Aleksei Sviridkin <[email protected]>
@lexfrei lexfrei force-pushed the feat/hot-reload-config branch from 9ff8814 to 7939127 Compare January 14, 2026 17:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant