VictoriaMetrics Ansible Playbooks

The vmstorage role configures the service using environment variables with the -envflag.enable flag. To map a command-line flag to an environment variable in the vmstorage_config dictionary, replace every dot (.) in the flag name with an underscore (_).

For example, to set the -storage.minFreeDiskSpaceBytes flag, use storage_minFreeDiskSpaceBytes as the key.

vmstorage_config:
  retentionPeriod: 1
  storageDataPath: "/var/lib/vmstorage"
  storage_minFreeDiskSpaceBytes: "1GB"  # corresponds to -storage.minFreeDiskSpaceBytes flag

You can pass configuration to VictoriaLogs using two methods:

1. Command-line flags: Use vlsingle_service_args. Keys are passed directly as flags.
2. Environment variables: Set vlsingle_service_envflag_enabled: "true" and provide entries in vlsingle_service_envflag_data. When using environment variables, replace dots (.) in flag names with underscores (_).

### Using service arguments (flags)
vlsingle_service_args:
  storageDataPath: "/var/lib/victoria-logs/"
  "retention.maxDiskSpaceUsageBytes": "10GB"  # passed as -retention.maxDiskSpaceUsageBytes

### Using environment variables
vlsingle_service_envflag_enabled: "true"
vlsingle_service_envflag_data:
  - "retention_maxDiskSpaceUsageBytes=10GB"  # corresponds to -retention.maxDiskSpaceUsageBytes flag

The role configures vmselect using environment variables passed via the -envflag.enable flag. To map a command-line flag to an environment variable in the vmselect_config dictionary, replace every dot (.) in the flag name with an underscore (_).

For example, the flag -search.maxUniqueTimeseries must be defined as search_maxUniqueTimeseries in your Ansible configuration.

vmselect_config:
  storageNode: "vmstorage1,vmstorage2,vmstorage3"
  search_maxUniqueTimeseries: 900000  # corresponds to -search.maxUniqueTimeseries flag

The role configures vminsert using environment variables via the -envflag.enable flag.

To map a VictoriaMetrics flag to the vminsert_config dictionary, replace every dot (.) in the flag name with an underscore (_).

Example Mapping: Flag -insert.maxQueueDuration $\rightarrow$ Key insert_maxQueueDuration in vminsert_config.

vminsert_config:
  replicationFactor: 1
  storageNode: "vmstorage1,vmstorage2,vmstorage3"
  insert_maxQueueDuration: "1m"  # corresponds to -insert.maxQueueDuration flag

To use the VictoriaMetrics Ansible roles, you must first install the victoriametrics.cluster collection from Ansible Galaxy using the ansible-galaxy CLI.

ansible-galaxy collection install victoriametrics.cluster

The repository provides specific documentation for deploying full clusters for metrics, logs, and traces. These guides cover the orchestration of multiple roles (e.g., insert, storage, select, and auth components).

- VictoriaMetrics cluster deployment: metrics cluster with vminsert, vmstorage, vmselect and vmauth
- VictoriaLogs cluster deployment: logs cluster with vlinsert, vlstorage, vlselect and vmauth
- VictoriaTraces cluster deployment: traces cluster with vtinsert, vtstorage, vtselect and vmauth

To deploy a VictoriaTraces cluster, use the playbooks/vtcluster.yml playbook. This deployment includes the VictoriaTraces cluster components and vmauth to serve as a load balancer.

All cluster components (vtstorage, vtinsert, and vtselect) utilize the same vtsingle Ansible role because they share a single binary. The specific function of each component is determined by the vtsingle_service_args variable, which passes specific flags to the binary.

ansible-playbook playbooks/vtcluster.yml -i inventory_example/vtcluster

The role supports two methods for passing configuration to vmauth:

1. Environment Variables (vmauth_config): Uses the -envflag.enable flag. When defining keys in vmauth_config, you must replace dots (.) with underscores (_). For example, a flag named http.pathPrefix must be defined as http_pathPrefix in the vmauth_config dictionary.

2. CLI Flags (vmauth_service_args): These are passed directly as command-line arguments to the binary. In this dictionary, you should use dots (.) as they appear in the actual CLI flags.

vmauth_config:
  # envflag-based config: use _ instead of .
  http_pathPrefix: "/vm"  # corresponds to -http.pathPrefix flag

vmauth_service_args:
  # CLI flags: dots work as-is
  http.pathPrefix: "/vm"  # passed directly as --http.pathPrefix

You can deploy a single-node VictoriaMetrics instance using the vmsingle role. This requires an inventory file defining your target hosts and a playbook that references the victoriametrics.cluster collection and the vmsingle role. You can customize the deployment using role variables, such as vmsingle_retention_period.

```yaml
# inventory.ini
[homelab]
  192.168.50.2

# deploy_vmsingle.yml
- name: Deploy VictoriaMetrics
  hosts: homelab
  become: true
  collections:
    - victoriametrics.cluster

  roles:
    - role: vmsingle
      vars:
        vmsingle_retention_period: "3"

To run the deployment:

ansible-playbook -i inventory.ini deploy_vmsingle.yml

After deployment, verify the installation by accessing the VMUI at http://<your-host-ip>:8428/vmui.