企业官网建设流程全解析

本指南以 Prometheus Community 官方维护的kube-state-metricsHelm Chart（本仓库 charts/kube-state-metrics）为对象，完整讲解其安装、升级、配置与指标端点安全加固方案。读完本文，你将掌握通过 OCI 镜像与 Helm 仓库两种方式部署 kube-state-metrics、按集群版本选择性启用 admission policy collectors、以及用 kube-rbac-proxy 或内置--auth-filter保护指标端点三种核心实战能力，并了解 Chart 内部模板如何把配置值渲染为最终的 Deployment、RBAC 与 ServiceMonitor 资源。

图表概览与版本信息

Chart 的元数据定义在 charts/kube-state-metrics/Chart.yaml：

apiVersion: v2 name: kube-state-metrics description: Install kube-state-metrics to generate and expose cluster-level metrics type: application version: 8.6.0 appVersion: 2.20.0

当前 Chart 版本为8.6.0，对应的 kube-state-metrics 应用版本为2.20.0。Chart 通过appVersion与image.tag的联动决定实际拉取的镜像：默认镜像为registry.k8s.io/kube-state-metrics/kube-state-metrics，tag留空时使用v + .Chart.AppVersion（即v2.20.0），这一逻辑实现在 _helpers.tpl 的kube-state-metrics.image模板中，也可通过global.imageRegistry覆盖 registry 主机名。

安装、卸载与升级

Chart 同时以OCI Artifact和传统Helm Repository两种形式分发：

• OCI Artifact：oci://ghcr.io/prometheus-community/charts/kube-state-metrics
• Helm Repository：https://prometheus-community.github.io/helm-charts，chart 名为kube-state-metrics

安装 Chart

