# victoriametrics/helm-charts architecture

> Architecture diagram of the GitHub repository victoriametrics/helm-charts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victoriametrics/helm-charts
- Repository: https://github.com/victoriametrics/helm-charts

## Overview

#### Purpose and entry points
This repository publishes Helm charts for deploying the VictoriaMetrics observability ecosystem on Kubernetes: metrics, logs, traces, alerting, auth, collectors, MCP services, and an operator-based stack. Each `charts/<name>/Chart.yaml` is an independently installable entry point; its `values.yaml` drives rendering of Kubernetes manifests. Repository-level catalog metadata is in `artifacthub-repo.yml`.

#### Helm chart composition boundary
Charts follow the Helm model: values and chart dependencies are resolved from `Chart.yaml`/`Chart.lock`, then templates produce cluster resources. Templates commonly expose Services, ingress/route, network policies, service accounts/RBAC, monitoring CRs, autoscaling, and optional user-supplied extra objects.
Paths: `charts/victoria-metrics-single/Chart.yaml`, `charts/victoria-metrics-single/values.yaml`, `charts/victoria-metrics-single/templates/server.yaml`.

#### Metrics deployment topologies
Metrics has single-node, cluster, agent, alerting, gateway, auth, and distributed deployment charts. Cluster mode partitions the runtime into ingest (`vminsert`), query (`vmselect`), and durable storage (`vmstorage`), optionally fronted by `vmauth`; the equivalent single chart deploys one server with optional persistent storage and scrape/relabel configuration.
Paths: `charts/victoria-metrics-cluster/templates/vminsert-server.yaml`, `charts/victoria-metrics-cluster/templates/vmselect-server.yaml`, `charts/victoria-metrics-cluster/templates/vmstorage-server.yaml`; `charts/victoria-metrics-single/templates/pvc.yaml`.

#### Logs and traces pipelines
Logs and traces charts similarly offer single-node and horizontally separated cluster forms. Cluster traffic enters insert services, is stored by storage services, and is queried through select services; auth is an optional boundary. Logs additionally includes agent/collector charts and Vector configuration for collection/forwarding.
Paths: `charts/victoria-logs-cluster/templates/vlinsert-server.yaml`, `charts/victoria-logs-cluster/templates/vlstorage-server.yaml`, `charts/victoria-logs-cluster/templates/vlselect-server.yaml`; `charts/victoria-traces-cluster/templates/vtinsert-server.yaml`, `charts/victoria-logs-collector/templates/server.yaml`.

#### Operator and integrated stack
The operator chart installs the VictoriaMetrics Operator runtime, RBAC, webhook, and CRD delivery machinery. The k8s-stack chart composes operator-managed custom resources for metrics, logs, traces, alerting, auth, and Grafana integration, making the Kubernetes API/CRDs the control-plane boundary rather than directly creating every workload.
Paths: `charts/victoria-metrics-operator/templates/server.yaml`, `charts/victoria-metrics-operator/templates/webhook.yaml`, `charts/victoria-metrics-operator/charts/crds/templates/job.yaml`; `charts/victoria-metrics-k8s-stack/templates/victoria-metrics-operator/vmcluster/vmcluster.yaml`.

#### Shared and external integrations
`victoria-metrics-common` supplies reusable Helm template primitives consumed as a chart dependency. Deployment targets Kubernetes and may integrate with Grafana, Prometheus-style scraping/ServiceMonitor resources, OpenShift Routes, ingress controllers, persistent volumes, and Kubernetes autoscalers. The distributed chart adds per-availability-zone topologies and separate read/write auth proxies.
Paths: `charts/victoria-metrics-common/templates/_pod.tpl`, `charts/victoria-metrics-distributed/templates/vmauth-read.yaml`, `charts/victoria-metrics-distributed/templates/per-az/vmcluster.yaml`.

