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. This will lead to an increase in the number of connections to the database. Connections are not explicitly killed and instead rely on idle timeouts and garbage collection to occur for them to be cleaned up. Therefore if configuration changes repeatedly occur in a short period, a large number of connections might be established. Consider relying on traditional deployment methodologies if you’re sensitive to the number of active DB connections.
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).