Install AxoSyslog with Helm

AxoSyslog provides Helm charts for syslog-ng. You can use these charts to install cloud-ready syslog-ng images created and maintained by Axoflow.

Prerequisites

You must have Helm 3.0 or newer installed to use these charts. Refer to the official Helm documentation for details.

Syslog collector and syslog server use cases

The chart provides parameters that make it easy to deploy AxoSyslog for the following use cases:

As a collector, to collect local logs using the kubernetes() source, and forward them to another syslog server, to an opensearch() node, or to another AxoSyslog node.
As a syslog server:
- to receive RFC3164 and RFC5424 formatted syslog messages from any sender, or syslog-ng-otlp messages from another AxoSyslog node, and then
- store them locally, or forward them to remote destinations.

These two use cases are independent from each other and can be configured separately. For other use cases, for example, to use other sources and destinations, you can use the config.raw parameter of the collector or the server. For the list of configurable parameters and their default values, see Parameters of the AxoSyslog Helm chart.

Install

To install the axosyslog chart, complete the following steps.

Clone the chart repository.

helm repo add axosyslog https://axoflow.github.io/axosyslog
helm repo update

Install the chart. The default settings install two pods into the default namespace:
- A collector that act as a syslog collector, and
- a syslog server.
If need only one of these pods, you can disable it with the collector.enabled or the syslog.enabled parameter, respectively. For the list of configurable parameters and their default values, see Parameters of the AxoSyslog Helm chart. If you want to use disk-buffers, see also How to use disk-buffers in containers and Kubernetes.
- Install with the default values:
```
helm install --generate-name axosyslog/axosyslog
```
- Install only the collector:
```
helm install --generate-name axosyslog/axosyslog --set syslog.enabled=false
```
- Install only the syslog server:
```
helm install --generate-name axosyslog/axosyslog --set collector.enabled=false
```
The output should be similar to:
```
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 container start.
  $ kubectl get pods --namespace=default -l app=axosyslog-1713953907 -w
```

Check that the pods are running.

kubectl get pods

The output should list the pods that are running: two for the default settings, or one if you have disabled the collector or the syslog pod.

NAME                                   READY   STATUS    RESTARTS   AGE
axosyslog-1713953907-collector-ddftq   1/1     Running   0          57s
axosyslog-1713953907-syslog-0          1/1     Running   0          57s

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 will override the default configuration settings of the chart.
3. Update your deployment using the my-values.yaml file by running:
```
helm upgrade <name-of-your-axosyslog-deployment> axosyslog/axosyslog -f my-values.yaml
```
  The output should be similar to:
```
Release "axosyslog-1713953907" has been upgraded. Happy Helming!
...
```
  Tip: You can retrieve the non-default values of a deployment by running helm get values <name-of-your-axosyslog-deployment>

For the collector use case, configure the destination where the logs are forwarded. For example, the following values file sends the logs in JSON format to the localhost:514 address via TCP:

collector:
  config:
    destinations:
      syslog:
        enabled: true
        transport: tcp
        address: localhost
        port: 514
        template: "$(format-json .*)"

For details and other parameters, see Collector parameters.

For the syslog server use case, you can send test messages from the pods, for example:
- From the syslog server pod:
```
kubectl exec axosyslog-1714389625-syslog-0 -- loggen -S 127.0.0.1 1514
```
  Expected output:
```
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
```
The generated log messages (like 2024-05-02T10:56:31.000000+00:00 localhost prg00000[1234]: seq: 0000000065, thread: 0000, runid: 1714647391, stamp: 2024-05-02T10:56:31 PADDPADDPADDPADD) should show up in the configured destinations, for example, in the file destination:
```
kubectl exec axosyslog-1714389625-syslog-0 -- less /var/log/syslog
```

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.

Uninstall

Tip: List all installed releases using helm list.

To uninstall a chart release, run:

helm delete <name-of-the-release-to-delete>

Parameters of the AxoSyslog Helm chart

Last modified December 18, 2024: Merge pull request #90 from axoflow/minor-fixes-241218 (68cd7df)