在 Kubernetes 上使用 Helm 部署单节点 VictoriaMetrics：集群指标采集与 Grafana 可视化实战-二趣网

在 Kubernetes 上使用 Helm 部署单节点 VictoriaMetrics：集群指标采集与 Grafana 可视化实战

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

本指南以当前仓库中的官方文档 docs/guides/k8s-monitoring-via-vm-single/README.md 为骨架，完整演示如何在 Kubernetes 集群上通过 Helm 部署单节点（single-node）版 VictoriaMetrics，利用其内置的 Pull 模式指标抓取与 Kubernetes 服务发现（service discovery）能力自动采集集群中所有 Node、Pod 与 API Server 的指标，并接入 Grafana 实现集群资源的可视化监控。读完本文，你将掌握：Helm 安装 VictoriaMetrics 单节点实例、配置 Kubernetes 指标自动发现、通过metric_relabel_configs规整标签，以及用 Helm 安装 Grafana 并加载现成仪表盘的全流程，同时理解其底层实现原理。

VictoriaMetrics 单节点部署在 Kubernetes 集群内，通过服务发现抓取集群组件指标并交由 Grafana 展示

1. 前置条件与整体思路

本指南的运行环境以文档编写时的版本为准，包括：

Kubernetes 集群 1.34（文档示例使用 GKE，同样适用于 Amazon EKS 或自建集群）
Helm 4.1.0+
kubectl 1.34.3

整体部署流程分为三步：先通过 Helm 安装 VictoriaMetrics 单节点（默认命名空间default），使其既能接收指标写入，又能主动抓取 Kubernetes 组件指标；再安装 Grafana 并将 VictoriaMetrics 配置为默认数据源；最后打开 Grafana 仪表盘查看集群运行状态。

建议：将本指南中使用的所有配置文件（如guide-vmsingle-values.yaml、grafana-single-values.yml）纳入版本控制，便于日后参考或调整部署配置。

2. 添加 VictoriaMetrics Helm 仓库

首先把 VictoriaMetrics 官方 Helm 仓库加入本地索引并更新：

helm repo add vm https://victoriametrics.github.io/helm-charts/ helm repo update

验证仓库是否配置成功：

helm search repo vm/

输出会列出仓库中可用的 chart，类似如下（版本号以实际拉取到的为准）：

NAME CHART VERSION APP VERSION DESCRIPTION vm/victoria-metrics-single 0.29.0 v1.134.0 VictoriaMetrics Single version - high-performan... vm/victoria-metrics-agent 0.30.0 v1.134.0 VictoriaMetrics Agent - collects metrics from v... vm/victoria-metrics-alert 0.30.0 v1.134.0 VictoriaMetrics Alert - executes a list of give... vm/victoria-metrics-anomaly 1.12.9 v1.28.2 VictoriaMetrics Anomaly Detection - a service t... ...(list continues)...

其中vm/victoria-metrics-single即本文要使用的单节点版本 chart。

3. 安装 VictoriaMetrics 单节点并启用指标自动抓取

3.1 获取官方示例 values 文件

本指南配套的示例配置文件保存在仓库的 docs/guides/examples/guide-vmsingle-values.yaml，可以直接获取：

wget https://docs.victoriametrics.com/guides/examples/guide-vmsingle-values.yaml

执行安装：

helm install vmsingle vm/victoria-metrics-single -f guide-vmsingle-values.yaml

3.2 核心配置解析：`scrape`与 Kubernetes 服务发现

guide-vmsingle-values.yaml中最关键的配置是server.scrape.enabled: true，它开启了 VictoriaMetrics 单节点内置的指标抓取能力——这意味着你不需要额外部署 vmagent 或 Prometheus，单节点版本身就内置了 Prometheus 兼容的抓取器：

server: scrape: enabled: true

