From 3916f7668ef0c8af556ee931062e3553eca36ca7 Mon Sep 17 00:00:00 2001 From: "Eric D. Schabell" Date: Sat, 5 Sep 2026 16:05:59 +0200 Subject: [PATCH] docs: administration: hot-reload: document relative path resolution Document how Fluent Bit resolves relative file references and the hot reload fix from fluent-bit d94fd89ce. - Add a Relative paths section listing the references this affects: parsers_file, plugins_file, upstream high availability files, and the stream processor streams_file - Describe the two-step resolution: the path as written relative to the process working directory first, then the directory holding the main configuration file - Note that absolute paths are used as provided and aren't retried - Record that Fluent Bit 5.1.3 and greater preserves the configuration directory across a hot reload, that earlier versions lost it, and that absolute paths are the workaround on those versions - Document that a failure to preserve the directory halts the reload, keeps the previous configuration running, and logs a specific message Signed-off-by: Eric D. Schabell --- administration/hot-reload.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/administration/hot-reload.md b/administration/hot-reload.md index 77caf885c..889e13af0 100644 --- a/administration/hot-reload.md +++ b/administration/hot-reload.md @@ -37,6 +37,20 @@ service: {% endtab %} {% endtabs %} +## Relative paths + +A configuration file can reference other files with a relative path, including `parsers_file`, `plugins_file`, upstream high availability files, and the stream processor `streams_file`. + +Fluent Bit resolves a relative reference in two steps. It first looks for the file at the path exactly as written, relative to the working directory of the Fluent Bit process. If no file exists there, it looks for the file in the directory that holds the main configuration file. An absolute path is used as provided and isn't retried. + +Fluent Bit version 5.1.2 and greater keeps track of the main configuration file's directory across a hot reload. In earlier versions, the reloaded configuration lost that directory, so a relative reference that resolved at startup failed to resolve after a reload. On those versions, use absolute paths for referenced files if you rely on hot reload. + +If Fluent Bit can't preserve the directory while reloading, it stops the reload, keeps the previous configuration running, and logs: + +```text +[reload] copying configuration path failed. Reloading is halted +``` + ## How to reload After updating the configuration, use one of the following methods to perform a hot reload: