ansible-playbooks

Ansible roles and playbooks for Victoria Metrics.

Quick start

1. Install ansible binaries ansible-galaxy and ansible-playbook.

2. Install the collection:

   ansible-galaxy collection install victoriametrics.cluster

3. Create an inventory file inventory.ini describing your hosts. Adjust IP addresses as needed:

   [homelab]
     192.168.50.2

4. Create a playbook deploy_vmsingle.yml to deploy VictoriaMetrics single node:

   - name: Deploy VictoriaMetrics
     hosts: homelab
     become: true
     collections:
       - victoriametrics.cluster
   
     roles:
       - role: vmsingle
         vars:
           # Check available variables and their defaults here:
           # https://github.com/VictoriaMetrics/ansible-playbooks/tree/master/roles/vmsingle
           victoriametrics_retention_period_months: "3"

5. Run the playbook. Address any errors that may arise:

   ansible-playbook -i inventory.ini  deploy_vmsingle.yml

6. Check that VictoriaMetrics is running by accessing http://192.168.50.2:8428/vmui in your browser.

You can deploy other playbooks in a similar way. See Contents section for available roles.

Install collection

Roles are published to ansible galaxy: https://galaxy.ansible.com/ui/namespaces/victoriametrics/

Install collection:

ansible-galaxy collection install victoriametrics.cluster

Contents

Collection includes the following roles:

• vmsingle - installs and configures VictoriaMetrics single node
• vmagent - installs and configures vmagent
• vmalert - installs and configures vmalert
• vmselect - installs and configures vmselect
• vmstorage - installs and configures vmstorage
• vminsert - installs and configures vminsert
• vmauth - installs and configures vmauth
• vlsingle - installs and configures VictoriaLogs single node

See cluster and vmsingle playbooks for examples of how to use these roles.

Cluster deployment

Cluster deployment example is available in playbooks/cluster.yml. The playbook deploys VictoriaMetrics cluster and vmauth to act as a load balancer and authentication proxy. See inventory for example of inventory file.

Here is a diagram of the cluster deployment:

It's also possible to use molecule scenario to create a local cluster for testing. See molecule directory for details. The scenario uses docker as a driver and sets up a container for each component. The scenario can be deployed by using make molecule-converge-cluster-integration command.

Development

In order to set up development environment, you need to have docker, python and make installed. Run make init-venv to create virtual environment and install required packages for linting and testing with molecule.

The following commands are useful for development:

• make lint - runs ansible-lint on all roles and playbooks
• make molecule-converge - runs molecule converge for default scenario of all roles
• make molecule-converge-integration - runs molecule converge for integration scenario of all roles
• make molecule-destroy - destroys all molecule instances created during testing

Refer to Makefile for the full list of commands.