这与仓库源码的实现是一致的：VictoriaMetrics 单节点二进制（app/victoria-metrics/main.go）引入了lib/promscrape包，内置完整的抓取与发现能力；其-promscrape.config命令行参数即指向 Prometheus 兼容的抓取配置文件。从 lib/promscrape/config.go 的源码可以看到，配置解析默认开启-promscrape.config.strictParse=true（拒绝未知字段），并支持通过-promscrape.config.dryRun在不启动服务的情况下预检配置文件。

该 values 文件中的完整抓取配置由三部分构成，它们被注入到单节点的-promscrape.config中：

victoriametrics：静态抓取本机localhost:8428的自身指标（即victoriametrics自身的job），用于监控数据库自身的摄入与资源情况；
kubernetes-apiservers：通过kubernetes_sd_configs以role: endpoints发现 API Server 的 metrics 端点，使用 serviceaccount 的 CA 与 token 进行 HTTPS 鉴权，并用relabel_configs的keep动作只保留default;kubernetes;https这一个目标；
kubernetes-nodes与kubernetes-nodes-cadvisor：以role: node发现集群所有 Node，抓取 kubelet 的/metrics（节点自身指标）与/metrics/cadvisor（容器运行时指标）。前者通过labelmap将__meta_kubernetes_node_label_*转成节点标签；后者额外记录了metrics_path标签。

其中全局抓取间隔为scrape_interval: 15s：

server: scrape: enabled: true config: global: scrape_interval: 15s scrape_configs: - job_name: victoriametrics static_configs: - targets: [ "localhost:8428" ] - job_name: "kubernetes-apiservers" kubernetes_sd_configs: - role: endpoints scheme: https tls_config: ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt insecure_skip_verify: true bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token relabel_configs: - source_labels: [ __meta_kubernetes_namespace, __meta_kubernetes_service_name, __meta_kubernetes_endpoint_port_name ] action: keep regex: default;kubernetes;https - job_name: "kubernetes-nodes" scheme: https tls_config: ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt insecure_skip_verify: true bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token kubernetes_sd_configs: - role: node relabel_configs: - action: labelmap regex: __meta_kubernetes_node_label_(.+) - job_name: "kubernetes-nodes-cadvisor" scheme: https tls_config: ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt insecure_skip_verify: true bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token kubernetes_sd_configs: - role: node metrics_path: /metrics/cadvisor relabel_configs: - action: labelmap regex: __meta_kubernetes_node_label_(.+) - source_labels: [__metrics_path__] target_label: metrics_path

从源码结构看，VictoriaMetrics 的 Kubernetes 服务发现实现位于 lib/promscrape/discovery/kubernetes，支持endpoints、endpointslice、ingress、node、pod、service、namespace等多种role，配合 kubeconfig（kubeconfig.go）和 API Watcher（api_watcher.go）实现目标动态更新。

3.3 用`metric_relabel_configs`规整标签

cadvisor 采集的指标标签无法直接满足后续 Grafana 仪表盘的展示需求，因此 values 中通过metric_relabel_configs（指标级重新打标）将pod、container等标签归一化：

... metric_relabel_configs: - action: replace source_labels: [pod] regex: '(.+)' target_label: pod_name replacement: '${1}' - action: replace source_labels: [container] regex: '(.+)' target_label: container_name replacement: '${1}' - action: replace target_label: name replacement: k8s_stub - action: replace source_labels: [id] regex: '^/system\.slice/(.+)\.service$' target_label: systemd_service_name replacement: '${1}'

四条规则分别完成：把pod标签复制为pod_name、把container标签复制为container_name、为所有样本补充固定的name="k8s_stub"标签、以及从 systemd 的id形如/system.slice/xxx.service中提取服务名到systemd_service_name。这样 Grafana 仪表盘在查询pod_name、container_name等标签时就能正确渲染。如果抓取后的标签行为不符合预期，还可以通过单节点的/metric-relabel-debug端点调试重打标结果（参见 app/victoria-metrics/main.go 中暴露的调试端点列表）。

3.4 安装输出解读

执行helm install vmsingle vm/victoria-metrics-single后，终端会输出类似如下的信息：

