--- title: "Install AxoSyslog with Helm" url: "https://axoflow.com/docs/axosyslog-core/4.28/install/helm/" description: "Install AxoSyslog on Kubernetes with the Helm chart, as a collector, an aggregator, or both." last_modified: "2026-10-02T12:51:48+02:00" --- > For the complete documentation index, see [llms.txt](https://axoflow.com/docs/axosyslog-core/4.28/llms.txt). # Install AxoSyslog with Helm Install AxoSyslog on Kubernetes with the Helm chart, as a collector, an aggregator, or both. AxoSyslog provides a [Helm chart](https://github.com/axoflow/axosyslog/tree/main/charts/axosyslog). You can use this chart to install [cloud-ready `syslog-ng` images](https://axoflow.com/docs/axosyslog-core/4.28/install/index.md#images) created and maintained by [Axoflow](https://axoflow.com). ## Prerequisites for the Helm chart To use this chart, you need: - A Kubernetes cluster that runs Kubernetes 1.22 or newer. - [`kubectl`](https://kubernetes.io/docs/tasks/tools/), configured to access your cluster. - [Helm 3.0 or newer](https://helm.sh). For details, see the [official Helm documentation](https://helm.sh/docs/intro/install/). ## Collector and aggregator use cases The chart has parameters for the following use cases: - As a [collector](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md#collector): The collector uses the [`kubernetes()`](https://axoflow.com/docs/axosyslog-core/4.28/chapter-sources/configuring-sources-kubernetes/index.md) source to collect the local logs. It sends the logs to the aggregator, to a syslog server, to an OpenSearch node, or to a different AxoSyslog node. - As an [aggregator](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md#aggregator): The aggregator receives RFC3164 and RFC5424 syslog messages from all senders, and `axosyslog-otlp()` messages from other AxoSyslog nodes. It stores the messages locally, or sends them to remote destinations. By default, the collector sends the logs to the aggregator. You can configure and deploy the two components independently. To use other sources and destinations, use the `config.raw` parameter of the collector or the aggregator. For the list of parameters and their default values, see [Parameters of the AxoSyslog Helm chart](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md). ## Install the Helm chart To install the `axosyslog` chart, complete the following steps. 1. Add the chart repository. ```shell helm repo add axosyslog https://axoflow.github.io/axosyslog helm repo update ``` 2. Install the chart. The default settings install the following into the `default` namespace: - A `collector` DaemonSet. It collects the pod logs on each node, and sends them to the aggregator. - An `aggregator` StatefulSet. It receives syslog and `axosyslog-otlp()` messages, and writes them to a file. To install only one component, disable the other component: set `collector.enabled=false` or `aggregator.enabled=false`. For the list of parameters and their default values, see [Parameters of the AxoSyslog Helm chart](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md). If you use disk-buffers, also read [How to use disk-buffers in containers and Kubernetes](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/index.md#disk-buffer-container-kubernetes). - Install with the default values: ```shell helm install --generate-name axosyslog/axosyslog ``` - Install only the collector: ```shell helm install --generate-name axosyslog/axosyslog --set aggregator.enabled=false ``` - Install only the aggregator: ```shell helm install --generate-name axosyslog/axosyslog --set collector.enabled=false ``` The output should be similar to: ```text NAME: axosyslog-1713953907 LAST DEPLOYED: Wed Apr 24 12:18:28 2024 NAMESPACE: default STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: 1. Watch the axosyslog-1713953907 containers start. $ kubectl get pods --namespace=default -l app.kubernetes.io/instance=axosyslog-1713953907,app.kubernetes.io/name=axosyslog -w ``` The `NAME` field shows the name of the release. In the following commands, replace `` with this name. 3. Check that the pods are running. ```shell kubectl get pods ``` The output should list the pods that are running: a collector pod on every node and an aggregator pod for the default settings. For example, on a single-node cluster: ```text NAME READY STATUS RESTARTS AGE axosyslog-1713953907-collector-ddftq 1/1 Running 0 57s axosyslog-1713953907-aggregator-0 1/1 Running 0 57s ``` 4. Configure the settings of the pods for your use case. 1. Create a file called `my-values.yaml`. 2. Add the configuration needed for your use case. The settings in this file override the default configuration settings of the chart. 3. Update your deployment using the `my-values.yaml` file by running: ```shell helm upgrade axosyslog/axosyslog -f my-values.yaml ``` The output should be similar to: ```text Release "axosyslog-1713953907" has been upgraded. Happy Helming! ... ``` > **Tip:** > To list the non-default values of a release, run `helm get values `. ## Send the collector logs to another destination By default, the collector sends the logs in JSON format to the aggregator over TCP. To send the logs to a different destination, configure the destination in your values file, then run `helm upgrade`. For example, the following values file sends the logs in JSON format to the `192.0.2.10:514` address over TCP: ```yaml collector: config: destinations: syslog: enabled: true transport: tcp address: 192.0.2.10 port: 514 template: "$(format-json .*)" ``` For details and other parameters, see [Collector parameters](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md#collector). ## Send test messages to the aggregator To make sure that the aggregator receives messages, send test messages from the aggregator pod. 1. Run `loggen` in the aggregator pod: ```shell kubectl exec -aggregator-0 -- loggen -S 127.0.0.1 1514 ``` Expected output: ```text count=9328, rate = 882.83 msg/sec count=9786, rate = 884.20 msg/sec count=9800, rate = 27.92 msg/sec average rate = 928.58 msg/sec, count=9800, time=10.5538, (average) msg size=256, bandwidth=232.14 kB/sec ``` 2. Check the configured destinations for the generated messages. For example, with the default file destination: ```shell kubectl exec -aggregator-0 -- tail -n 5 /var/log/syslog ``` The generated messages look like this: ```text 2024-05-02T10:56:31.000000+00:00 localhost prg00000[1234]: seq: 0000000065, thread: 0000, runid: 1714647391, stamp: 2024-05-02T10:56:31 PADDPADDPADDPADD ``` ## How to use disk-buffers in containers and Kubernetes When you are running AxoSyslog in a container or in Kubernetes, and you want to use disk-buffers, there are some additional things to configure. - Make sure to mount the disk-buffer files and the persist file (by default, both are stored in `/var/lib/syslog-ng`) in a way they are not lost when the pod or container is restarted. - In Kubernetes, add a persistent volume to your pod and store the disk buffer files (`/var/lib/syslog-ng`) there. - In a container, mount the disk-buffer directory from the host, or store it on a local volume. - Use a reliable disk-buffer only if your storage is fast enough. For example, a low-speed persistent volume in Kubernetes can cause a significant performance degradation for AxoSyslog. - Use the latest available version of AxoSyslog, as many related improvements and performance improvements (for example, disk-buffer related metrics) are only supported in recent versions. If you are using `syslog-ng` without disk-buffering configured, `syslog-ng` stores everything in memory, which results in great performance. If you enable disk-buffering, the performance decreases. Make sure to size your observability pipeline appropriately. ## Upgrade the Helm chart To upgrade the chart to a newer version, and to roll back an upgrade, see [Upgrade the Helm chart](https://axoflow.com/docs/axosyslog-core/4.28/install/upgrade-axosyslog/index.md#helm). ## Uninstall the Helm chart > **Tip:** > To list the installed releases, run `helm list`. To uninstall a release of the chart, run: ```shell helm uninstall ``` --- [Parameters of the AxoSyslog Helm chart](https://axoflow.com/docs/axosyslog-core/4.28/install/helm/helm-chart-parameters/index.md) Configurable parameters and default values of the AxoSyslog Helm chart for the collector, aggregator, and metrics exporter. Last modified October 2, 2026: [Adds an upgrade axosyslog page (7fbe98d3)](https://github.com/axoflow/axosyslog-core-docs/commit/7fbe98d3405a8ccc30ac1cfda341edcd3b3ace77)