VictoriaLogs Agent #

VictoriaLogs Agent - accepts logs from various protocols and replicates them across multiple VictoriaLogs instances.

Prerequisites #

Before installing this chart, ensure your environment meets the following requirements:

Kubernetes cluster - A running Kubernetes cluster with sufficient resources
Helm - Helm package manager installed and configured

Additional requirements depend on your configuration:

Persistent storage - Required if you enable persistent volumes for data retention (enabled by default)
kubectl - Needed for cluster management and troubleshooting

For installation instructions, refer to the official documentation:

Quick start #

This Helm chart deploys the log receiver agent as a StatefulSet. It receives logs using supported protocols (for example: syslog, Elasticsearch, OpenTelemetry) from cluster workloads and forwards them to the configured VictoriaLogs destinations. If more than one destination is specified, collected logs are replicated to all configured destinations.

To quickly install single-node version of VictoriaLogs and victoria-logs-agent, see these docs .
To start with a VictoriaLogs cluster and victoria-logs-agent, see these docs .

Chart configuration #

The simplest working configuration includes specifying the remoteWrite array and setting CPU and memory resources for the chart.

Example of a minimal working configuration:

      remoteWrite:
  - url: http://victoria-logs:9428

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi
    

If multiple remoteWrite entries are defined, logs are replicated to all the specified destinations.

Basic auth #

If you need to use basic auth, define the needed flags via environment variables as shown below:

      remoteWrite:
  - url: http://victoria-logs:9428

env:
  - name: VL_remoteWrite_basicAuth_password
    valueFrom:
      secretKeyRef:
        name: auth-secret
        key: VL_PASSWORD
  - name: VL_remoteWrite_basicAuth_username
    valueFrom:
      secretKeyRef:
        name: auth-secret
        key: VL_USERNAME
    

or mount secrets into pod and reference them in remoteWrite section:

      remoteWrite:
  - url: http://victoria-logs:9428
    basicAuth.username: <name>
    basicAuth.passwordFile: /path/to/password

extraVolumes:
  - name: basic-auth-secret
    secret:
      secretName: basic-auth-secret

extraVolumeMounts:
  - name: basic-auth-secret
    mountPath: /path/to
    readOnly: true
    

Multitenancy #

To define tenant , use ProjectID and AccountID headers as shown below:

      remoteWrite:
  - url: http://localhost:9428
    headers:
      ProjectID: 12
      AccountID: 42
    

TLS #

To enable TLS verification for the remoteWrite target, you can specify the tls-prefixed flags inside each remoteWrite entry.

At a minimum, you should provide the tlsCAFile path so that the agent can verify the server’s TLS certificate. This is useful when the target endpoint uses a certificate signed by a custom or self-signed Certificate Authority (CA).

      remoteWrite:
  - url: https://victoria-logs:9428
    tlsCAFile: "/etc/tls/ca.crt"

extraVolumes:
  - name: tls-certs
    secret:
      secretName: tls-secret

extraVolumeMounts:
  - name: tls-certs
    mountPath: /etc/tls
    readOnly: true
    

If you want to disable TLS certificate verification (not recommended in production), you can set tlsInsecureSkipVerify to true.

This will skip verification of the server’s certificate and allow connecting to targets with self-signed or invalid certificates.

      remoteWrite:
  - url: https://victoria-logs:9428
    tlsInsecureSkipVerify: true
    

Ignore fields #

VictoriaLogs efficiently compresses repeated values, such as pod and node labels. However, if you prefer not to store certain fields, you can ignore them using the VL-Ignore-Fields header. For example:

      remoteWrite:
  - url: http://victoria-logs:9428
    headers:
      VL-Ignore-Fields:
        - file
        - kubernetes.container_id
        - kubernetes.pod_annotations*
        - kubernetes.node_labels*
        - kubernetes.namespace_labels*
        - kubernetes.pod_labels*
    

This allows you to exclude unnecessary or sensitive fields from being ingested. If sensitive data has already been ingested, see how to exclude logs from search result .

Extra fields #

You can add custom fields to your logs by including the VL-Extra-Fields header in headers section of remote write configuration. For example:

      remoteWrite:
  - url: http://victoria-logs:9428/
    headers:
      VL-Extra-Fields:
        zone: us-east1-c
        source: victoria-logs-agent
    

This feature lets you attach metadata to every log entry, making it easier to filter, group, or analyze logs based on these additional attributes.

How to install #

Access a Kubernetes cluster.

Setup chart repository (can be omitted for OCI repositories) #

Add a chart helm repository with follow commands:

      helm repo add vm https://victoriametrics.github.io/helm-charts/

helm repo update

List versions of vm/victoria-logs-agent chart available to installation:

      helm search repo vm/victoria-logs-agent -l

Install `victoria-logs-agent` chart #

Export default values of victoria-logs-agent chart to file values.yaml:

For HTTPS repository

      helm show values vm/victoria-logs-agent > values.yaml

For OCI repository

      helm show values oci://ghcr.io/victoriametrics/helm-charts/victoria-logs-agent > values.yaml

Change the values according to the need of the environment in values.yaml file.

Note

Consider setting .Values.nameOverride to a small value like vla to avoid hitting resource name limits of 63 characters

Test the installation with command:

For HTTPS repository

      helm install vla vm/victoria-logs-agent -f values.yaml -n NAMESPACE --debug

For OCI repository

      helm install vla oci://ghcr.io/victoriametrics/helm-charts/victoria-logs-agent -f values.yaml -n NAMESPACE --debug

Install chart with command:

For HTTPS repository

      helm install vla vm/victoria-logs-agent -f values.yaml -n NAMESPACE

For OCI repository

      helm install vla oci://ghcr.io/victoriametrics/helm-charts/victoria-logs-agent -f values.yaml -n NAMESPACE