NAME: vmsingle LAST DEPLOYED: Wed Jan 28 13:04:36 2026 NAMESPACE: default STATUS: deployed REVISION: 1 DESCRIPTION: Install complete TEST SUITE: None NOTES: The VictoriaMetrics write api can be accessed via port 8428 on the following DNS name from within your cluster: vmsingle-victoria-metrics-single-server.default.svc.cluster.local. Metrics Ingestion: Get the Victoria Metrics service URL by running these commands in the same shell: export POD_NAME=$(kubectl get pods --namespace default -l "app=" -o jsonpath="{.items[0].metadata.name}") kubectl --namespace default port-forward $POD_NAME 8428 Write the URL inside the Kubernetes cluster: http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428/<protocol-specific-write-endpoint> E.g, for Prometheus: http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428/api/v1/write Metrics Scrape: Pull-based scrapes are enabled Scrape config can be displayed by running this command:: kubectl get cm vmsingle-victoria-metrics-single-server-scrapeconfig -n default The target’s information is accessible via api: Inside cluster: http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428/targets Outside cluster: You need to port-forward the service (see instructions above) and call http://<service-host-port>/targets Read Data: The following URL can be used as the datasource URL in Grafana:: http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428

输出中的几个关键信息值得注意：

写入端点：/api/v1/write是 Prometheus remote write 兼容的写入路径，/targets页面用于查看当前发现并抓取的所有目标及其健康状态（其实现位于 lib/promscrape/targetstatus.go），/metrics暴露数据库自身指标，vmui为内置 Web UI；
默认端口：单节点默认监听8428端口，这与源码中 app/victoria-metrics/main.go 的默认监听地址:8428一致；
Grafana 数据源 URL：输出末尾的http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428就是下一步配置 Grafana 数据源时使用的地址，请记下它。

验证 Pod 状态：

kubectl get pods

等待STATUS变为Running，预期输出：

NAME READY STATUS RESTARTS AGE vmsingle-victoria-metrics-single-server-0 1/1 Running 0 68s

4. 安装 Grafana 并接入 VictoriaMetrics 数据源

4.1 添加 Grafana Helm 仓库并准备 values 文件

helm repo add grafana-community https://grafana-community.github.io/helm-charts helm repo update

创建 Grafana 配置。请确保url与上一步安装输出中的 Grafana 数据源 URL 保持一致：

cat <<EOF > grafana-single-values.yml datasources: datasources.yaml: apiVersion: 1 datasources: - name: victoriametrics type: prometheus orgId: 1 # use the URL obtained from the VictoriaMetrics helm install output url: http://vmsingle-victoria-metrics-single-server.default.svc.cluster.local.:8428 access: proxy isDefault: true updateIntervalSeconds: 10 editable: true dashboardProviders: dashboardproviders.yaml: apiVersion: 1 providers: - name: 'default' orgId: 1 folder: '' type: file disableDeletion: true editable: true options: path: /var/lib/grafana/dashboards/default dashboards: default: victoriametrics: gnetId: 10229 datasource: victoriametrics kubernetes: gnetId: 14205 datasource: victoriametrics EOF

该文件完成了三件事：

注册数据源：datasources中声明一个type: prometheus、名为victoriametrics的数据源，指向单节点服务的集群内 DNS 地址，并设为默认数据源（isDefault: true）；
声明仪表盘目录：dashboardProviders让 Grafana 从/var/lib/grafana/dashboards/default目录加载仪表盘 JSON；
预装两个仪表盘：gnetId: 10229为 VictoriaMetrics 单节点自身的遥测仪表盘，gnetId: 14205为 Kubernetes 集群监控仪表盘（Kubernetes Cluster Monitoring via Prometheus），两者都以victoriametrics为数据源。作为参考，当前仓库的 dashboards 目录中也维护了victoriametrics.json、victoriametrics-cluster.json、vmagent.json等官方仪表盘定义，可供自行导入。

4.2 安装 Grafana

helm install my-grafana grafana-community/grafana -f grafana-single-values.yml

安装成功后会输出类似信息：

