Victoriametrics Operator

VictoriaMetrics Operator CRDs

Helm chart: oci://ghcr.io/victoriametrics/helm-charts/victoria-metrics-operator
Latest chart: 0.63.1 | API: v1beta1 (metrics), v1 (logs)

All CRDs are namespaced. Operator must be installed with crds.enabled=true keep=true to retain CRDs on chart uninstall.

CRD Reference

Metrics — Storage

Metrics — Collection

Metrics — Scrape Configuration

Alerting

Auth

Logs (API v1)

Advanced

Common Patterns

VMAgent — DaemonSet + HostNetwork (Talos)

VMAgent runs on every node, uses host networking (no CNI dependency for scraping):

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAgent
metadata:
  name: vmagent
spec:
  selectAllByDefault: true
  serviceScrapeNamespaceSelector: {}
  podScrapeNamespaceSelector: {}
  daemonSetMode: true
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet
  remoteWrite:
    - url: http://vmsingle:8428/api/v1/write
  inlineScrapeConfig: |
    - job_name: default-pods
      kubernetes_sd_configs:
        - role: pod

VMSingle — Storage with Dedup

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vmetrics
spec:
  retentionPeriod: "30d"
  storage:
    storageClassName: ceph-block
    resources:
      requests:
        storage: 50Gi
  extraArgs:
    dedup.minScrapeInterval: 30s
    memory.allowedPercent: "60"
  nodeSelector:
    kubernetes.io/hostname: worker-01

VMServiceScrape — Auto-Discover Service

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMServiceScrape
metadata:
  name: my-app
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: my-app
  endpoints:
    - port: http
      interval: 30s

VMAlert + VMRule — Alerting Pipeline

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAlert
metadata:
  name: vmalert
spec:
  datasource:
    url: http://vmsingle:8428
  notifier:
    url: http://vmalertmanager:9093
  evaluationInterval: 20s
  selectAllByDefault: true
---
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMRule
metadata:
  name: alerts
spec:
  groups:
    - name: k8s
      rules:
        - alert: InstanceDown
          expr: up == 0
          for: 1m
          labels:
            severity: critical

VLogs + VLAgent — Log Pipeline

apiVersion: operator.victoriametrics.com/v1
kind: VLSingle
metadata:
  name: vlogs
spec:
  retentionPeriod: "30d"
  storage:
    storageClassName: ceph-block
    resources:
      requests:
        storage: 30Gi
---
apiVersion: operator.victoriametrics.com/v1
kind: VLAgent
metadata:
  name: vlagent
spec:
  remoteWrite:
    - url: http://vlsingle:9428/insert/native
  k8sCollector:
    enabled: true
    includePodLabels: true

VMUser + VMAuth — Access Control

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth
spec:
  userNamespaceSelector: {}
  userSelector: {}
---
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMUser
metadata:
  name: grafana
spec:
  username: grafana
  generatePassword: true
  targetRefs:
    - crd:
        kind: VMSingle
        name: vmetrics
        namespace: monitoring
      paths:
        - "/select/.*"
        - "/vmui.*"

Quick Reference

Common Mistakes

• Scrape config not picked up — VMAgent uses selectors (serviceScrapeSelector, podScrapeSelector). If selectAllByDefault: true is not set, must match labels. Empty {} selectors match all.
• VMSingle dedup not set — Without dedup.minScrapeInterval, HA VMAgent sends duplicate data. Set on VMSingle extraArgs.
• VMServiceScrape role deprecated — endpointslices role is deprecated as of v0.67.0. Use endpointslice instead.
• VMAgent DaemonSet on Talos — Use daemonSetMode: true + hostNetwork: true. No CNI needed. Set dnsPolicy: ClusterFirstWithHostNet.
• VMAgent hostNetwork port conflict — Default VMAgent port is 8429. Explicitly set port: "8429" to avoid conflicts.
• VMAgent nodes/proxy RBAC — Scraping K8s API (/api/v1/nodes/...) needs nodes/proxy ClusterRole.
• Alertmanager configRawYaml vs configSecret — Use configRawYaml for inline config (simple). Use configSecret for complex/versioned configs.
• VLAgent image tag — Must set image.tag explicitly; operator may not default to latest. Defaults may lag.
• VMAuth user path patterns — Use regex paths ("/select/.*"), not globs. Test with target service.
• Prometheus CRD compatibility — VM Operator can convert ServiceMonitor/PodMonitor/PrometheusRule/Probe/ScrapeConfig from prometheus-operator. Set -controller.disableReconcileFor to disable unwanted converters.