Install

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

Prerequisites

Logging operator requires Kubernetes v1.22.x or later.
For the Helm-based installation you need Helm v3.8.1 or later.

With the 4.3.0 release, the chart is now distributed through an OCI registry.
For instructions on how to interact with OCI registries, please take a look at Use OCI-based registries. For instructions on installing the previous 4.2.3 version, see Installation for 4.2.

Deploy Logging operator with Helm

Logos

To install the Logging operator using Helm, complete the following steps.

Note: You need Helm v3.8 or later to be able to install the chart from an OCI registry.

Install the Logging operator into the logging namespace:
```
helm upgrade --install --wait --create-namespace --namespace logging logging-operator oci://ghcr.io/kube-logging/helm-charts/logging-operator
```
Expected output:
```
Release "logging-operator" does not exist. Installing it now.
Pulled: ghcr.io/kube-logging/helm-charts/logging-operator:4.3.0
Digest: sha256:c2ece861f66a3a2cb9788e7ca39a267898bb5629dc98429daa8f88d7acf76840
NAME: logging-operator
LAST DEPLOYED: Wed Aug  9 11:02:12 2023
NAMESPACE: logging
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
Note:
- Helm has a known issue in version 3.13.0 that requires users to log in to the registry, even though the repo is public.
  Upgrade to 3.13.1 or higher to avoid having to log in, see: https://github.com/kube-logging/logging-operator/issues/1522
- If you’re installing the Helm chart from Terraform, reference the repository as repository = "oci://ghcr.io/kube-logging/helm-charts/" (without the logging-operator suffix). Otherwise, you’ll get a 403 Forbidden error.
Note: By default, the Logging operator Helm chart doesn’t install the Logging resource. To install it with Helm, set logging.enabled to true. To create a separate FluentdConfig resource, set logging.fluentdConfig.create to true.
For details on customizing the installation, see the Helm chart values.

Operator arguments

Metrics and Performance

--metrics-addr (string, default :8080): Address for metric endpoint
--health-probe-bind-address (string, default :8081): Address the health probe endpoint binds to. Serves the /healthz (liveness) and /readyz (readiness) endpoints backing the operator pod’s Kubernetes probes.
--pprof (boolean, default false): Enable performance profiling

Logging Configuration

--verbose (boolean, default false): Enable verbose logging
--klogLevel (integer, default 0): Global log level for klog (0-9)
--output-format (string, default ""): Logging output format (json or console)
-stderrthreshold (integer, default 0): Log messages at or above this severity level are written to stderr in addition to log files. Severity levels: 0=INFO, 1=WARNING, 2=ERROR, 3=FATAL

Resource Watching

--watch-namespace (string, default ""): Filter watched objects by namespace
--watch-logging-name (string, default ""): Filter objects by logging resource name
--watch-labeled-children (boolean, default false): Watch child resources only with logging operator’s name label (app.kubernetes.io/name: fluentd|fluentbit|syslog-ng)
--watch-labeled-secrets (boolean, default false): Watch secrets only with logging.banzaicloud.io/watch: enabled label

Note on Combinations:

If watch-namespace is set, it narrows the scope for ALL watched resources
watch-logging-name and watch-labeled-children can be combined to further restrict child resource watching
watch-labeled-children and watch-labeled-secrets apply independent label filters
Using multiple filters creates an increasingly restrictive watch scope
Most restrictive scenario: All three flags set will significantly limit the operator’s resource visibility

Controller Management

--enable-leader-election (boolean, default false): Ensure only one active controller manager
--finalizer-cleanup (boolean, default false): Remove finalizers during operator shutdown, useful for Helm uninstallation
--enable-telemetry-controller-route (boolean, default false): Enable Telemetry Controller routing for Logging resources
--sync-period (string, default ""): Minimum frequency for reconciling watched resources, for example, 30s, or 2h45m. Valid time units are “ms”, “s”, “m”, “h”.

To add arguments with Helm you can use the extraArgs field e.g:

helm install logging-operator ./charts/logging-operator/ --set extraArgs='{"-enable-leader-election=true","-enable-telemetry-controller-route"}'

Validate the deployment

To verify that the installation was successful, complete the following steps.

Check the status of the pods. You should see a new logging-operator pod.

kubectl -n logging get pods

Expected output:

NAME                                READY   STATUS    RESTARTS   AGE
logging-operator-5df66b87c9-wgsdf   1/1     Running   0          21s

Check the CRDs. You should see the following five new CRDs.

kubectl get crd

Expected output:

NAME                                    CREATED AT
clusterflows.logging.banzaicloud.io              2023-08-10T12:05:04Z
clusteroutputs.logging.banzaicloud.io            2023-08-10T12:05:04Z
eventtailers.logging-extensions.banzaicloud.io   2023-08-10T12:05:04Z
flows.logging.banzaicloud.io                     2023-08-10T12:05:04Z
fluentbitagents.logging.banzaicloud.io           2023-08-10T12:05:04Z
hosttailers.logging-extensions.banzaicloud.io    2023-08-10T12:05:04Z
loggings.logging.banzaicloud.io                  2023-08-10T12:05:05Z
outputs.logging.banzaicloud.io                   2023-08-10T12:05:05Z
syslogngclusterflows.logging.banzaicloud.io      2023-08-10T12:05:05Z
syslogngclusteroutputs.logging.banzaicloud.io    2023-08-10T12:05:05Z
syslogngflows.logging.banzaicloud.io             2023-08-10T12:05:05Z
syslogngoutputs.logging.banzaicloud.io           2023-08-10T12:05:06Z

Image and chart verification

Images and charts are signed with GitHub Actions OIDC token. We sign the digests of the images and the charts to ensure the integrity and authenticity of the artifacts.

To verify signatures, you must have cosign installed.

Image verification

You can verify our images by running the following command.

cosign verify "ghcr.io/kube-logging/logging-operator@{sha256-IMAGE-DIGEST}" \ 
--certificate-identity "https://github.com/ghcr.io/kube-logging/logging-operator/.github/workflows/artifacts.yaml@{refs/heads/main || refs/tags/<tag_name>}" \ 
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Replace {sha256-IMAGE-DIGEST} with the digest of the image you want to verify. You can find the digests at ghcr.io/kube-logging/logging-operator. For example, for the 4.11.0 release it’s sha256:50550883905ffe484f210ae65a8e0dbcbc0836c240b1fec454945d8b97830ede.
Replace {refs/heads/main || refs/tags/<tag_name>} with the reference to the image you want to verify. For example, for the 4.11.0 release, use refs/tags/4.11.0.

For example:

cosign verify "ghcr.io/kube-logging/logging-operator@sha256:50550883905ffe484f210ae65a8e0dbcbc0836c240b1fec454945d8b97830ede" \
    --certificate-identity "https://github.com/kube-logging/logging-operator/.github/workflows/artifacts.yaml@refs/tags/4.11.0" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Pin the operator image by digest

The logging-operator Helm chart accepts an optional image.digest value that pins the operator image to a specific digest instead of a tag. It is unset by default. Omitting it keeps the chart’s standard tag-based behavior, so upgrades remain backward compatible.

Pinning by digest is useful in two cases:

To pin a digest you just verified in the image verification step above, as an extra safeguard.
To run a specific pre-release or master image by digest. For the tag-based alternative, see How can I run the unreleased master version. That approach uses --set image.tag=master.

The value must include the full sha256: prefix. When set, the chart renders the operator image in digest form as <repository>@<digest>, for example ghcr.io/kube-logging/logging-operator@sha256:.... To set it, add --set image.digest=<digest> to the OCI install command.

For example, using the 4.11.0 image digest (substitute the digest you verified):

helm upgrade --install --wait --create-namespace --namespace logging logging-operator oci://ghcr.io/kube-logging/helm-charts/logging-operator \
    --set image.digest=sha256:50550883905ffe484f210ae65a8e0dbcbc0836c240b1fec454945d8b97830ede

Note: When image.digest is set, it overrides both image.tag and the chart’s appVersion. Setting a tag alongside it has no effect because the digest wins.

Chart verification

You can verify our charts by running the following command.

cosign verify "ghcr.io/kube-logging/logging-operator@{sha256-CHART-DIGEST}" \ 
--certificate-identity "https://github.com/ghcr.io/kube-logging/logging-operator/.github/workflows/artifacts.yaml@{refs/heads/main || refs/tags/<tag_name>}" \ 
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Replace {sha256-CHART-DIGEST} with the digest of the image you want to verify. You can find the digests at ghcr.io/kube-logging/helm-charts/logging-operator. For example, for the 4.11.0 release it’s sha256:233407195e1c97382e7fc0dfb00f9c6cadbba2928a64bfce6be072fc37df20eb.
Replace {refs/heads/main || refs/tags/<tag_name>} with the reference to the image you want to verify. For example, for the 4.11.0 release, use refs/tags/4.11.0.

For example:

cosign verify "ghcr.io/kube-logging/helm-charts/logging-operator@sha256:233407195e1c97382e7fc0dfb00f9c6cadbba2928a64bfce6be072fc37df20eb" \
    --certificate-identity "https://github.com/kube-logging/logging-operator/.github/workflows/artifacts.yaml@refs/tags/4.11.0" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Last modified September 17, 2026: Merge pull request #349 from Promptless/promptless/document-manager-health-probe-flag (8018ff1)