logging-operator: Open Source Monitoring & Observability

What is logging-operator?

The Logging operator is a CNCF Sandbox Kubernetes operator that automates the deployment and configuration of a cluster logging pipeline, and it is for platform, infrastructure, and operations teams running Kubernetes who need container and application logs collected, enriched, filtered, and delivered to one or more destinations.

What it is

The Logging operator is a Kubernetes operator written in Go and licensed under Apache-2.0, living in the cloud-native ecosystem and accepted as a CNCF Sandbox project. It manages the two tiers of a logging pipeline: the log collectors, which are endpoint agents running as a Fluent Bit DaemonSet on every node to collect container and application logs from the node file system, and the log forwarders, which receive, filter, and transform incoming logs before transferring them to one or more destination outputs. Fluentd and syslog-ng are both supported as log forwarders, and logs are always transferred over authenticated and encrypted channels. The operator also manages the routing rules that specify where different log messages are sent.

The concrete problem it solves is the manual work of standing up and maintaining that pipeline. Instead of deploying and configuring the collector and forwarder tiers by hand, the operator does it from Custom Resource Definitions: the Logging resource defines the collectors and forwarders for the cluster, while Flow and ClusterFlow route selected log messages to Output and ClusterOutput destinations. Fluent Bit queries the Kubernetes API to enrich logs with pod metadata before forwarding, so the collector tier carries both logs and metadata. Because the behaviour can be described in an application's charts, teams bundle logging configuration with the application itself and let the operator handle the rest.

Key capabilities

Deploys and configures Fluent Bit as a DaemonSet collector on every node, reading container and application logs from the node file system.
Enriches collected logs with pod metadata obtained by querying the Kubernetes API.
Supports Fluentd and syslog-ng as log forwarders, with forwarder-specific flows and outputs.
Ships the same logs to multiple destinations, including S3, GCS, Elasticsearch, and Loki.
Defines infrastructure and routing through CRDs: Logging, Flow, ClusterFlow, Output, ClusterOutput, SyslogNGFlow, and SyslogNGOutput.
Supports namespace isolation and native Kubernetes label selectors for selecting which logs a flow processes.
Validates configuration, supports secure TLS communication, and allows multiple logging systems, meaning multiple Fluentd and Fluent Bit deployments on the same cluster.

Who uses it and how

Platform teams that describe logging behaviour in application charts and let the operator deploy the matching pipeline, rather than templating collector and forwarder configuration separately.
Multi-tenant clusters that rely on namespace isolation so teams define their own flows and outputs within their namespace.
Clusters that must store the same logs in more than one place, for example Elasticsearch plus an Amazon S3 bucket, using multiple output support.
Operators that publish a centralized output in the controlNamespace, which namespaced users can reference but cannot modify.
Environments large enough to justify multiple Fluentd or Fluent Bit deployments in a single cluster, where different workloads need different logging systems.

Getting started

The README excerpt does not include an install command, Helm chart, Docker image, or compose file. Deployment details are published by the project at its homepage, https://kube-logging.dev, and documentation site, kube-logging.github.io.

How it compares

The facts list no paid products that this project replaces, and name no similar tools. It stands alone in this registry on that basis, so no comparison against competing commercial logging services can be drawn from the supplied facts.

When to use it — and when not to

A self-hoster must operate the Fluent Bit DaemonSet collectors and a Fluentd or syslog-ng forwarder tier, define the flow and output custom resources, and own the destination backends and TLS material. Teams that want a fully managed logging service, or that do not want to run and size a forwarder tier inside the cluster, should not pick it. One evident limitation is portability: flows and outputs are specific to the forwarder type in use, so Fluentd and syslog-ng configurations are not interchangeable.

project readme (upstream, from github) — read inline

logging-operator logo

Logging operator

The Logging operator is now a CNCF Sandbox project.

The Logging operator solves your logging-related problems in Kubernetes environments by automating the deployment and configuration of a Kubernetes logging pipeline.

The operator deploys and configures a log collector (currently a Fluent Bit DaemonSet) on every node to collect container and application logs from the node file system.
Fluent Bit queries the Kubernetes API and enriches the logs with metadata about the pods, and transfers both the logs and the metadata to a log forwarder instance.
The log forwarder instance receives, filters, and transforms the incoming the logs, and transfers them to one or more destination outputs. The Logging operator supports Fluentd and syslog-ng as log forwarders.

Your logs are always transferred on authenticated and encrypted channels.

This operator helps you bundle logging information with your applications: you can describe the behavior of your application in its charts, the Logging operator does the rest.

What is this operator for?

This operator helps you bundle logging information with your applications: you can describe the behavior of your application in its charts, the Logging operator does the rest.

