Reloading Configuration
Tilegroxy supports automatic hot-loading of configuration without a restart or downtime when running as a server. Reloading must be explicitly enabled via the CLI parameter --hot-reload.
Reloading occurs automatically within a few seconds of the configuration changing on the filesystem. When reloading the configuration, the new configuration is stored side-by-side with the previous configuration and swapped atomically. The exact timing of that change cannot be controlled but should occur within several seconds of configuration being updated depending on the size of your configuration. Requests that are already in-flight while this change occurs will continue operating against the old configuration while requests coming in after the swap completes will use the new configuration.
Warnings
Configuration changes that affect the core functionality of the service (for example changing the port of the HTTP server) still require a restart of the executable.
When reloading occurs, new connections will be established for configured datastores and caches. The previous connections are closed once in-flight requests using them have had time to complete, therefore the number of connections returns to its steady state instead of growing with each reload. Expect a temporary period after each reload where both the old and new connections are open.
Buffered analytics events are flushed before the previous configuration is released so a reload doesn’t lose the current batch.
Tilegroxy uses fsnotify to detect when configuration has changed. It is possible for the file change event to reach tilegroxy before the file has finished being written. Tilegroxy waits 1 second before applying changes to avoid this but if you are using a filesystem with especially slow writes it is possible tilegroxy will attempt to read the configuration too early. This will usually result in an invalid configuration which will be ignored but could result in operating against incorrect configuration. It is therefore recommended to avoid using hot reload if you’re at risk of slow writes, especially if using YAML configurations.
Automatic configuration reloading will not work with remote providers (such as etcd) or certain file systems that do not support file notifications (such as NFS, SMB, or FUSE).