NAME: my-grafana LAST DEPLOYED: Wed Jan 28 13:12:51 2026 NAMESPACE: default STATUS: deployed REVISION: 1 DESCRIPTION: Install complete NOTES: 1. Get your 'admin' user password by running: kubectl get secret --namespace default my-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo 2. The Grafana server can be accessed via port 80 on the following DNS name from within your cluster: my-grafana.default.svc.cluster.local Get the Grafana URL to visit by running these commands in the same shell: export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=my-grafana" -o jsonpath="{.items[0].metadata.name}") kubectl --namespace default port-forward $POD_NAME 3000 3. Login with the password from step 1 and the username: admin ################################################################################# ###### WARNING: Persistence is disabled!!! You will lose your data when ##### ###### the Grafana pod is terminated. ##### #################################################################################

注意输出末尾的警告：当前部署没有启用持久化存储，Grafana Pod 被终止后其数据会丢失。生产环境建议按官方 Helm 文档启用持久化存储（Persistent Volume），并可按需为 Grafana 配置私有 CA 证书。

获取 Grafanaadmin用户密码：

kubectl get secret --namespace default my-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

等待 Grafana Pod 进入Running状态：

NAME READY STATUS RESTARTS AGE my-grafana-bc7796cf5-ffmln 1/1 Running 0 8m40s

将 Grafana 服务转发到本地3000端口：

export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=my-grafana" -o jsonpath="{.items[0].metadata.name}") kubectl --namespace default port-forward $POD_NAME 3000

现在浏览器访问http://127.0.0.1:3000即可打开 Grafana。

5. 查看仪表盘与验证采集效果

使用用户名admin和上一步获取的密码登录 Grafana，打开http://127.0.0.1:3000/dashboards，选择Kubernetes Cluster Monitoring (via Prometheus)仪表盘：

Grafana 中预装的 VictoriaMetrics 与 Kubernetes 仪表盘

可以看到集群节点的 CPU、内存、网络等核心指标：

Kubernetes 集群监控仪表盘，数据由单节点 VictoriaMetrics 抓取并提供

VictoriaMetrics - single-node仪表盘（gnetId 10229）则展示数据库自身的遥测指标（如摄入速率、查询负载、资源占用），用于确认采集链路本身处于健康状态。

这些指标之所以能在仪表盘中正确渲染，正是得益于第 3 节中metric_relabel_configs对标签的归一化处理——仪表盘依赖pod_name、container_name、systemd_service_name等标签进行分组与过滤。若仪表盘出现空面板，可回到 VictoriaMetrics 的/targets页面检查各 job 的抓取状态，或使用/metric-relabel-debug端点排查重打标规则。

6. 小结与后续扩展

完成上述步骤后，你的集群中现在拥有一套完整的指标监控闭环：

单节点 VictoriaMetrics 作为时序数据库，持续抓取并存储 Kubernetes 集群中所有 Node、Pod、容器（cadvisor）以及 API Server 的指标；
无需额外部署 Prometheus 或 vmagent，抓取、服务发现、存储均由单节点实例一体完成（源码上由 lib/promscrape 提供抓取与发现，app/victoria-metrics/main.go 负责组装与启动）；
Grafana 通过内置数据源直接查询这些指标，并以仪表盘形式呈现集群资源使用情况。

可以基于这套基础继续扩展：

深入了解单节点版的全部能力，参见 docs/victoriametrics/Single-server-VictoriaMetrics.md；
使用 vmctl 将已有 Prometheus/InfluxDB/OpenTSDB 等历史指标迁移进 VictoriaMetrics；
参考 vmalert 与 Grafana 告警配置指南为集群指标配置告警规则；
若后续集群规模增长，可将单节点替换为 cluster 版本（vminsert/vmselect/vmstorage三组件），相关仪表盘定义见 dashboards/vm/victoriametrics-cluster.json。

最后提醒：请务必将guide-vmsingle-values.yaml与grafana-single-values.yml纳入版本控制，它们是你后续升级与调整配置的唯一依据。

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析