Feature highlights

Namespace isolation
Native Kubernetes label selectors
Secure communication (TLS)
Configuration validation
Multiple flow support (multiply logs for different transformations)
Multiple output support (store the same logs in multiple storage: S3, GCS, ES, Loki and more...)
Multiple logging system support (multiple fluentd, fluent-bit deployment on the same cluster)

Architecture

The Logging operator manages the log collectors and log forwarders of your logging infrastructure, and the routing rules that specify where you want to send your different log messages.

The log collectors are endpoint agents that collect the logs of your Kubernetes nodes and send them to the log forwarders. Logging operator currently uses Fluent Bit as log collector agents.

The log forwarder instance receives, filters, and transforms the incoming the logs, and transfers them to one or more destination outputs. The Logging operator supports Fluentd and syslog-ng as log forwarders. Which log forwarder is best for you depends on your logging requirements.

You can filter and process the incoming log messages using the flow custom resource of the log forwarder to route them to the appropriate output. The outputs are the destinations where you want to send your log messages, for example, Elasticsearch, or an Amazon S3 bucket. You can also define cluster-wide outputs and flows, for example, to use a centralized output that namespaced users can reference but cannot modify. Note that flows and outputs are specific to the type of log forwarder you use (Fluentd or syslog-ng).

You can configure the Logging operator using the following Custom Resource Definitions.

Logging - The Logging resource defines the logging infrastructure (the log collectors and forwarders) for your cluster that collects and transports your log messages. It also contains configurations for Fluent Bit, Fluentd, and syslog-ng.
CRDs for Fluentd:
- Output - Defines a Fluentd Output for a logging flow, where the log messages are sent using Fluentd. This is a namespaced resource. See also ClusterOutput. To configure syslog-ng outputs, see SyslogNGOutput.
- Flow - Defines a Fluentd logging flow using filters and outputs. Basically, the flow routes the selected log messages to the specified outputs. This is a namespaced resource. See also ClusterFlow. To configure syslog-ng flows, see SyslogNGFlow.
- ClusterOutput - Defines a Fluentd output that is available from all flows and clusterflows. The operator evaluates clusteroutputs in the controlNamespace only unless allowClusterResourcesFromAllNamespaces is set to true.
- ClusterFlow - Defines a Fluentd logging flow that collects logs from all namespaces by default. The operator evaluates clusterflows in the controlNamespace only unless allowClusterResourcesFromAllNamespaces is set to true. To configure syslog-ng clusterflows, see SyslogNGClusterFlow.
CRDs for syslog-ng (these resources like their Fluentd counterparts, but are tailored to features available via syslog-ng):
- SyslogNGOutput - Defines a syslog-ng Output for a logging flow, where the log messages are sent using Fluentd. This is a namespaced resource. See also SyslogNGClusterOutput. To configure Fluentd outputs, see output.
- SyslogNGFlow - Defines a syslog-ng logging flow using filters and outputs. Basically, the flow routes the selected log messages to the specified outputs. This is a namespaced resource. See also SyslogNGClusterFlow. To configure Fluentd flows, see flow.
- SyslogNGClusterOutput - Defines a syslog-ng output that is available from all flows and clusterflows. The operator evaluates clusteroutputs in the controlNamespace only unless allowClusterResourcesFromAllNamespaces is set to true.
- SyslogNGClusterFlow - Defines a syslog-ng logging flow that collects logs from all namespaces by default. The operator evaluates clusterflows in the controlNamespace only unless allowClusterResourcesFromAllNamespaces is set to true. To configure Fluentd clusterflows, see clusterflow.

See the detailed CRDs documentation.

Quickstart

Follow these quickstart guides to try out the Logging operator!

Install

Deploy Logging operator with our Helm chart.

Caution: The master branch is under heavy development. Use releases instead of the master branch to get stable software.

Support

If you encounter problems while using the Logging operator the documentation does not address, open an issue or talk to us on the #logging-operator Discord channel.

Documentation

You can find the complete documentation on the Logging operator documentation page :blue_book:

Contributing

If you find this project useful, help us:

Support the development of this project and star this repo! :star:
If you use the Logging operator in a production environment, add yourself to the list of production adopters. :metal:
Help new users with issues they may encounter :muscle:
Send a pull request with your new features and bug fixes :rocket:

Please read the Organisation's Code of Conduct!

For more information, read the developer documentation.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Frequently asked questions

Is logging-operator free to use?

logging-operator is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does logging-operator do?

Logging operator for Kubernetes

What is logging-operator written in?

logging-operator is primarily written in Go. Its source is publicly available at https://github.com/kube-logging/logging-operator, and it has 1,716 GitHub stars.