Mastering Fluent Bit: Installing and Configuring Fluent Bit using Container Images

This series is a general purpose getting started guide for those of us wanting to learn about the Cloud Native Computing Foundation (CNCF) project Fluent Bit. 

Each article in this series addresses a single topic by providing insights into what the topic is, why we are interested in exploring that topic, where to get started with the topic, and how to get hands-on with learning about the topic as it relates to the Fluent Bit project.

The idea is that each article can stand on its own, but that they also lead down a path that slowly increases our abilities to implement solutions with Fluent Bit telemetry pipelines.

Let's take a look at the topic of this article, installing and configuring Fluent Bit using container images.

In case you missed the previous article, I'm providing a short introduction to Fluent Bit before sharing how to install and use the Fluent Bit telemetry pipeline on our own local machine with container images.

What is Fluent Bit?

Before diving into Fluent Bit, let's step back and look at the position of this project within the Fluent organization. If we look at the Fluent organization on Github, we find Fluentd and Fluent Bit project hosted there. The back story is that the project started with log parsing project Fluentd joining the CNCF in 2026 and reaching Graduated status in 2019. 

Once it became apparent that the world was heading into cloud native Kubernetes environments, the solution was not designed for the flexible and light weight requirements that Kubernetes solutions demanded. Fluent bit was born from the need to have a low resource using, high throughput, and highly scalable log management solution for cloud native Kubernetes environments. The project was started within the Fluent organization as a sub-project in 2017 and the rest is now 10 years of history with the release of v4 last week!

Fluent Bit has become so much more than a flexible and lightweight log pipeline solution, now able to process metrics and traces and becoming a telemetry pipeline collection tool of choice for those looking to put the control over their telemetry data right at the source where it's being collected.

Let's get started with Fluent Bit and see what we can do for ourselves!

Why install with container images?

The maintainers of any open source project will provide a source code project for anyone to access and build from scratch. This is often intimidating and not always straightforward, so these days you are often provided pre-built container images that you only need to pull to your local machine from a container image registry to use. 

For development, containers provide a way to test your Fluent Bit telemetry pipelines in agnostic environments that are not tied to the local machine settings before deploying them into your organization.

Where to get started

There are always requirements that need to be satisfied on your local machine before you can run any software project's container images and Fluent Bit images in this article will be using Podman container tooling. The best is to have the latest versions of this tooling installed, but at a very minimum you need to have the Podman CLI tooling. 

It is assumed you can install this on your local machine prior to reading this article. To test this you can run the following from a terminal console on your machine:

$ podman -v

podman version 5.4.1

If you prefer, you can install the Podman Desktop project and it will provide all the needed CLI tooling you see used in the rest of this article. Be aware, I won't spend any time focusing on the desktop version.

Also note that if you want to use Docker, feel free, it's pretty similar in commands and usage that you see here, but again, I will not reference that tooling in this article.

Finally, all examples in this article have been done on OSX and are assuming the reader is able to convert the actions shown here to their own local machines.

How to install and configure

The first installation of Fluent Bit with a container image can be done using the project provided image. You need only to ensure your Podman virtual machine is running. The following assumes you have already initialized your Podman machine, so you can start it as follows:

$ podman machine start

Starting machine "podman-machine-default"
WARN[0000] podman helper is installed, but was not able to claim the global 

docker sock

[SNIPPED OUTPUT]

Another process was listening on the default Docker API socket address.
You can still connect Docker API clients by setting DOCKER_HOST using the
following command in your terminal session:

export DOCKER_HOST='unix:///var/folders/6t/podman/podman-machine-default-api.sock'

Machine "podman-machine-default" started successfully

If you see something like this, then there are issues with connecting to the API socket, so Podman provides a variable to export that will work for this console session. You just need to copy that export line into your console and execute it as follows:

$ export DOCKER_HOST='unix:///var/folders/6t/podman/podman-machine-default-api.sock'

Now that you have Podman ready, you can run the default Fluent Bit image as follows:

$ podman run --rm --name fb -ti ghcr.io/fluent/fluent-bit:4.0.0

Trying to pull ghcr.io/fluent/fluent-bit:4.0.0...
Getting image source signatures
Copying blob sha256:3214acf345c0cc6bbdb56b698a41ccdefc624a09d6beb0d5de0b2303ecaf4
Copying blob sha256:bfb59b82a9b65e47d485e53b3e815bca3b3e21a095bd0cb88cac0b48062bf
Copying blob sha256:64b0d9c5f622d82dc411b0b08804023da4c4c437afcf504e1e7b9bdf8feef
Copying blob sha256:d893cdd2a6b41e0426be831dafebe1762c2380d259a2019cc12e70ee3986d
Copying config sha256:5b81ae8b810fd48abbb1115cef77dd93a3f532e3ff34f1e3466da9ceee7
Writing manifest to image destination

...

What the command is doing here includes some execution flags. The first one is a flag that automatically removes the container after we stop it just to keep our named images registry tidy (--rm). The second gives the container a name we can reference (--name fb). The third flag assigns it to a console for output and stays interactive (-ti). The last argument is the image version supported in this workshop (ghcr.io/fluent/fluent-bit:4.0.0). 

After you execute the command, we see Podman downloading the Fluent Bit 4.0.0 image into its registry. This will only happen the first time you use this version. Below the image is started after downloading is successful: 

...

Fluent Bit v4.0.0
* Copyright (C) 2015-2025 The Fluent Bit Authors
* Fluent Bit is a CNCF sub-project under the umbrella of Fluentd
* https://fluentbit.io

______ _                  _    ______ _ _             ___  _____
|  ___| |                | |   | ___ (_) |           /   ||  _  |
| |_  | |_   _  ___ _ __ | |_  | |_/ /_| |_  __   __/ /| || |/' |
|  _| | | | | |/ _ \ '_ \| __| | ___ \ | __| \ \ / / /_| ||  /| |
| |   | | |_| |  __/ | | | |_  | |_/ / | |_   \ V /\___  |\ |_/ /
\_|   |_|\__,_|\___|_| |_|\__| \____/|_|\__|   \_/     |_(_)___/


[2025/04/16 15:33:07] [ info] [fluent bit] version=4.0.0, commit=712b48d7c3, pid=1
[2025/04/16 15:33:07] [ info] [storage] ver=1.5.2, type=memory, sync=normal, checksum=off, max_chunks_up=128
[2025/04/16 15:33:07] [ info] [simd    ] disabled
[2025/04/16 15:33:07] [ info] [cmetrics] version=0.9.9
[2025/04/16 15:33:07] [ info] [ctraces ] version=0.6.2
[2025/04/16 15:33:07] [ info] [input:cpu:cpu.0] initializing
[2025/04/16 15:33:07] [ info] [input:cpu:cpu.0] storage_strategy='memory' (memory only)
[2025/04/16 15:33:07] [ info] [sp] stream processor started
[2025/04/16 15:33:07] [ info] [output:stdout:stdout.0] worker #0 started
[0] cpu.local: [[1744817588.253689543, {}], {"cpu_p"=>0.142857, "user_p"=>0.000000, "system_p"=>0.142857, "cpu0.p_cpu"=>0.000000, "cpu0.p_user"=>0.000000, "cpu0.p_system"=>0.000000, "cpu1.p_cpu"=>0.000000, "cpu1.p_user"=>0.000000, "cpu1.p_system"=>0.000000, "cpu2.p_cpu"=>0.000000, "cpu2.p_user"=>0.000000, "cpu2.p_system"=>0.000000, "cpu3.p_cpu"=>0.000000, "cpu3.p_user"=>0.000000, "cpu3.p_system"=>0.000000, "cpu4.p_cpu"=>0.000000, "cpu4.p_user"=>0.000000, "cpu4.p_system"=>0.000000, "cpu5.p_cpu"=>0.000000, "cpu5.p_user"=>0.000000, "cpu5.p_system"=>0.000000, "cpu6.p_cpu"=>0.000000, "cpu6.p_user"=>0.000000, "cpu6.p_system"=>0.000000}]

...

You can see that your Fluent Bit 4.0.0 image is running and by default, when you do not provide a configuration file, it reports CPU information as a log line to the standard output which is our console. While this is not very useful to you, it's your first time running Fluent Bit from a container image, so well done!

How to add configuration

If you were paying attention, you notice that the way you ran the container image did not allow you any insights or access to a configuration of the Fluent Bit instance. This next section will walk you through a basic Fluent Bit YAML-based configuration file and how to build container images that let you manage them with your configuration.

A basic configuration has the minimum requirements of the following sections:

service:
  flush: 1
  log_level: info

