docs: env: bash-style default value operator :-#2568
docs: env: bash-style default value operator :-#2568benjaminmueggenburg-serato wants to merge 1 commit intofluent:masterfrom
Conversation
📝 WalkthroughWalkthroughThis PR updates Fluent Bit documentation to clarify environment variable substitution. Two files are enhanced with explicit syntax documentation for standard variable references and default-value fallback syntax, alongside a new subsection explaining when defaults apply. ChangesEnvironment Variable Substitution Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Signed-off-by: benjaminmueggenburg-serato <benjamin.mueggenburg@serato.com>
benjaminmueggenburg-serato
force-pushed
the
master
branch
from
5be92cf to
032baeb
Compare
benjaminmueggenburg-serato
requested review from
a team and
eschabell
as code owners
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
administration/configuring-fluent-bit/classic-mode/variables.md (2)
22-26: 💤 Low valueMinor terminology clarification.
The phrase "primary variable" at line 23 could be simplified to just "the variable" for clarity. The word "primary" doesn't add meaningful distinction here since there's only one variable being evaluated.
📝 Proposed simplification
-If the `${VARIABLE:-DEFAULT}` syntax is used, Fluent Bit will use the `DEFAULT` value if the primary variable meets either of the following conditions: +If the `${VARIABLE:-DEFAULT}` syntax is used, Fluent Bit will use the `DEFAULT` value if the variable meets either of the following conditions:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@administration/configuring-fluent-bit/classic-mode/variables.md` around lines 22 - 26, Replace the phrase "primary variable" with "the variable" in the "Fallback Behavior" section describing the `${VARIABLE:-DEFAULT}` syntax so the bullet points read that Fluent Bit will use the `DEFAULT` value if the variable is not defined (unset) or is defined but set to an empty string; update the sentence containing "primary variable" under the "Fallback Behavior" heading to use "the variable" for clarity.
17-17: 💤 Low valueGrammar: Use hyphen to join compound modifier.
"Debian based system" should be "Debian-based system" when used as a compound adjective before a noun.
📝 Proposed fix
-- `/etc/default/fluent-bit` (Debian based system) +- `/etc/default/fluent-bit` (Debian-based system)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@administration/configuring-fluent-bit/classic-mode/variables.md` at line 17, The phrase "/etc/default/fluent-bit (Debian based system)" uses "Debian based" as a compound modifier; update that text to read "/etc/default/fluent-bit (Debian-based system)" so the compound adjective is hyphenated correctly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@administration/configuring-fluent-bit/yaml/environment-variables-section.md`:
- Around line 68-79: The "Default Values" section currently says defaults apply
only "if the variable is not defined"; update the text to state that the
`${VARIABLE_NAME:-DEFAULT_VALUE}` syntax supplies the DEFAULT_VALUE both when
the variable is unset and when it is defined but set to an empty string, so the
behavior matches the classic-mode doc; adjust the explanatory sentence and any
examples (the `service.flush: ${FLUSH_INTERVAL:-5}` example) to reflect this
dual-case behavior and ensure wording mirrors the classic-mode variables.md
description.
---
Nitpick comments:
In `@administration/configuring-fluent-bit/classic-mode/variables.md`:
- Around line 22-26: Replace the phrase "primary variable" with "the variable"
in the "Fallback Behavior" section describing the `${VARIABLE:-DEFAULT}` syntax
so the bullet points read that Fluent Bit will use the `DEFAULT` value if the
variable is not defined (unset) or is defined but set to an empty string; update
the sentence containing "primary variable" under the "Fallback Behavior" heading
to use "the variable" for clarity.
- Line 17: The phrase "/etc/default/fluent-bit (Debian based system)" uses
"Debian based" as a compound modifier; update that text to read
"/etc/default/fluent-bit (Debian-based system)" so the compound adjective is
hyphenated correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0131c310-bdb3-4583-bef3-ac293feb8a38
📒 Files selected for processing (2)
administration/configuring-fluent-bit/classic-mode/variables.mdadministration/configuring-fluent-bit/yaml/environment-variables-section.md
| ## Default Values | ||
|
|
||
| Fluent Bit supports setting a default value for an environment variable if the variable is not defined. This is useful for providing a fallback when an external or configuration-level variable might be missing. | ||
|
|
||
| The syntax for a default value is `${VARIABLE_NAME:-DEFAULT_VALUE}`. | ||
|
|
||
| ```yaml | ||
| service: | ||
| flush: ${FLUSH_INTERVAL:-5} | ||
| log_level: info | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for how Fluent Bit implements the :- operator to confirm behavior
rg -nP -C5 ':-' --type=c --type=cpp -g '!*test*' -g '!*example*'Repository: fluent/fluent-bit-docs
Length of output: 215
🏁 Script executed:
# First, find the file mentioned in the review
find . -name "variables.md" -type f | head -20Repository: fluent/fluent-bit-docs
Length of output: 132
🏁 Script executed:
# List files in the classic-mode directory to understand structure
find . -path "*classic-mode*" -type f | head -20Repository: fluent/fluent-bit-docs
Length of output: 543
🏁 Script executed:
# Search for environment variable documentation files
fd -e md . | grep -i variable | head -20Repository: fluent/fluent-bit-docs
Length of output: 206
🏁 Script executed:
# Read the classic-mode/variables.md file to check what it says
cat -n ./administration/configuring-fluent-bit/classic-mode/variables.md | head -50Repository: fluent/fluent-bit-docs
Length of output: 1881
🏁 Script executed:
# Also read the environment-variables-section.md file being reviewed
cat -n ./administration/configuring-fluent-bit/yaml/environment-variables-section.md | sed -n '65,85p'Repository: fluent/fluent-bit-docs
Length of output: 996
Documentation inconsistency: default value behavior incomplete in YAML section.
Line 70 states that defaults apply "if the variable is not defined," but the classic-mode documentation at administration/configuring-fluent-bit/classic-mode/variables.md (lines 22-25) explicitly specifies that defaults apply in two cases:
- The variable is not defined (unset).
- The variable is defined but set to an empty string.
Update this section to match the more complete classic-mode documentation:
Suggested fix
-Fluent Bit supports setting a default value for an environment variable if the variable is not defined. This is useful for providing a fallback when an external or configuration-level variable might be missing.
The syntax for a default value is `${VARIABLE_NAME:-DEFAULT_VALUE}`.
+
+The default value is used when:
+1. The variable is **not defined** (unset).
+2. The variable is defined but set to an **empty string**.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@administration/configuring-fluent-bit/yaml/environment-variables-section.md`
around lines 68 - 79, The "Default Values" section currently says defaults apply
only "if the variable is not defined"; update the text to state that the
`${VARIABLE_NAME:-DEFAULT_VALUE}` syntax supplies the DEFAULT_VALUE both when
the variable is unset and when it is defined but set to an empty string, so the
behavior matches the classic-mode doc; adjust the explanatory sentence and any
examples (the `service.flush: ${FLUSH_INTERVAL:-5}` example) to reflect this
dual-case behavior and ensure wording mirrors the classic-mode variables.md
description.
patrick-stephens
left a comment
patrick-stephens
left a comment
There was a problem hiding this comment.
I don't believe this is correct, the variable defaulting syntax is inherent to the shell itself rather than the config file.
| ${MY_VARIABLE} | ||
| ``` | ||
| * **Standard:** `${MY_VARIABLE}` | ||
| * **With Default Value:** `${MY_VARIABLE:-default_value}` |
There was a problem hiding this comment.
I don't think this is true, this is a bash shell syntax rather than anything with Fluent Bit itself.
Yes you can do this in bash outside of your Fluent Bit process but doing it in a Fluent Bit configuration file will not work - plus it won't work on targets like Windows either.
You could use it if you were setting them from the command line with a bash/posix shell but that's down to shell substitution.
e.g.
$ cat fluent-bit.conf
[INPUT]
name dummy
tag test
dummy { "message": "${MY_TEST_VAR:-default}" }
[OUTPUT]
name stdout
match *
$ docker run --rm -it -v $PWD/fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf:ro fluent/fluent-bit:5.0.5
...
[2026/05/08 09:16:43.720] [ warn] [env] variable ${MY_TEST_VAR:-default} is used but not set
[2026/05/08 09:16:44.720] [ warn] [env] variable ${MY_TEST_VAR:-default} is used but not set
[0] test: [[1778231803.720809223, {}], {"message"=>""}]
[0] test: [[1778231804.720746078, {}], {"message"=>""}]As you can see it's actually using the whole string as the name of the variable rather than any default expansion and you end up with an empty string because of it.
I could run it (on a compatible shell that supports this syntax) like so but this is down to the shell itself and not Fluent Bit:
$ docker run --rm -it fluent/fluent-bit:5.0.5 -i dummy -p dummy="{ \"message\": \"${MY_TEST_VAR:-default}\"}" -o stdout -m '*'
...
[2026/05/08 09:20:10.480] [ info] [output:stdout:stdout.0] worker #0 started
[0] dummy.0: [[1778232010.720772049, {}], {"message"=>"default"}]
[0] dummy.0: [[1778232011.720769028, {}], {"message"=>"default"}]There was a problem hiding this comment.
Oh my apologies, I should've linked the original PR in the description:
fluent/fluent-bit#11787
This is the PR for the updated docs if the changes were to be merged 😄
There was a problem hiding this comment.
Ah right, that makes more sense!
There was a problem hiding this comment.
Can you update the description to include the links and a bit of description?
Relying on AI for it all is not great in my experience :)
There was a problem hiding this comment.
@benjaminmueggenburg-serato same for me, see comment @patrick-stephens above.
eschabell
left a comment
eschabell
left a comment
There was a problem hiding this comment.
@benjaminmueggenburg-serato my review requires some fixes first.
| ${MY_VARIABLE} | ||
| ``` | ||
| * **Standard:** `${MY_VARIABLE}` | ||
| * **With Default Value:** `${MY_VARIABLE:-default_value}` |
There was a problem hiding this comment.
@benjaminmueggenburg-serato same for me, see comment @patrick-stephens above.
|
|
||
| These files are ignored if they don't exist. | ||
|
|
||
| ### Fallback Behavior |
There was a problem hiding this comment.
@benjaminmueggenburg-serato this means lower case for second word.
|
|
||
| ### Fallback Behavior | ||
| If the `${VARIABLE:-DEFAULT}` syntax is used, Fluent Bit will use the `DEFAULT` value if the primary variable meets either of the following conditions: | ||
| 1. The variable is **not defined** (unset). |
There was a problem hiding this comment.
@benjaminmueggenburg-serato this is vale check, adjust please?
|
|
||
| In this example, `${DB_PASSWORD}` is read from the file `/run/secrets/db_password` and refreshed every 60 seconds. `${REGION}` is set to the static value `us-east-1`. | ||
|
|
||
| ## Default Values |
There was a problem hiding this comment.
@benjaminmueggenburg-serato same on second word here with lower case.
|
|
||
| ## Default Values | ||
|
|
||
| Fluent Bit supports setting a default value for an environment variable if the variable is not defined. This is useful for providing a fallback when an external or configuration-level variable might be missing. |
There was a problem hiding this comment.
@benjaminmueggenburg-serato see the vale issue here.
| flush: ${FLUSH_INTERVAL:-5} | ||
| log_level: info | ||
| ``` | ||
|
|
There was a problem hiding this comment.
@benjaminmueggenburg-serato see the AI issue here, please address.
3 participants
Waiting on code merge: fluent/fluent-bit#11787
Updates documentation to mention the default value operator i.e
${ENV_VAR:-default}. Feature applies to both legacy config and YAML config files.Has some examples, and details the expected behaviour.
Summary by CodeRabbit