#### Release and validation flow
GitHub Actions runs linting, testing, documentation, releases, and release synchronization. Helm-template snapshot tests live within charts, while Go integration tests exercise chart behavior across the catalog. The Go sync-job is a separate runnable utility for synchronizing dashboards and rules into the stack.
Paths: `.github/workflows/release.yaml`, `test/main_test.go`, `hack/sync-job/main.go`, `charts/victoria-metrics-k8s-stack/templates/sync-job/job.yaml`.

Main entry points: [`charts/victoria-metrics-single/Chart.yaml`](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/Chart.yaml) (Independent Helm charts), [`charts/victoria-metrics-single/values.yaml`](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/values.yaml) (Chart values), [`charts/victoria-metrics-single/templates/server.yaml`](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/templates/server.yaml) (Single-node metrics), [`charts/victoria-metrics-operator/templates/server.yaml`](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/templates/server.yaml) (VictoriaMetrics Operator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Chart Catalog"]
  node_artifacthub["Artifact Hub metadata<br/>catalog metadata"]
  node_chart_entry["Independent Helm charts<br/>chart entry points<br/>[Chart.yaml]"]
  node_values["Chart values<br/>Helm values<br/>[values.yaml]"]
  node_common["Common template library<br/>Helm dependency<br/>[_pod.tpl]"]
end

subgraph group_metrics["Metrics Runtime"]
  node_single_metrics["Single-node metrics<br/>metrics server<br/>[server.yaml]"]
  node_metrics_pvc[("Metrics persistent volume<br/>persistent storage<br/>[pvc.yaml]")]
  node_vminsert["vminsert<br/>metrics ingest"]
  node_vmselect["vmselect<br/>metrics query"]
  node_vmstorage[("vmstorage<br/>metrics storage")]
  node_distributed["Distributed metrics topology<br/>multi-AZ vmcluster<br/>[vmcluster.yaml]"]
  node_read_auth["Read auth proxy<br/>vmauth<br/>[vmauth-read.yaml]"]
end

subgraph group_logs_traces["Logs &amp; Traces"]
  node_logs_collector["Logs collector<br/>collection gateway<br/>[server.yaml]"]
  node_vlinsert["vlinsert<br/>logs ingest"]
  node_vlstorage[("vlstorage<br/>logs storage")]
  node_vlselect["vlselect<br/>logs query"]
  node_vtinsert["vtinsert<br/>traces ingest"]
end

subgraph group_operator["Operator Stack"]
  node_operator_runtime["VictoriaMetrics Operator<br/>operator runtime<br/>[server.yaml]"]
  node_operator_webhook["Operator webhook<br/>admission webhook<br/>[webhook.yaml]"]
  node_crd_delivery["CRD delivery<br/>CRD install job<br/>[job.yaml]"]
  node_k8s_stack["Kubernetes stack CRs<br/>operator-managed stack<br/>[vmcluster.yaml]"]
  node_sync_job["Dashboard and rule sync job<br/>runnable utility<br/>[main.go]"]
end

subgraph group_delivery["Release &amp; Validation"]
  node_release_ci["Release automation<br/>GitHub Actions workflow<br/>[release.yaml]"]
  node_integration_tests["Catalog integration tests<br/>Go tests<br/>[main_test.go]"]
end

node_kubernetes{{"Kubernetes cluster<br/>deployment target"}}

node_artifacthub -->|"catalogs"| node_chart_entry
node_chart_entry -->|"configures"| node_values
node_chart_entry -.->|"depends on"| node_common
node_values -->|"renders"| node_single_metrics
node_single_metrics -.->|"optionally uses"| node_metrics_pvc
node_single_metrics -->|"deploys to"| node_kubernetes
node_values -->|"renders cluster mode"| node_vminsert
node_vminsert -->|"writes"| node_vmstorage
node_vmselect -->|"queries"| node_vmstorage
node_distributed -->|"fronted by"| node_read_auth
node_distributed -->|"deploys multi-AZ"| node_kubernetes
node_logs_collector -->|"forwards logs"| node_vlinsert
node_vlinsert -->|"writes"| node_vlstorage
node_vlselect -->|"queries"| node_vlstorage
node_vtinsert -->|"ingests traces in"| node_kubernetes
node_crd_delivery -->|"installs CRDs"| node_kubernetes
node_operator_runtime -->|"reconciles in"| node_kubernetes
node_operator_webhook -->|"supports"| node_operator_runtime
node_k8s_stack -->|"submits custom resources to"| node_operator_runtime
node_sync_job -->|"synchronizes dashboards and rules"| node_k8s_stack
node_release_ci -->|"runs"| node_integration_tests
node_integration_tests -.->|"validates"| node_chart_entry

click node_artifacthub "https://github.com/victoriametrics/helm-charts/blob/master/artifacthub-repo.yml"
click node_chart_entry "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/Chart.yaml"
click node_values "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/values.yaml"
click node_common "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-common/templates/_pod.tpl"
click node_single_metrics "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/templates/server.yaml"
click node_metrics_pvc "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/templates/pvc.yaml"
click node_vminsert "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vminsert-server.yaml"
click node_vmselect "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vmselect-server.yaml"
click node_vmstorage "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vmstorage-server.yaml"
click node_distributed "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-distributed/templates/per-az/vmcluster.yaml"
click node_read_auth "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-distributed/templates/vmauth-read.yaml"
click node_logs_collector "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-collector/templates/server.yaml"
click node_vlinsert "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlinsert-server.yaml"
click node_vlstorage "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlstorage-server.yaml"
click node_vlselect "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlselect-server.yaml"
click node_vtinsert "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-traces-cluster/templates/vtinsert-server.yaml"
click node_operator_runtime "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/templates/server.yaml"
click node_operator_webhook "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/templates/webhook.yaml"
click node_crd_delivery "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/charts/crds/templates/job.yaml"
click node_k8s_stack "https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-k8s-stack/templates/victoria-metrics-operator/vmcluster/vmcluster.yaml"
click node_sync_job "https://github.com/victoriametrics/helm-charts/blob/master/hack/sync-job/main.go"
click node_release_ci "https://github.com/victoriametrics/helm-charts/blob/master/.github/workflows/release.yaml"
click node_integration_tests "https://github.com/victoriametrics/helm-charts/blob/master/test/main_test.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_artifacthub,node_chart_entry,node_values,node_common toneBlue
class node_single_metrics,node_metrics_pvc,node_vminsert,node_vmselect,node_vmstorage,node_distributed,node_read_auth toneAmber
class node_logs_collector,node_vlinsert,node_vlstorage,node_vlselect,node_vtinsert toneMint
class node_operator_runtime,node_operator_webhook,node_crd_delivery,node_k8s_stack,node_sync_job toneRose
class node_release_ci,node_integration_tests toneIndigo
class node_kubernetes toneNeutral
```

## Components

### Chart Catalog

- [Artifact Hub metadata](https://github.com/victoriametrics/helm-charts/blob/master/artifacthub-repo.yml): catalog metadata · `artifacthub-repo.yml`
- [Independent Helm charts](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/Chart.yaml): chart entry points · Each chart is separately installable. · `charts/victoria-metrics-single/Chart.yaml`
- [Chart values](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/values.yaml): Helm values · Values select optional resources and runtime topology. · `charts/victoria-metrics-single/values.yaml`
- [Common template library](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-common/templates/_pod.tpl): Helm dependency · `charts/victoria-metrics-common/templates/_pod.tpl`

### Metrics Runtime

- [Single-node metrics](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/templates/server.yaml): metrics server · One server with optional storage and scrape configuration. · `charts/victoria-metrics-single/templates/server.yaml`
- [Metrics persistent volume](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-single/templates/pvc.yaml): persistent storage · `charts/victoria-metrics-single/templates/pvc.yaml`
- [vminsert](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vminsert-server.yaml): metrics ingest · `charts/victoria-metrics-cluster/templates/vminsert-server.yaml`
- [vmselect](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vmselect-server.yaml): metrics query · `charts/victoria-metrics-cluster/templates/vmselect-server.yaml`
- [vmstorage](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-cluster/templates/vmstorage-server.yaml): metrics storage · `charts/victoria-metrics-cluster/templates/vmstorage-server.yaml`
- [Distributed metrics topology](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-distributed/templates/per-az/vmcluster.yaml): multi-AZ vmcluster · Adds per-zone clusters and separate read/write auth. · `charts/victoria-metrics-distributed/templates/per-az/vmcluster.yaml`
- [Read auth proxy](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-distributed/templates/vmauth-read.yaml): vmauth · `charts/victoria-metrics-distributed/templates/vmauth-read.yaml`

### Logs & Traces

- [Logs collector](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-collector/templates/server.yaml): collection gateway · Supports collector and forwarding configuration. · `charts/victoria-logs-collector/templates/server.yaml`
- [vlinsert](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlinsert-server.yaml): logs ingest · `charts/victoria-logs-cluster/templates/vlinsert-server.yaml`
- [vlstorage](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlstorage-server.yaml): logs storage · `charts/victoria-logs-cluster/templates/vlstorage-server.yaml`
- [vlselect](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-logs-cluster/templates/vlselect-server.yaml): logs query · `charts/victoria-logs-cluster/templates/vlselect-server.yaml`
- [vtinsert](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-traces-cluster/templates/vtinsert-server.yaml): traces ingest · `charts/victoria-traces-cluster/templates/vtinsert-server.yaml`

### Operator Stack

- [VictoriaMetrics Operator](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/templates/server.yaml): operator runtime · Reconciles VictoriaMetrics custom resources. · `charts/victoria-metrics-operator/templates/server.yaml`
- [Operator webhook](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/templates/webhook.yaml): admission webhook · `charts/victoria-metrics-operator/templates/webhook.yaml`
- [CRD delivery](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-operator/charts/crds/templates/job.yaml): CRD install job · `charts/victoria-metrics-operator/charts/crds/templates/job.yaml`
- [Kubernetes stack CRs](https://github.com/victoriametrics/helm-charts/blob/master/charts/victoria-metrics-k8s-stack/templates/victoria-metrics-operator/vmcluster/vmcluster.yaml): operator-managed stack · Composes metrics, logs, traces, alerting, auth, and Grafana resources. · `charts/victoria-metrics-k8s-stack/templates/victoria-metrics-operator/vmcluster/vmcluster.yaml`
- [Dashboard and rule sync job](https://github.com/victoriametrics/helm-charts/blob/master/hack/sync-job/main.go): runnable utility · `hack/sync-job/main.go`

### Release & Validation

- [Release automation](https://github.com/victoriametrics/helm-charts/blob/master/.github/workflows/release.yaml): GitHub Actions workflow · Runs release and synchronization workflows. · `.github/workflows/release.yaml`
- [Catalog integration tests](https://github.com/victoriametrics/helm-charts/blob/master/test/main_test.go): Go tests · `test/main_test.go`

### Other components

- **Kubernetes cluster**: deployment target

## Connections

- Artifact Hub metadata → Independent Helm charts: catalogs
- Independent Helm charts → Chart values: configures
- Independent Helm charts → Common template library: depends on
- Chart values → Single-node metrics: renders
- Single-node metrics → Metrics persistent volume: optionally uses
- Single-node metrics → Kubernetes cluster: deploys to
- Chart values → vminsert: renders cluster mode
- vminsert → vmstorage: writes
- vmselect → vmstorage: queries
- Distributed metrics topology → Read auth proxy: fronted by
- Distributed metrics topology → Kubernetes cluster: deploys multi-AZ
- Logs collector → vlinsert: forwards logs
- vlinsert → vlstorage: writes
- vlselect → vlstorage: queries
- vtinsert → Kubernetes cluster: ingests traces in
- CRD delivery → Kubernetes cluster: installs CRDs
- VictoriaMetrics Operator → Kubernetes cluster: reconciles in
- Operator webhook → VictoriaMetrics Operator: supports
- Kubernetes stack CRs → VictoriaMetrics Operator: submits custom resources to
- Dashboard and rule sync job → Kubernetes stack CRs: synchronizes dashboards and rules
- Release automation → Catalog integration tests: runs
- Catalog integration tests → Independent Helm charts: validates