Get the pods lists by running this commands:

      kubectl get pods -A | grep 'vla'

Get the application by running this command:

      helm list -f vla -n NAMESPACE

See the history of versions of vla application with command.

      helm history vla -n NAMESPACE

How to uninstall #

Remove application with command.

      helm uninstall vla -n NAMESPACE

Documentation of Helm Chart #

Install helm-docs following the instructions on this tutorial .

Generate docs with helm-docs command.

      cd charts/victoria-logs-agent

helm-docs

The markdown generation is entirely go template driven. The tool parses metadata from charts and generates a number of sub-templates that can be referenced in a template file (by default README.md.gotmpl). If no template file is provided, the tool has a default internal template that will generate a reasonably formatted README.

Parameters #

The following tables lists the configurable parameters of the chart and their default values.

Change the values according to the need of the environment in victoria-logs-agent/values.yaml file.

Key	Description
`affinity: {}`	`(object)` Pod affinity
`annotations: {}`	`(object)` Annotations to be added to the deployment
`env: []`	`(list)` Environment variables (ex.: secret tokens)
`extraVolumeMounts: []`	`(list)` Extra Volume Mounts for the container
`extraVolumes: []`	`(list)` Extra Volumes for the pod
`fullnameOverride: ""`	`(string)` Override resources fullname
`global.cluster.dnsDomain: cluster.local.`	`(string)` K8s cluster domain suffix, used for building storage pods’ FQDN. Details are here
`global.compatibility: openshift: adaptSecurityContext: auto`	`(object)` Openshift security context compatibility configuration
`global.image.registry: ""`	`(string)` Image registry, that can be shared across multiple helm charts
`global.imagePullSecrets: []`	`(list)` Image pull secrets, that can be shared across multiple helm charts
`image.pullPolicy: IfNotPresent`	`(string)` Image pull policy
`image.registry: ""`	`(string)` Image registry
`image.repository: victoriametrics/vlagent`	`(string)` Image repository
`image.tag: ""`	`(string)` Image tag
`image.variant: ""`	`(string)` Image tag suffix, which is appended to `Chart.AppVersion` if no `server.image.tag` is defined
`maxDiskUsagePerURL: 1GiB`	`(string)` Maximum disk usage per remoteWrite URL. When exceeded, old logs will be deleted.
`nameOverride: ""`	`(string)` Override chart name
`nodeSelector: {}`	`(object)` Pod’s node selector. Details are here
`persistentVolume.accessModes: - ReadWriteOnce`	`(list)` Array of access modes. Must match those of existing PV or dynamic provisioner. Details are here
`persistentVolume.annotations: {}`	`(object)` Persistent volume annotations
`persistentVolume.enabled: false`	`(bool)` Create/use Persistent Volume Claim for server component. Empty dir if false
`persistentVolume.existingClaim: ""`	`(string)` Existing Claim name. If defined, PVC must be created manually before volume will be bound
`persistentVolume.extraLabels: {}`	`(object)` Persistent volume additional labels
`persistentVolume.matchLabels: {}`	`(object)` Bind Persistent Volume by labels. Must match all labels of targeted PV
`persistentVolume.size: 10Gi`	`(string)` Size of the volume. Should be calculated based on the logs you send and retention policy you set
`persistentVolume.storageClassName: ""`	`(string)` StorageClass to use for persistent volume claim. Empty string means default StorageClass
`podAnnotations: {}`	`(object)` Annotations to be added to pod
`podLabels: {}`	`(object)` Extra labels for Pods only
`podSecurityContext: enabled: true`	`(object)` Security context to be added to pod
`priorityClassName: ""`	`(string)` Priority class to be assigned to the pod(s)
`remoteWrite: []`	`(list)` List of log destinations. Logs will be replicated to all listed destinations.
`resources: null`	`(string)`
`securityContext: enabled: true`	`(object)` Security context to be added to pod’s containers
`service.annotations: {}`	`(object)` Service annotations
`service.clusterIP: ""`	`(string)` Service ClusterIP
`service.enabled: false`	`(bool)` Enable agent service
`service.externalIPs: []`	`(list)` Service external IPs. Check here for details
`service.externalTrafficPolicy: ""`	`(string)` Service external traffic policy. Check here for details
`service.extraLabels: {}`	`(object)` Service labels
`service.healthCheckNodePort: ""`	`(string)` Health check node port for a service. Check here for details
`service.internalTrafficPolicy: ""`	`(string)` Service internal traffic policy. Check here for details
`service.ipFamilies: []`	`(list)` List of service IP families. Check here for details.
`service.ipFamilyPolicy: ""`	`(string)` Service IP family policy. Check here for details.
`service.loadBalancerIP: ""`	`(string)` Service load balancer IP
`service.loadBalancerSourceRanges: []`	`(list)` Load balancer source range
`service.selectorLabels: {}`	`(object)` Extra selector labels common for service only
`service.servicePort: 8429`	`(int)` Service port
`service.targetPort: http`	`(string)` Target port
`service.trafficDistribution: ""`	`(string)` Traffic Distribution. Check Traffic distribution
`service.type: ClusterIP`	`(string)` Service type
`tolerations: []`	`(list)` Node tolerations for server scheduling to nodes with taints. Details are here
`topologySpreadConstraints: null`	`(string)` Pod topologySpreadConstraints

VictoriaLogs Agent #

Prerequisites #

Quick start #

Chart configuration #

Basic auth #

Multitenancy #

TLS #

Ignore fields #

Extra fields #

How to install #

Setup chart repository (can be omitted for OCI repositories) #

Install victoria-logs-agent chart #

How to uninstall #

Documentation of Helm Chart #

Parameters #

Install `victoria-logs-agent` chart #