AWS for Fluent Bit: the container image that ships AWS output plugins

What the repository is: a build source, not a library

The project description is precise about the scope: this repository is the source of the amazon/aws-for-fluent-bit container image. The README is a document for operators and for anyone building on top of the image, and it covers the public images, the plugin set, the release process, the testing bar and the Windows variants.

The core subject is the AWS output plugin set for Fluent Bit, the plugins that push log records to AWS services. The Go module in the tree shows exactly which AWS surface is involved: `aws-sdk-go-v2` at v1.36.4 with the config module at v1.29.16, the S3 manager feature at v1.17.79, the CloudWatch Logs service at v1.50.2, the S3 service at v1.80.2, `sirupsen/logrus` at v1.9.3 for logging, and `stretchr/testify` at v1.10.0 for tests. The module is `github.com/aws/aws-for-fluent-bit` and requires Go 1.24.3.

That dependency set is the architecture in miniature. CloudWatch Logs and S3 are the destinations, the S3 manager is there for multipart uploads, and logrus is what the plugin code itself uses to report its own problems, which is the sort of detail you want in a component that runs inside someone else's logging pipeline.

The primary language of the repository is recorded as Shell, and that is accurate for the build system, which is a large set of CodeBuild build specifications and shell scripts rather than a Go library that people import.

The tag you deploy matters more than the version you read about

The README opens with a warning that failure to understand the tag scheme may cause outages in a production environment, and it is right to be blunt about it.

There are four kinds of tag in the image repositories. The `3` tag is the most recently released image version of the `3.x` major version release. The `latest` tag is the most recently released image version of the `2.x` major version release, and the README states in bold that they do not recommend deploying this to production environments ever. A version number tag such as `3.1.1` is the only tag they recommend consuming in production environments. And `stable` is a designation that some time after a version is released may be applied to it.

The `stable` tag has its own subtlety. The latest stable version is the most recent version that AWS has high confidence is stable for AWS use cases, and the recommendation is to use the stable version number in production deployments but not the stable tag itself. The reasoning is that the version number freezes, while the `stable` tag moves, so pinning the number gives you a fixed artefact even if the designation changes underneath you.

The `VERSIONS.md` file at the top of the tree holds the current version and tag information, and the repository also tracks the stable and previous stable versions in two plain files, `AWS_FOR_FLUENT_BIT_STABLE_VERSION` and `AWS_FOR_FLUENT_BIT_PREVIOUS_STABLE_VERSION`.

The 2.x and 3.x split is the other half of the story, and it is a deadline rather than a preference. The `2.x` image is based on Amazon Linux 2 and now only receives updates when the AL2 base image is updated. It will reach end of life on 2026-06-30, mirroring the upstream Amazon Linux 2 EOL date, and after that date `2.x` image updates stop if AL2 base image updates cease. The `3.x` image is based on Amazon Linux 2023 and includes long-term support through 2028.

The release testing bar, and why CVE patches skip the long tests

What makes this distribution trustworthy is not the image but the release process around it, and the README documents the bar in detail.

Three kinds of tests run. Simple integration tests are short running tests of the AWS output plugins that send log records and verify that all of them were received correctly formatted at the destination. Load tests test the AWS output plugins at various throughputs and check for log loss, with the results posted in the release notes. Long running stability tests are highly parallel tests run in Amazon ECS for the AWS output plugins using the `aws/firelens-datajet` project, simulating real Fluent Bit deployments and use cases to test for bugs that crash.

For a latest release, the bar is that the integration tests must fully pass with all log events received properly formatted, the load tests must pass the thresholds defined in `load_tests/validation_bar.py`, and the long running stability tests must show no crashes for at least one day. A CVE patch release has a lower bar, with integration and load tests but no stability tests, and the reason given is that the goal is to get the patch out as quickly as possible and because CVE patch releases never include Fluent Bit code changes, only base image dependency upgrades. There is one exception spelled out: if there is ever a CVE in the Fluent Bit code base itself, that patch would be considered a bug fix that might introduce instability and would undergo the normal latest release testing.

Promotion to `stable` adds more. A version has to have already been released as the latest release, so it has already passed that bar, and then it undergoes the long running stability tests for at least two weeks. After promotion the stability tests continue, and AWS may roll back the stable designation if issues later surface.

That last clause is the part worth internalising: `stable` is a revocable designation, not a guarantee.

How the image is actually built

The build system is where the repository's real engineering lives, and the top level shows the shape of it.

There is a `buildspec.yml` for the main build, plus a set of specialised specifications: `buildspec_integ.yml`, `buildspec_load_test.yml`, `buildspec_publish_dockerhub.yml`, `buildspec_publish_ecr.yml`, `buildspec_publish_public_ecr.yml`, `buildspec_publish_ssm.yml` and `buildspec_sync.yml`. There is a matching set of Windows specifications, including `buildspec_windows_create_manifest.yml`, `buildspec_windows_fluent-bit.yml`, `buildspec_windows_plugins.yml` and several verification specifications, which tells you the Windows container variants are built and verified as first class artefacts rather than an afterthought.

The `Makefile` shows how the version inputs are derived. Rather than hardcoding versions, the build asks a script:

BUILD_VERSION ?= 3
AL_TAG ?= $(shell ./scripts/get_linux_version.sh ${BUILD_VERSION} al-tag)
FLB_VERSION ?= $(shell ./scripts/get_linux_version.sh ${BUILD_VERSION} fluent-bit)
FLB_REPOSITORY ?= $(shell ./scripts/get_linux_version.sh ${BUILD_VERSION} flb-repository)
AWS_FOR_FLUENT_BIT_VERSION ?= $(shell ./scripts/get_linux_version.sh ${BUILD_VERSION} version)