pipeline:

  inputs:
    # This entry generates a test INFO log level message.
    - name:  dummy
      dummy: '{"message":"An INFO message", "level":"INFO", "color": "yellow"}'
  
  outputs:
    # This sends all messages to the console.
    - name: stdout
      match: '*'

The basic structure has a service section to set up how Fluent Bit will function and a pipeline section with at the very least an input and output section to process telemetry data. In the above configuration file the service section uses a flush time of 1 nanosecond and logs at the level INFO. The pipeline section uses the dummy input plugin to generate the log line you define, in this case a simple message. The output plugin is a commonly used stdout, it sends all messages to the console.

To get a container image that uses your new configuration file, name it config.yaml. Create a new file called Buildfile and define how to build the Fluent Bit container image using your configuration file as follows:

FROM ghcr.io/fluent/fluent-bit:4.0.0

COPY ./config.yaml /fluent-bit/etc/config.yaml

CMD [ "fluent-bit", "-c", "/fluent-bit/etc/config.yaml"]

You can see that the build uses the base image and adds instructions on using the configuration file you provide. Build the container image as follows:

$ podman build -t fb-myimage:v1 -f Buildfile

STEP 1/3: FROM ghcr.io/fluent/fluent-bit:4.0.0
STEP 2/3: COPY ./config.yaml /fluent-bit/etc/config.yaml
--> 0169d1e2220a
STEP 3/3: CMD [ "fluent-bit", "-c", "/fluent-bit/etc/config.yaml"]
COMMIT fb-myimage:v1
--> d42a72c9dead
Successfully tagged localhost/fb-myimage:v1
d42a72c9deadc44cead0606a4e80535234ee560486c642aa31f6c081ab7d86a0

This output shows the Fluent Bit version 4.0.0 image is being used to build your image with the name fb-myimage:v1 and adding it to your local container image registry. You can test it by running the following command:

$ podman run --rm --name fb fb-myimage:v1

Fluent Bit v4.0.0
* Copyright (C) 2015-2025 The Fluent Bit Authors
* Fluent Bit is a CNCF sub-project under the umbrella of Fluentd
* https://fluentbit.io

______ _                  _    ______ _ _             ___  _____
|  ___| |                | |   | ___ (_) |           /   ||  _  |
| |_  | |_   _  ___ _ __ | |_  | |_/ /_| |_  __   __/ /| || |/' |
|  _| | | | | |/ _ \ '_ \| __| | ___ \ | __| \ \ / / /_| ||  /| |
| |   | | |_| |  __/ | | | |_  | |_/ / | |_   \ V /\___  |\ |_/ /
\_|   |_|\__,_|\___|_| |_|\__| \____/|_|\__|   \_/     |_(_)___/


[2025/04/17 15:13:28] [ info] [fluent bit] version=4.0.0, commit=712b48d7c3, pid=1
[2025/04/17 15:13:28] [ info] [storage] ver=1.5.2, type=memory, sync=normal, checksum=off, max_chunks_up=128
[2025/04/17 15:13:28] [ info] [simd    ] disabled
[2025/04/17 15:13:28] [ info] [cmetrics] version=0.9.9
[2025/04/17 15:13:28] [ info] [ctraces ] version=0.6.2
[2025/04/17 15:13:28] [ info] [input:dummy:dummy.0] initializing
[2025/04/17 15:13:28] [ info] [input:dummy:dummy.0] storage_strategy='memory' (memory only)
[2025/04/17 15:13:28] [ info] [sp] stream processor started
[2025/04/17 15:13:28] [ info] [output:stdout:stdout.0] worker #0 started
[0] dummy.0: [[1744902809.224032041, {}], {"message"=>"An INFO message", "level"=>"INFO", "color"=>"yellow"}]
[0] dummy.0: [[1744902810.224307497, {}], {"message"=>"An INFO message", "level"=>"INFO", "color"=>"yellow"}]

You have not run Fluent Bit from the standard provided container image and learned how to create, build, and run your own image with a configuration file of your choosing.

More in the series

In this article you learned how to run and configure Fluent Bit using container images, verify that it worked, and were walked through doing it step-by-step. This article is based on this online free workshop with a lab to install Fluent Bit using a container image.

There will be more in this series as you continue to learn how to configure, run, manage, and master the use of Fluent Bit in the wild. Next up, installing Fluent Bit on a Kubernetes cluster.