helm install [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/kube-state-metrics [flags]

例如：

helm install ksm oci://ghcr.io/prometheus-community/charts/kube-state-metrics --namespace monitoring --create-namespace

若使用传统仓库方式，需先helm repo add prometheus-community https://prometheus-community.github.io/helm-charts，再执行helm install [RELEASE_NAME] prometheus-community/kube-state-metrics [flags]。

卸载 Chart

helm uninstall [RELEASE_NAME]

该命令会移除与 Chart 关联的所有 Kubernetes 组件并删除 release 记录。若安装时创建了独立命名空间，可按需另行清理。

升级 Chart

helm upgrade [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/kube-state-metrics [flags]

升级前建议先查看目标版本默认值，确认变更点：

helm show values oci://ghcr.io/prometheus-community/charts/kube-state-metrics

从 stable/kube-state-metrics 与 kubernetes/kube-state-metrics 迁移

原官方文档明确说明：可以原地升级（in-place），即使用你现有的 release 名称，改用新的 Chart 仓库执行一次 upgrade 即可，无需先卸载再安装。这样 ServiceAccount、RBAC 等资源的引用关系不会因名称变化而断裂。

大版本升级注意事项

• 升级到 v8.0.0：移除了对CiliumNetworkPolicy的配置支持（属于厂商特定资源）；networkPolicy.flavor设置不再生效，可以安全删除，因为现在只支持 Kubernetes 原生NetworkPolicy资源（对应 values.yaml 中的networkPolicy配置块）。
• 升级到 v6.0.0：移除了对已废弃的 Pod Security Policy（PSP）资源的支持。
• 升级到 v3.0.0：随 Chart 升级到 kube-state-metrics v2.0（应用侧变更见上游 changelog），Chart 侧变化包括：要求 Helm v3 及以上（不再支持 Helm v2）；collectors键更名为resources；namespace键更名为namespaces。

查看全部可配置项

执行以下命令即可看到带详细注释的完整配置清单：

helm show values oci://ghcr.io/prometheus-community/charts/kube-state-metrics

仓库内的默认值即 charts/kube-state-metrics/values.yaml，包含镜像、RBAC、Service、ServiceMonitor、ScrapeConfig、网络策略、探针、VPA、自定义资源状态指标（customResourceState）等全部开关与默认值，是排查与调优时的权威参照。

Admission Policy Collectors（准入策略采集器）

kube-state-metrics v2.20.0 及以后版本支持以下准入策略采集器，它们使用admissionregistration.k8s.io/v1API。为了兼容旧版 Kubernetes 与自定义镜像覆盖，本 Chart 默认不启用这些采集器，属于 opt-in 特性：

只应通过collectorsExtra或collectors启用集群实际支持的采集器。例如在 Kubernetes v1.36+ 上：

collectorsExtra: - mutatingadmissionpolicies - mutatingadmissionpolicybindings - validatingadmissionpolicies - validatingadmissionpolicybindings

而在 Kubernetes v1.30 ~ v1.35 上，只启用两个 validating admission policy 采集器。不要在镜像被覆盖为早于 v2.20.0 的 kube-state-metrics 版本时启用这些采集器，否则进程会因未知的--resources值而无法正常启动。

这些资源是**集群级（cluster-scoped）**的，需要集群范围的 RBAC 权限。使用默认 RBAC 配置时，Chart 只为所选采集器生成对应的list、watch权限——这一逻辑可以在 role.yaml 中看到：模板遍历kube-state-metrics.collectors计算出的活跃采集器列表，按has "mutatingadmissionpolicies" $activeCollectors等条件逐项追加规则。如果你自行管理 RBAC，需要手动在admissionregistration.k8s.ioAPI 组中为所选资源授予这些权限。

值得说明的是，默认的 values.yaml 中collectors列表（如certificatesigningrequests、configmaps、nodes、pods、services、statefulsets等约 29 项）即默认启用项，而ingressclasses、clusterroles、roles、serviceaccounts等以注释形式列出、需手动取消注释启用；admission policy 采集器同样以注释形式预置在collectorsExtra示例中。Chart 提供了collectorsExclude与collectorsExtra两个轻量调整手段：collectorsExclude从默认列表中剔除条目，collectorsExtra在剔除后追加条目（自动去重），两者都基于.Values.collectors生效。若设置collectors: []，则collectorsExtra将整体作为--resources列表。最终列表由 _helpers.tpl 中的kube-state-metrics.collectors模板计算，并渲染进 Deployment 的--resources=参数（见 deployment.yaml）。

使用 kube-rbac-proxy 保护指标端点

设置kubeRBACProxy.enabled: true后，Chart 会为每个暴露的 HTTP 端点（metrics 与 telemetry）各部署一个 kube-rbac-proxy 边车容器。从 deployment.yaml 可以看到，启用时主容器会改为监听127.0.0.1（--host=127.0.0.1），由kube-rbac-proxy-http容器通过--secure-listen-address=:8080、--upstream=http://127.0.0.1:9090/对外提供 HTTPS 服务；若同时启用了selfMonitor.enabled，还会额外注入kube-rbac-proxy-telemetry容器代理 telemetry 端点。默认值为 values.yaml 中的kubeRBACProxy配置块：

kubeRBACProxy: enabled: false image: registry: quay.io repository: brancz/kube-rbac-proxy tag: v0.23.0 ignoreProbePaths: true # 为 /livez,/readyz 设置 --ignore-paths，保证探针可用 extraArgs: [] port: 9090 # kube-state-metrics 上游端口 proxyEndpointsPort: 8888 # proxy 自身健康检查端口

代理的授权配置由模板 rbac-configmap.yaml 生成，其核心是resourceAttributes授权规则：要求请求者对services/<release>-kube-state-metrics这个 subresource 具备get权限。因此，要授权抓取方访问，需要为其附加一个带如下规则的 ClusterRole：

apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: kube-state-metrics-read rules: - apiGroups: [ "" ] resources: ["services/kube-state-metrics"] verbs: - get

抓取方（例如 Prometheus 的 ServiceAccount）再通过 ClusterRoleBinding 绑定该角色即可。请求经由 kube-rbac-proxy 转为 HTTPS，并由代理完成 SubjectAccessReview 鉴权。

使用内置 auth-filter 作为替代方案

kube-rbac-proxy之外的另一种方案是让 kube-state-metrics 自己完成请求的认证与授权——启用其内置的--auth-filter。设置authFilter.enabled: true后，Chart 会向主容器追加--auth-filter参数，并自动为 RBAC 增加tokenreviews与subjectaccessreviews的create权限。这一条件在 role.yaml 中可见：

{{- if or $.Values.kubeRBACProxy.enabled $.Values.authFilter.enabled }} - apiGroups: ["authentication.k8s.io"] resources: [tokenreviews] verbs: ["create"] - apiGroups: ["authorization.k8s.io"] resources: [subjectaccessreviews] verbs: ["create"] {{- end }}

对应的配置开关位于 values.yaml：

authFilter: enabled: false

启用后，抓取方必须以 ServiceAccount 令牌等方式完成认证，并被授权对kube-state-metricsService 执行get（与 kube-rbac-proxy 场景相同的资源级授权模型）。抓取方所需的 ClusterRole 与 ClusterRoleBinding 完整示例可参考上游 kube-state-metrics 的 Authentication/Authorization 文档（Protecting Metrics Endpoints 一节）。两种方案二选一即可，二者互斥部署时反而会重复引入鉴权层。

与 Prometheus 生态集成：ServiceMonitor 与 ScrapeConfig

Chart 原生支持通过 Prometheus Operator 的 CRD 暴露抓取目标：

• prometheus.monitor.enabled: true时生成ServiceMonitor（模板见 servicemonitor.yaml），可配置additionalLabels、namespaceSelector、jobLabel、以及针对 http/metrics 两个端点的interval、scrapeTimeout、relabelings、metricRelabelings、bearerTokenFile、tlsConfig等；还支持sampleLimit、targetLimit、labelLimit、labelNameLengthLimit、labelValueLengthLimit五类抓取限制（渲染逻辑见 _helpers.tpl 的servicemonitor.scrapeLimits）。
• 若使用 kube-prometheus-stack 且希望 ServiceMonitor 的标签能匹配其默认选择器，可设置releaseLabel: true，它会为所有资源额外打上release: <Release.Name>标签。
• prometheus.scrapeconfig.enabled: true时生成ScrapeConfig资源（默认jobName: kube-state-metrics，honorLabels: true），适合需要多实例安全扩展的场景；使用前应先将prometheus.monitor.enabled置为false以避免重复采集同一批指标。

常用调优配置速览

• 命名空间范围：默认采集所有命名空间；可通过namespaces（逗号分隔字符串或 YAML 列表）、releaseNamespace: true（仅 release 命名空间）与namespacesDenylist（排除列表）控制采集范围，三者合并/去重逻辑在 deployment.yaml 中完成并渲染为--namespaces/--namespaces-denylist参数。
• 指标裁剪：metricAllowlist/metricDenylist控制暴露哪些指标（二者互斥）；metricLabelsAllowlist与metricAnnotationsAllowList可将额外 Kubernetes label/annotation 纳入资源的 labels 指标（例如=namespaces=[team],pods=[app]，单资源可用*放行所有键，但有显著性能开销）。
• 自动分片：autosharding.enabled: true时以 StatefulSet 部署并借助上游内置自动分片特性（通过POD_NAME/POD_NAMESPACE环境变量配合--pod、--pod-namespace参数实现），将数据按<.Values.replicas>个 Pod 分片，属于实验性功能，无稳定性保证；关闭时默认replicas: 1，可设置updateStrategy: Recreate避免滚动更新期间双实例短暂并存。
• 自定义资源状态指标：customResourceState.enabled: true会创建 ConfigMap 承载 CRD 指标配置（key: config.yaml），并挂载到/etc/customresourcestate/，同时通过--custom-resource-state-config-file传给主容器；对应的 CRDlist/watch规则由 role.yaml 按rbac.customResourceState.createClusterRoleRules控制，自定义资源 API 组权限需通过rbac.extraRules补充。
• 安全基线：默认securityContext以runAsNonRoot: true、runAsUser/runAsGroup/fsGroup: 65534运行，并启用seccompProfile: RuntimeDefault；容器级containerSecurityContext默认readOnlyRootFilesystem: true、allowPrivilegeEscalation: false并 drop 全部 capabilities，可作为生产集群的默认安全起点。

小结

kube-state-metrics是 Prometheus 生态中最常用的集群状态指标来源，而本 Chart 将部署、RBAC、ServiceMonitor 与安全加固收敛为可声明式管理的配置。部署时建议先helm show values核对默认值，再按集群 Kubernetes 版本审慎启用 admission policy collectors；指标端点若需对外授权，可在kube-rbac-proxy与内置auth-filter之间按运维习惯选择其一。相关模板与默认值均可直接查阅本仓库 charts/kube-state-metrics/templates 与 values.yaml，CI 测试用例（如 collectors_test.yaml、rbac_aggregation_rule_test.yaml）也是验证采集器与 RBAC 渲染行为的良好参考。