So the base Amazon Linux tag, the Fluent Bit version to check out, the Fluent Bit repository and the image's own version all come from one lookup driven by a single build version number, and the `linux.version` and `windows.versions` files at the top level are the inputs to that lookup. That is why the two major version lines can coexist: the build version selects which set of versions applies.

The `Makefile` also pins the base image by digest. The OS digest and the OS pretty name are both obtained by running the Amazon Linux image and reading its metadata, so a rebuild resolves to the same base layer rather than to whatever the tag points at that day. The `DOCKER_BUILD_FLAGS` variable is set to `--no-cache` during development, with a comment explaining that turning the cache back on speeds up development.

The remaining top level entries describe the rest of the product: `configs/` for the image configuration, `filters/` for the plugin filters, `init/` and the `entrypoint.sh` for container start-up, `fluent-bit.conf` for the Fluent Bit configuration, `ecs/` and `ecs_windows_forward_daemon/` for the ECS task definitions, `examples/` with a `fluent-bit/` example, `use_cases/` for the guide the README links, and `troubleshooting/` for the debugging guide.

Where the image is published and how to find versions programmatically

The public images section covers the registries and the mechanisms for discovering versions, and the registries are listed individually.

There is Amazon ECR Public Gallery, Docker Hub and Amazon ECR, and each is reachable with the same image names. There is an `init` tag, which the README explains separately, and there are debug images for troubleshooting, documented under their own heading.

The programmatic discovery route is the one that matters operationally. The README describes using SSM to find available versions and AWS regions, and using SSM parameters in CloudFormation templates. That is how you avoid hardcoding a tag in a template that has to work across regions: the template reads the parameter for its region at deploy time, and the parameter is maintained by the same release process that builds the image.

The publishing specifications in the tree map directly onto this. `buildspec_publish_ssm.yml` is what fills the SSM parameters, `buildspec_publish_ecr.yml` and `buildspec_publish_public_ecr.yml` push to the two ECR variants, `buildspec_publish_dockerhub.yml` handles Docker Hub, and `buildspec_sync.yml` keeps the destinations in step.

For the plugins themselves, the README has a Plugins section and a section on using the AWS plugins outside of a container, which is the escape hatch for a team that wants the plugin behaviour without the image. The plugin source is Go, and the go.mod is what defines that surface.

Where this image is the wrong choice

The first wrong-tool case is a non-AWS destination. This image exists to ship Fluent Bit output to AWS services. If your logs go to Elasticsearch, Loki, a Kafka topic or a file, the AWS plugins are dead weight in the image and the general upstream Fluent Bit image is a better starting point.

The second case is a 2.x deployment that has not been migrated. The 2.x line reaches end of life on 2026-06-30, and after that date image updates stop if the Amazon Linux 2 base image stops being updated. Running a log shipper that no longer receives security updates in the base layer is a decision with a deadline attached, and the README is explicit that customers are encouraged to migrate to the 3.x line.

The third is a team that wants the latest version without pinning. The floating `latest` tag points at the newest 2.x release, which the README says in bold should never be deployed to production. The reason is structural: `latest` moves every time a release ships, so two identical deployments on two different days run different images.

The fourth is a Windows container user who expects the Linux image to apply. There is a separate set of Windows build specifications and a dedicated `ecs_windows_forward_daemon/` directory, and the README has its own section on running aws-for-fluent-bit Windows containers, which means the Windows path is a parallel product with its own manifest and verification steps rather than a flag.

The alternative worth naming is the upstream Fluent Bit image with the AWS plugins installed separately, and the README has a section on using the AWS plugins outside of a container. The difference in approach is that the AWS image gives you a tested combination of a pinned base layer, a pinned Fluent Bit version and the AWS SDK, tested together against the release bar described above, whereas assembling it yourself means reproducing that combination and owning the result.

Maintenance state, licensing and what the tree tells you

The last push to the default branch was on 2026-10-20, and the repository is not archived. The recent releases show two tracks running in parallel: v3.5.3 tagged on 2026-10-20, v3.5.1 on 2026-10-08, and a 2.x build v2.34.3.20261001 dated 2026-10-12, which is the 2.x maintenance line still receiving base image updates while Amazon Linux 2 lasts.

The default branch is `mainline`, not `main`, which is worth noting if you write automation against the repository, and the README links the release process document `Release_Process.md` plus a `CHANGELOG.md` at the top level.

The licence is Apache-2.0, and the tree carries the expected Apache artefacts: a `LICENSE` file, a `NOTICE` file, a `THIRD-PARTY` directory for the licences of bundled dependencies, and a `CODE_OF_CONDUCT.md`. The `CONTRIBUTING.md` file and the `CODEOWNERS` file describe how the project is worked on. The Apache-2.0 choice means that the image source can be vendored and modified, and that the plugin code in the repository carries the standard patent grant.

The practical advice for an operator is short. Pin a version number from `VERSIONS.md`, prefer the `3.x` line, keep the `stable` tag out of production configurations, and read the release notes for the load test results before you upgrade, because the numbers in there are the closest thing the project offers to a performance statement for a given build.

Editorial conclusion

Adopt the AWS for Fluent Bit image when your log pipeline is Fluent Bit and its destinations are CloudWatch Logs, S3 or FireLens, because the AWS SDK and plugin configuration are already assembled and tested together. Do not adopt it as a general Fluent Bit image for non-AWS destinations, and do not deploy the floating `latest` tag, since the README says plainly that they do not recommend deploying it to production environments ever. Before you pin a version, decide between the `2.x` line, which reaches end of life on 2026-06-30 with Amazon Linux 2, and the `3.x` line, which is based on Amazon Linux 2023 and includes long-term support through 2028.

Frequently asked questions

Official sources

1. aws/aws-for-fluent-bit on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases