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
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 thelogging-operator
suffix). Otherwise, you’ll get a 403 Forbidden error.
Note: By default, the Logging operator Helm chart doesn’t install the
logging
resource. If you want to install it with Helm, set thelogging.enabled
value 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--pprof
(boolean, defaultfalse
): Enable performance profiling
Logging Configuration
--verbose
(boolean, defaultfalse
): Enable verbose logging--klogLevel
(integer, default0
): Global log level for klog (0-9)--output-format
(string, default""
): Logging output format (json
orconsole
)
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, defaultfalse
): Watch child resources only with logging operator’s name label (app.kubernetes.io/name: fluentd|fluentbit|syslog-ng
)--watch-labeled-secrets
(boolean, defaultfalse
): Watch secrets only withlogging.banzaicloud.io/watch: enabled
label
Note on Combinations:
- If
watch-namespace
is set, it narrows the scope for ALL watched resourceswatch-logging-name
andwatch-labeled-children
can be combined to further restrict child resource watchingwatch-labeled-children
andwatch-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, defaultfalse
): Ensure only one active controller manager--finalizer-cleanup
(boolean, defaultfalse
): Remove finalizers during operator shutdown, useful forHelm
uninstallation--enable-telemetry-controller-route
(boolean, defaultfalse
): Enable Telemetry Controller routing for Logging resources--sync-period
(string, default""
): Minimum frequency for reconciling watched resources, for example,30s
, or2h45m
. 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 nodeagents.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’ssha256: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, userefs/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"
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’ssha256: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, userefs/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"