Supply Fluentd environment variables in systemd and containers

Fluentd can read environment variables while loading its configuration. The practical challenge is making sure the service receives the intended values and replacing the process when those values change.

Set defaults and require credentials

This configuration fragment receives local Forward traffic and sends events to an Elasticsearch output plugin installed in the Fluentd environment:

<source>
  @type forward
  bind 127.0.0.1
  port "#{ENV.fetch('FLUENT_PORT', '24224')}"
</source>

<match **>
  @type elasticsearch
  host "#{ENV.fetch('ES_HOST', 'localhost')}"
  user "#{ENV.fetch('ES_USER')}"
  password "#{ENV.fetch('ES_PASSWORD')}"
</match>

Adjust the bind address and destination TLS settings to your deployment. ENV.fetch('NAME', 'default') and ENV['NAME'] || 'default' both fall back when a variable is absent. An explicitly empty string survives both expressions. Use ENV.fetch('NAME') without a default to fail on a missing required setting.

systemd

Add a service override, using your installation's actual service name:

[Service]
Environment="ES_HOST=es.internal"
EnvironmentFile=/etc/fluentd/secrets.env

The environment file contains NAME=value assignments. Restrict access to it and keep it out of version control. After editing the unit override, run systemctl daemon-reload and restart the Fluentd service. Ordinary shell exports do not change a systemd service's environment.

Docker

An environment file avoids putting a password directly in the command line:

docker run --env-file /secure/fluentd.env your-fluentd-image:tested

Replace the image with one containing your required plugins and configuration. This is not a secret-storage guarantee: users with sufficient container-runtime access can inspect environment settings. Prefer your platform's supported secret-delivery mechanism where available, and never print the credentials during diagnosis.

Kubernetes

Populate a container variable from an existing Secret:

env:
  - name: ES_PASSWORD
    valueFrom:
      secretKeyRef:
        name: es-secret
        key: password

Set the remaining variables in the same container specification. Updating a Secret used as an environment variable does not update the environment of an already-running container; roll out replacement Pods.

Troubleshoot without exposing secrets

Run fluentd --dry-run -c fluent.conf with the same configuration and required environment as the service. Then verify connectivity with a non-sensitive sample event. Check variable presence rather than dumping values.

For an array-valued plugin setting, supply syntax that the parameter accepts, such as a JSON array or its documented comma-separated form. Interpolating a Ruby object does not bypass the plugin's type parser. The Elasticsearch plugin's hosts, for example, expects its own documented host-list syntax.

Reloading a configuration can reevaluate expressions, but it cannot import changes from another process's environment. Restart or recreate the service through the mechanism that supplies the updated values.

References: Fluentd configuration, Elasticsearch output, and Kubernetes Secrets.