VictoriaMetrics: Single-Node vs Cluster Deployment

VictoriaMetrics solves the same problem as Prometheus long-term storage, but in two very different shapes: a single binary that scales vertically, and a cluster of three component types that scales horizontally. Picking wrong is expensive — the cluster version is significantly harder to operate, while the single-node version quietly handles far more than most teams assume. This guide covers the decision, the architecture, a minimal cluster you can actually start, and the HA patterns the documentation recommends.

The Decision: When Single-Node Is Enough

The documented guidance is refreshingly blunt: use the single-node version for ingestion rates below roughly one million data points per second. It scales with CPU, RAM and disk, supports HA by running two identical instances, and is much easier to configure and operate. It can also discover and scrape Prometheus targets directly, so a small deployment needs nothing but Grafana in front of it.

Reach for the cluster version when you need horizontal scale beyond one machine, multi-tenancy with independent namespaces, or per-component independent scaling.

Cluster Architecture in Three Components

The critical property is the shared-nothing design: vmstorage nodes do not talk to each other and do not share data. That is what makes scaling and maintenance simple — but it also means the cluster's availability depends on having more than one node per service, and that a load balancer such as vmauth or nginx must sit in front of the read and write paths: requests starting with /insert route to port 8480 on vminsert, and /select to port 8481 on vmselect.

A Minimal Cluster

# vmstorage
vmstorage -storageDataPath=/var/lib/vmstorage -retentionPeriod=12            -httpListenAddr=:8482

# vminsert (points at the storage node)
vminsert -storageNode=vmstorage-host:8400 -httpListenAddr=:8480

# vmselect (also points at the storage node)
vmselect -storageNode=vmstorage-host:8400 -httpListenAddr=:8481

Every component needs a distinct -httpListenAddr if you are testing several of them on one host, and vmstorage needs distinct data-path and inter-node ports. The documentation's recommendation is to run at least two nodes per service so the cluster survives a single node being unavailable during an upgrade or hardware failure.

Getting Data In: vmagent and URL Formats

vmagent is the collector: it scrapes Prometheus targets, accepts push protocols (Prometheus remote write, Influx, OpenTSDB, Graphite, OpenTelemetry) and writes to VictoriaMetrics. The remote-write URL differs by deployment type, which is the detail people get wrong when migrating:

# single-node
-remoteWrite.url=http://vm-host:8428/api/v1/write

# cluster (tenant 0, Prometheus protocol)
-remoteWrite.url=http://vminsert-host:8480/insert/0/prometheus/api/v1/write

# cluster, multitenant writes via labels
-remoteWrite.url=http://vminsert-host:8480/insert/multitenant/prometheus/api/v1/write

Scraping can be sharded across multiple vmagent instances with -promscrape.cluster.membersCount plus a distinct -promscrape.cluster.memberNum per instance, and -promscrape.cluster.replicationFactor when you want the same target scraped by several agents for resilience.

High Availability Patterns

• Single-node HA: run two identically configured instances and point Grafana at one; if it dies, switch. Simple and well understood.
• Cluster HA: at least two nodes per component, with vmauth or nginx in front. Cluster mode already supports replication, so you do not need several -remoteWrite.url flags for the same cluster.
• Multi-AZ: the documentation does not recommend stretching one cluster across availability zones — cross-AZ latency and error rates hurt. Run an independent cluster per AZ and put vmagent in front to replicate into each, with additional vmselect nodes for cross-AZ reads.

Operating Notes

1. Keep all components of one cluster in the same subnet with high bandwidth and low latency.
2. Monitor ingestion health with the standard dashboards, and treat vm_rows_invalid_total on the server side as your parsing-error alarm — streaming ingest APIs may not return parse errors to the client.
3. Watch out for inflated time-series stats in cluster mode: vmselect sums per-node stats, so replicated or rerouted samples can be double-counted. Use /api/v1/status/tsdb with that caveat in mind.
4. Size retention deliberately (-retentionPeriod) and use vmbackup/vmrestore rather than copying data directories.

相关阅读：Prometheus SNMP Exporter 监控网络设备、Grafana Loki 日志聚合与 LogQL 以及 Calico、Cilium 与 Flannel CNI 对比。

原文链接：VictoriaMetrics documentation - Cluster version