【免费下载链接】helm-chartsPrometheus community Helm charts项目地址https://gitcode.com/gh_mirrors/he/helm-charts点击查看免费下载导读本指南以 prometheus-community/helm-charts 仓库中的 Prometheus chartcharts/prometheus为核心系统讲解如何在 Kubernetes 集群中通过 Helm 部署、配置和升级 Prometheus 监控系统。读完本文你将掌握 OCI 制品与传统 Helm 仓库两种安装方式、四个依赖子 chart 的启停控制、基于注解的服务发现与抓取配置、scrapeConfigs映射式新配置模型的用法以及从 v5.0 到 v29.0 各主要版本的升级注意事项与数据迁移方案。文中所有配置项与实现细节均以当前仓库的 values.yaml 与模板源码为事实依据。图表概览与前置条件Prometheus 是 Cloud Native Computing Foundation 旗下的系统与服务监控系统它以固定时间间隔从配置的目标上采集指标评估规则表达式展示结果并在观测到某些条件为真时触发告警。本 chart 使用 Helm 包管理器在 Kubernetes 集群上启动一个 Prometheus 部署。前置条件Kubernetes 1.19chart 的 Chart.yaml 中通过kubeVersion: 1.19.0-0声明Helm 3.7自 chart 版本 16.0 起安装即要求 Helm 3.7请先检查helm version当前 chart 元数据Chart.yaml显示appVersion: v3.15.0、version: 29.36.0即默认部署 Prometheus v3.15.0chart 版本 29.x 系列。安装与卸载该 chart 同时以两种方式分发OCI Artifactoci://ghcr.io/prometheus-community/charts/prometheus传统 Helm Repositoryhttps://prometheus-community.github.io/helm-chartschart 名为prometheus安装 Charthelm install [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/prometheus若要使用传统仓库先helm repo add再通过helm install [RELEASE_NAME] prometheus-community/prometheus安装helm repo与helm install的完整用法参见 Helm 官方文档。安装前可用helm show values预览默认配置见下文「Configuration」章节。依赖子 chart默认情况下该 chart 会一并安装四个依赖子 chart声明于 Chart.yaml 的dependencies段子 chart默认启用开关alertmanageralertmanager.enabledkube-state-metricskube-state-metrics.enabledprometheus-node-exporterprometheus-node-exporter.enabledprometheus-pushgatewayprometheus-pushgateway.enabled如需在安装时禁用某个依赖将对应的enabled设为false即可例如alertmanager: enabled: false kube-state-metrics: enabled: false prometheus-node-exporter: enabled: false prometheus-pushgateway: enabled: false注意prometheus-pushgateway子 chart 还默认带serviceAnnotations: prometheus.io/probe: pushgateway见 values.yaml配合默认 scrape config 中基于该注解的 relabel 规则自动发现 Pushgateway 目标。卸载 Charthelm uninstall [RELEASE_NAME]该命令会移除 chart 关联的所有 Kubernetes 组件并删除该 release。升级 Charthelm upgrade [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/prometheus --install--install使得 release 不存在时自动执行安装存在时执行升级。更新 values.schema.jsonvalues.schema.json 用于校验 chart 的 values 输入。当 values.yaml 发生结构变化如新增字段、改变值类型时需要手动修改 schema 文件或运行helm schema-gen values.yaml values.schema.json自动重新生成保证 schema 与最新 values 对齐helm schema-gen是 helm-schema-gen 插件提供的命令。升级与迁移指南版本要点README 按版本顺序记录了从 v5.0 到 v29.0 的升级注意事项下面按时间倒序梳理关键节点。升级到 29.0endpoints → endpointslice由于 Kubernetes 1.33 中endpoints角色被弃用自 29.0 起以下默认 scrape 配置中的kubernetes_sd_configs角色已从endpoints迁移到endpointslicekubernetes-api-serverskubernetes-service-endpointskubernetes-service-endpoints-slow当前 values.yaml 中这三个配置确实已使用role: endpointslice且 relabel 规则中的元标签同步改为__meta_kubernetes_endpointslice_port_name。若你之前对endpoints标签做了自定义 relabel升级前应相应调整为endpointslice标签。升级到 28.0scrapeConfigs 新配置模型这是近几个版本中最重要的一次配置结构变更原先定义在serverFiles.prometheus.yml.scrape_configs数组中的抓取配置已迁移到新字段scrapeConfigsmap抓取配置内容本身不变。新模型规则每个抓取配置可通过enabled: false禁用每个 key 成为该配置默认的job_name也可显式设置job_name覆盖新增的 key 默认启用配置体为原生 Prometheus 的scrape_config语法。extraScrapeConfigs字段仍可用于追加额外抓取配置不受此次变更影响。使用新字段并非强制serverFiles.prometheus.yml.scrape_configs仍按原有方式工作只是默认不再设置。若想继续使用旧字段升级前需显式置空新字段scrapeConfigs: null反之若你之前修改过默认抓取配置应将修改迁移进scrapeConfigs并移除旧配置。典型示例跳过 API server 的证书校验默认不跳过scrapeConfigs: kubernetes-api-servers: tls_config: insecure_skip_verify: true为默认 prometheus 抓取配置添加 basic authscrapeConfigs: prometheus: basic_auth: username: admin password_file: /etc/private/auth-passwd禁用 kubernetes-pods-slow 抓取配置scrapeConfigs: kubernetes-pods-slow: enabled: false新增一个 job_name 为 foo 的抓取配置默认启用scrapeConfigs: foo: honor_labels: true kubernetes_sd_configs: - role: service relabel_configs: - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_probe] action: keep regex: true源码侧templates/cm.yaml 中模板会遍历scrapeConfigs未显式声明enabled的 key 会被默认置为true渲染时以job_name缺省取 key开头并将pre_relabel_configs、relabel_configs、post_relabel_configs三段按顺序拼接后再输出最后剔除enabled、job_name、pre_relabel_configs、post_relabel_configs这些模板字段。单元测试 unittests/scrape_configs_test.yaml 验证了pre/post_relabel_configs渲染钩子模板化的 relabel 规则会被插入到 chart 管理的 relabel 规则前后且这两个辅助字段不会泄漏到最终prometheus.yml中。升级到 27.0insecure_skip_verify 默认值serverFiles.prometheus.yml.scrape_configs中 Prometheus 配置参数insecure_skip_verify已被注释掉从而保持 Prometheus 默认值即默认校验证书。若确实需要跳过证书校验请在抓取配置中显式设置该参数参考上文 28.0 的第一个示例。升级到 26.0默认 Prometheus v3该版本将默认 Prometheus 版本升级到 v3.0.0。升级前请参阅官方 Prometheus 3.0 迁移指南与 v3.0.0 发布说明确认你的查询语言、存储与配置兼容性。升级到 25.0remoteRead/remoteWrite URL 模板化server.remoteRead[].url与server.remoteWrite[].url现在支持模板化例如https://{{ .Release.Name }}.example.com。若已有条目中包含{{或}}必须转义为{{ {{ }}与{{ }} }}不含模板语法的条目不受影响。升级到 24.0要求 Kubernetes 1.19要求 Kubernetes 1.19。此外alertmanager 子 chart 1.0.0 用 prometheus-config-reloader 取代了 configmap-reload通过configmapReload.prometheus.extraArgs传入的旧命令行参数不兼容会与新 reloader 冲突请参照其源码调整参数。当前 values.yaml 中configmapReload.prometheus.image.repository即为quay.io/prometheus-operator/prometheus-config-reloadertag v0.94.1reloader 通过--watched-dir/etc/config监听配置目录、通过--reload-url调用 Prometheus 的/-/reload端点见 templates/deploy.yaml。升级到 23.0kube-state-metrics 镜像字段拆分kube-state-metrics 子 chart 5.0.0 将image.repository拆分为两个独立值image: registry: registry.k8s.io repository: kube-state-metrics/kube-state-metrics若自定义 values 或 CLI 参数设置了kube-state.metrics.image.repository请按新字段重新设置。同时若prometheus-pushgateway以 StatefulSet 持久卷方式部署升级 chart 前必须先删除该 StatefulSet例如kubectl delete sts -l app.kubernetes.io/nameprometheus-pushgateway -n monitoring --cascadeorphan建议升级前仔细审阅对应子 chart 的版本变更说明。升级到 22.0移除版本标签app.kubernetes.io/version标签已从 pod selector 中移除。因此升级前必须删除旧的 StatefulSet 或 Deployment且该操作会使Prometheus 在升级完成前停止工作kubectl delete deploy,sts -l app.kubernetes.io/nameprometheus升级到 21.0标签规范化Kubernetes 标签已按 Helm 3 标签与注解最佳实践更新映射关系如下旧标签新标签heritageapp.kubernetes.io/managed-bycharthelm.sh/chart[container version]app.kubernetes.io/versionappapp.kubernetes.io/namereleaseapp.kubernetes.io/instance升级前需根据配置删除旧工作负载runAsStatefulSet: false默认时执行kubectl delete deploy -l appprometheusrunAsStatefulSet: true时执行kubectl delete sts -l appprometheus随后再执行helm upgrade -i prometheus prometheus-community/prometheus升级到 20.0 / 24.0configmap-reload → prometheus-config-reloader与 24.0 相同configmap-reload 容器被 prometheus-config-reloader 取代configmapReload.prometheus.extraArgs中旧参数不兼容。升级到 19.0组件与配置项调整Prometheus 升级到 v2.40.5prometheus-pushgateway 升级到 2.0.0采用 Helm 标签最佳实践升级前请先阅读其升级文档禁用 kube-state-metrics 的条件由kubeStateMetrics.enabled改为kube-state-metrics.enabledDocker 镜像 tag 默认取自 Chart.yaml 的appVersion字段移除未使用的子 chart 配置子 chart 配置移至配置文件底部Prometheus 以 Deployment 部署时更新策略默认改为Recreatevalues.yaml 中server.strategy.type: Recreate保证 Helm 升级开箱即用.Values.server.extraTemplates与.Values.server.extraObjects被.Values.extraManifests取代.Values.server.enabled已移除所有组件均由子 chart 创建templates/server目录下的文件全部移到templates目录。helm upgrade [RELEASE_NAME] prometheus-community/prometheus --version 19.0.0升级到 18.0alertmanager 子 chart18.0.0 使用 alertmanager chart 的 alertmanager 服务。若做过配置修改请对比新旧alertmanager配置段的差异configmapReload.alertmanager专属段已并入alertmanager.configmapReload。升级前先将prometheus-serverdeployment 缩容为 0# In 17.x kubectl scale deploy prometheus-server --replicas0 # Upgrade helm upgrade [RELEASE_NAME] prometheus-community/prometheus --version 18.0.0升级到 17.0pushgateway 子 chart17.0.0 使用 prometheus-pushgateway chart 的 pushgateway 服务升级前同样先缩容# In 16.x kubectl scale deploy prometheus-server --replicas0 # Upgrade helm upgrade [RELEASE_NAME] prometheus-community/prometheus --version 17.0.0升级到 16.0内嵌服务拆分从 16.0 起内嵌服务alertmanager、node-exporter 等移出 Prometheus chart改以本仓库对应子 chart 作为依赖16.0.0 将 node-exporter 服务迁移到 prometheus-node-exporter chart。升级前先缩容# In 15.x kubectl scale deploy prometheus-server --replicas0 # Upgrade helm upgrade [RELEASE_NAME] prometheus-community/prometheus --version 16.0.0升级到 15.0relabeling 对齐社区约定relabeling 配置已对齐 Prometheus 社区约定做过手工 relabel 修改的需适配。升级前执行以下命令以便更新 kube-state-metricskubectl delete deployments.apps -l app.kubernetes.io/instanceprometheus,app.kubernetes.io/namekube-state-metrics --cascadeorphan升级到 9.0server.enabled9.0 新增开关控制 Prometheus Server 启停支持一个集群跑 Prometheus server、另一个集群跑 exporters的场景安装 server 时必须设server.enabled: true。升级到 5.0Prometheus 2.x 数据格式自 5.0 起本 chart 使用 Prometheus 2.x。2.x 引入新数据格式与 1.x 不兼容建议作为新 release 安装直接升级现有 release 不会成功。同时 2.x 对 alertmanager、存储与 recording rules 做了变更用户需先将告警规则更新为新格式才能升级。保留旧数据的具体做法见下面「示例迁移」。示例迁移保留旧数据升级到 2.x假设现有 release 名为prometheus-old按以下两步升级到 2.x 并保留旧数据更新prometheus-oldrelease禁用除 Prometheus server 外所有组件的抓取配置类似alertmanager: enabled: false alertmanagerFiles: alertmanager.yml: kubeStateMetrics: enabled: false nodeExporter: enabled: false pushgateway: enabled: false server: extraArgs: storage.local.retention: 720h serverFiles: alerts: prometheus.yml: rules: 部署 5.0 的新 release在 values.yaml 中设置常规 scrape config并将prometheus-old实例作为 remote-read 目标prometheus.yml: ... remote_read: - url: http://prometheus-old/api/v1/read ...完成后查询新 Prometheus 实例即可读到旧数据。注意当前 chart 的remoteRead/remoteWrite已支持模板化见 25.0且 templates/cm.yaml 会在prometheus.yml中渲染remote_read段。配置指南完整的可配置项含详细注释请参阅 values.yaml也可执行helm show values oci://ghcr.io/prometheus-community/charts/prometheus对每个依赖子 chart 同样可以执行上述命令查看其配置。核心 server 配置速览从 values.yaml 中整理出高频配置项镜像server.image.repository默认quay.io/prometheus/prometheustag为空时默认取 Chart.yaml 的appVersionv3.15.0支持模板化digest非空时按 digest 拉取distroless: true使用 distroless 镜像变体见 templates/deploy.yaml。全局抓取参数server.global.scrape_interval: 1m、scrape_timeout: 10s、evaluation_interval: 1m。保留策略server.retention: 15d默认 15 天server.retentionSize支持 B/KB/MB/GB/TB/PB/EB 单位二者分别渲染为--storage.tsdb.retention.time与--storage.tsdb.retention.size。命令行参数server.extraArgs如web.enable-remote-write-receiver: null、server.extraFlags默认含web.enable-lifecycle可启用web.enable-admin-api、storage.tsdb.no-lockfile、storage.tsdb.wal-compressionserver.defaultFlagsOverride可整体覆盖默认参数。持久化server.persistentVolume.enabled: true默认size: 8Gi、accessModes: [ReadWriteOnce]、mountPath: /datastorageClass设为-表示禁用动态供给existingClaim可绑定已有 PVC也可用emptyDirmedium、sizeLimit。工作负载形态server.statefulSet.enabledStatefulSet支持多副本 顺序 PVC、server.daemonSet.enabledDaemonSet可在每节点运行 agent 模式默认 Deploymentstrategy.type: Recreateserver.replicaCount: 1。模板 templates/deploy.yaml 按这三个开关分支渲染 KindStatefulSet 下通过volumeClaimTemplates创建 PVC并支持 1.27 的persistentVolumeClaimRetentionPolicy。探针readiness/liveness 默认走 HTTP 探测/-/ready、/-/healthyserver.tcpSocketProbeEnabled: true可切换为 TCP 探测startupProbe默认关闭probeHeaders可注入 HTTP Basic Auth 等自定义头。调度与拓扑nodeSelector、tolerations、affinity、podAntiAffinitysoft/hard默认关闭、podAntiAffinityTopologyKey默认kubernetes.io/hostname、topologySpreadConstraints、priorityClassName、runtimeClassName。服务与访问server.service.type: ClusterIP、servicePort: 80gRPC.enabled可在 Service 上开放 10901 端口供 thanos-querier 自动发现StatefulSet 场景可用statefulsetReplica固定访问某个副本以获得一致视图。扩展能力sidecarContainers支持模板化的 string 或 map 形式如挂 oauth2-proxy、extraInitContainers、extraVolumes/extraVolumeMounts、extraConfigmapMounts、extraSecretMounts、extraHostPathMounts、configFromSecret与configMapOverrideName二者不可同时设置设置后不再生成 ConfigMap见 templates/cm.yaml 与 templates/deploy.yaml。远程读写server.remoteWrite[]、server.remoteRead[]URL 支持模板化。配置扩展文件ruleFiles渲染进 ConfigMap 的规则文件、scrapeConfigFiles渲染为scrape_config_files列表、extraScrapeConfigs字符串形式追加原生 scrape config|块语法。告警文件serverFiles.alerting_rules.yml推荐取代已弃用的alerts、serverFiles.recording_rules.yml推荐取代已弃用的rulesprometheus.yml的rule_files默认加载/etc/config/recording_rules.yml与/etc/config/alerting_rules.yml以及两个已弃用路径。alertRelabelConfigs可配置alert_relabel_configs避免 HA Prometheus 重复告警。默认 scrapeConfigs 全览values.yaml 默认定义了 10 个抓取配置key 即默认 job_namekey角色/要点prometheus静态抓取 localhost:9090kubernetes-api-serversrole: endpointsliceHTTPS bearer tokenkubernetes-nodesrole: nodelabelmap 节点标签kubernetes-nodes-cadvisorrole: node抓取/metrics/cadvisorkubernetes-service-endpointsrole: endpointslice按服务注解抓取kubernetes-service-endpoints-slow同上scrape_interval: 5m、scrape_timeout: 30sprometheus-pushgatewayrole: service按prometheus.io/probe: pushgateway注解发现kubernetes-servicesrole: service走 blackbox/probekubernetes-podsrole: pod按 Pod 注解抓取kubernetes-pods-slow同上慢速抓取每个配置还支持pre_relabel_configs与post_relabel_configs接受模板化 YAML 块标量字符串渲染时分别插入 chart 管理的 relabel 规则前后实现见 templates/cm.yaml验证见 unittests/scrape_configs_test.yaml。通过注解抓取 Pod 指标chart 默认配置会让 Prometheus 抓取多种 Kubernetes 资源类型前提是这些资源带正确的注解。要给 Pod 开启抓取只需添加如下注解metadata: annotations: prometheus.io/scrape: true prometheus.io/path: /metrics prometheus.io/port: 8080prometheus.io/path应按 Pod 暴露指标的 URL 调整prometheus.io/port设为 Pod 提供指标的端口。注意prometheus.io/scrape与prometheus.io/port的值必须用双引号包裹字符串类型。这对应默认kubernetes-pods配置中的 relabel 规则匹配__meta_kubernetes_pod_annotation_prometheus_io_scrape true保留目标并将 scheme、path、port含 IPv4/IPv6 地址处理替换进抓取目标见 values.yaml。若需了解其他资源类型Service、Endpoints 等的抓取方式可运行helm template导出资源定义再对照 ConfigMap 中的 Prometheus 配置与官方文档中的relabel_config、kubernetes_sd_config语法理解。在多个服务之间共享告警安装或升级时可以使用多个 values 覆盖文件特别适合集群中存在多个服务的告警。例如把每个服务的告警拆成独立文件# service1-alert.yaml serverFiles: alerts: service1: - alert: anAlert # ... # service2-alert.yaml serverFiles: alerts: service2: - alert: anAlert # ...安装时同时传入helm install [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/prometheus -f values.yaml -f service1-alert.yaml -f service2-alert.yaml注意该命令示例中引用的 OCI 制品名为prom-label-proxy实际部署 Prometheus 时应替换为prometheus制品地址。serverFiles.alerts的 map 结构在渲染时会被模板转换为以 key 命名的 rule group见 templates/cm.yaml。RBAC 配置chart 会自动为server服务创建 Role 与 RoleBinding 资源。若要手动管理 RBAC设置rbac.createfalse并为每个服务指定已存在的 ServiceAccount设serviceAccounts.{{ component }}.createfalse且serviceAccounts.{{ component }}.name已有 SA 名。相关模板见 templates/clusterrole.yaml 与 templates/clusterrolebinding.yaml可参考其默认内容自定义。此外values.yaml 提供server.releaseNamespace与server.namespaces实现命名空间级服务发现无需 cluster-admin 权限需配合server.useExistingClusterRoleName使用。ConfigMap 文件Alertmanager 通过 alertmanager.yml 配置该文件及alertmanagerFiles中列出的其他文件会被挂载进alertmanagerPodPrometheus 通过 prometheus.yml 配置该文件及serverFiles中列出的其他文件会被挂载进serverPod。对应模板为 templates/cm.yaml它按serverFiles的每个 key 生成 ConfigMap data 条目并对prometheus.yml特殊处理拼入global、remote_write/remote_read、storagetsdb/exemplars、otlp、scrape_config_files、scrape_configs来自scrapeConfigs与extraScrapeConfigs以及alerting段。Ingress TLS若集群支持自动签发 TLS 证书如 cert-manager请参考相应机制文档。手动配置 TLS 的步骤如下为要保护的地址创建/获取密钥与证书对并在命名空间创建 TLS secretkubectl create secret tls prometheus-server-tls --certpath/to/tls.cert --keypath/to/tls.key在自定义values.yaml的 server Ingress TLS 段填入 secret 名称与主机名server: ingress: ## If true, Prometheus server Ingress will be created ## enabled: true ## Prometheus server Ingress hostnames ## Must be provided if Ingress is enabled ## hosts: - prometheus.domain.com ## Prometheus server Ingress TLS configuration ## Secrets must be manually created in the namespace ## tls: - secretName: prometheus-server-tls hosts: - prometheus.domain.com对应 Ingress 模板为 templates/ingress.yaml。此外 values.yaml 还支持 Gateway API 的 HTTPRouteserver.route.main需集群安装 Gateway API 控制器支持parentRefs、hostnames、matches、filters与httpsRedirectHTTP 301 重定向到 HTTPS模板见 templates/httproute.yaml。NetworkPolicy启用 NetworkPolicy 后到 Alertmanager 和 Kube State Metrics 的连接将只接受来自 Prometheus Server 的流量而所有进入 Prometheus Server 的入站连接仍被允许templates/network-policy.yaml 仅在 ingress 方向声明了 server 端口。启用步骤先安装实现 Kubernetes NetworkPolicy 规范的网络插件再将networkPolicy.enabled设为truenetworkPolicy: enabled: true如果 Prometheus 的抓取目标也启用了 NetworkPolicy你可能还需要手动创建一条允许 Prometheus 访问的 NetworkPolicy。访问 Prometheus安装完成后可从 templates/NOTES.txt 生成的提示信息中获取访问方式集群内release-prometheus-server.namespace.svc.cluster.local:servicePort默认 80 端口映射到 9090集群外取决于 Service 类型——NodePort 用NODE_IP:NODE_PORT、LoadBalancer 用SERVICE_IP、ClusterIP 用kubectl port-forward转发若配置了 Ingress 或 HTTPRoute则直接使用配置的主机名访问。结语本指南完整覆盖了 prometheus-community 的 Prometheus Helm chart 的安装、配置、服务发现与升级迁移全流程并补充了 values.yaml、Chart.yaml、templates/cm.yaml、templates/deploy.yaml 等源码级佐证。实际操作时建议以helm show values输出为准核对默认值并在升级前按版本要点逐项检查尤其是 28.0 的scrapeConfigs迁移与 29.0 的endpointslice角色变更必要时先在小集群演练再对生产环境操作。赞分享【免费下载链接】helm-chartsPrometheus community Helm charts项目地址https://gitcode.com/gh_mirrors/he/helm-charts点击查看免费下载相关推荐Prometheus SQL Exporter Helm Chart 部署与配置实战指南prometheus-community/helm-chartsPrometheus SQL Exporter Helm Chart 部署与配置实战指南prometheus community/helm charts Pkube-prometheus-stack Helm Chart 完整指南安装、配置、高可用与迁移实战kube prometheus stack Helm Chart 完整指南安装、配置、高可用与迁移实战 kube prometheus stack 是 ProPrometheus Operator Helm Chart 迁移指南从仓库内置 Chart 到 kube-prometheus-stackPrometheus Operator Helm Chart 迁移指南从仓库内置 Chart 到 kube prometheus stack 本文聚焦 Pro云原生可观测性上一篇Lightdash Autopilot 的 Agent 播报规范SKILL.md 如何定义一个 BI 代理的 Slack 消息风格下一篇Home Assistant数据持久化状态历史与存储方案全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考