Prometheus Operator 平台部署指南：在 Kubernetes 上部署 Prometheus 与 Alertmanager 实例

• 云原生
• 可观测性

本文是 Prometheus Operator 的Platform Guide（平台指南），基于官方文档 Documentation/platform/platform-guide.md 展开。文章将带领你完成从零部署一套可用的监控栈：先为 Prometheus 配置 RBAC 权限并创建首个Prometheus自定义资源，再部署高可用的Alertmanager集群，最后通过alerting.alertmanagers字段把二者打通，让告警真正流动起来。读完本文，你将掌握 Prometheus Operator 平台侧部署与集成告警的核心实操能力，并理解其底层 CRD 与控制器的工作原理。

1. 前置知识：Prometheus Operator 与自定义资源

Prometheus Operator 是一个 Kubernetes Operator，以自定义资源（Custom Resources）的方式提供 Prometheus 及其相关监控组件的原生部署与管理能力，其核心目标包括自动化管理监控目标、通过 Label Selector 抽象 Prometheus 重打标签（Relabeling）配置、以及简化版本、持久化、保留策略、副本数等基础部署配置。

Operator 提供的核心 CRD 包括：Prometheus、Alertmanager、ThanosRuler、ServiceMonitor、PodMonitor、Probe、PrometheusRule、AlertmanagerConfig、PrometheusAgent与ScrapeConfig。其中，本指南聚焦于其中两个"实例型"资源：Prometheus与Alertmanager。相关资源总览可参考 Documentation/getting-started/introduction.md。

如果你还没有接触过 Prometheus Operator，建议先阅读 Documentation/getting-started/introduction.md 再继续本指南。

2. 部署 Prometheus 实例

Prometheus 服务器自身需要通过 Kubernetes API 发现抓取目标（Target）与 Alertmanager 实例，因此在创建Prometheus资源之前，必须为 Prometheus 使用的 ServiceAccount 预先配置好 RBAC 授权规则。

2.1 创建 ServiceAccount

首先为 Prometheus 创建一个ServiceAccount：

apiVersion: v1 kind: ServiceAccount metadata: name: prometheus

该清单与 example/rbac/prometheus/prometheus-service-account.yaml 完全一致。

2.2 创建 ClusterRole

接下来创建一个ClusterRole，授予 Prometheus 在集群内发现并抓取目标所需的必要权限：

apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: prometheus rules: - apiGroups: [""] resources: - nodes - nodes/metrics - services - endpoints - pods verbs: ["get", "list", "watch"] - apiGroups: [""] resources: - configmaps verbs: ["get"] - apiGroups: - discovery.k8s.io resources: - endpointslices verbs: ["get", "list", "watch"] - apiGroups: - networking.k8s.io resources: - ingresses verbs: ["get", "list", "watch"] - nonResourceURLs: ["/metrics"] verbs: ["get"]

该清单与 example/rbac/prometheus/prometheus-cluster-role.yaml 完全一致，各规则的用途可归纳如下：

• nodes、nodes/metrics、services、endpoints、pods的get/list/watch：用于 Kubernetes 服务发现（Service Discovery），这是 Prometheus 发现抓取目标的基础；
• endpointslices：支持基于 EndpointSlice 的服务发现；
• ingresses：用于从 Ingress 对象中发现抓取目标；
• configmaps的get：Prometheus 的 sidecar（config-reloader）需要读取 ConfigMap 中的规则文件（rule files）；
• 非资源 URL/metrics的get：允许 Prometheus 抓取 Kubernetes apiserver 自身的/metrics指标。

注意：因为 Prometheus 只读取而不会修改 Kubernetes API 中的对象，所以只需要get、list、watch动作即可。更详细的权限说明参见 Documentation/platform/rbac.md。

2.3 创建 ClusterRoleBinding

再创建一个ClusterRoleBinding，把上面的ClusterRole绑定到 Prometheus 的ServiceAccount上：

apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: prometheus roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: prometheus subjects: - kind: ServiceAccount name: prometheus namespace: default

该清单与 example/rbac/prometheus/prometheus-cluster-role-binding.yaml 完全一致。由于该ClusterRole通常会被多个Prometheus对象复用，因此这里使用ClusterRoleBinding而非RoleBinding。

注意：创建ClusterRole并绑定到 Prometheus Pod 使用的ServiceAccount需要集群管理员权限。Prometheus Pod 使用的ServiceAccount是通过Prometheus对象的spec.serviceAccountName字段指定的。

2.4 应用清单并部署 Prometheus 实例

将上述三个清单依次应用：

kubectl apply -f example/rbac/prometheus/prometheus-service-account.yaml kubectl apply -f example/rbac/prometheus/prometheus-cluster-role.yaml kubectl apply -f example/rbac/prometheus/prometheus-cluster-role-binding.yaml

RBAC 资源就绪后，即可创建最基本的 Prometheus 实例：

apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: prometheus spec: serviceAccountName: prometheus

这是 example/user-guides/getting-started/prometheus.yaml 的完整内容——一个最小化的Prometheus资源，只声明了serviceAccountName字段。Operator 会据此自动生成对应的StatefulSet、Service（名为prometheus-operated）、Secret（包含生成的 Prometheus 配置文件）等附属资源。

2.5 验证实例运行状态

执行以下命令观察Prometheus资源的状态变化：

kubectl get -n default prometheus prometheus -w

-w参数会持续监听资源变化，当实例创建成功、Pod 进入 Ready 状态后，即可在Status中看到更新信息。更细粒度的验证可以查看对应 StatefulSet 与 Pod：

kubectl get statefulset -l operated-prometheus=true kubectl get pods -l prometheus=prometheus

Prometheus 生成的 Pod 会带有prometheus: <prometheus-name>标签，例如名为prometheus的实例，其 Pod 标签为prometheus: prometheus。在稍后创建Service时，这个标签正是 selector 的依据。

3. 部署 Alertmanager 集群

部署 Alertmanager 同样简单，一个最基础的Alertmanager资源即可创建出多副本的高可用集群：

apiVersion: monitoring.coreos.com/v1 kind: Alertmanager metadata: name: example spec: replicas: 3

该清单与 example/user-guides/alerting/alertmanager-example.yaml 完全一致，spec.replicas: 3声明了 3 个副本。Operator 会将其物化为一个带 3 副本的StatefulSet，并自动为这些副本配置mesh 集群通信（端口 9094），使 Alertmanager 之间可以互相同步告警状态。

等待所有 Alertmanager Pod 就绪：

kubectl get pods -l alertmanager=example -w

从源码角度看，pkg/alertmanager/statefulset.go 中定义了 Alertmanager 的关键端口常量：Web 端口为9093（alertmanagerWebPort），Mesh 集群通信端口为9094（alertmanagerMeshPort），并会在生成 StatefulSet 时同时暴露mesh-tcp与mesh-udp两个端口用于集群内部通信。这就是"3 副本 Alertmanager 自动组成集群"的底层实现依据。

4. 理解 Prometheus 与 Alertmanager 的关系

光有 Alertmanager 集群本身并没有实际价值——Alertmanager 的职责是接收来自 Prometheus 的告警，并在此基础上提供：

• 去重（Deduplicate）：对 Prometheus 发来的重复告警进行合并；
• 静默（Silence）：在指定时间窗口内抑制特定告警；
• 路由与分组通知（Routing & Grouping）：将告警按规则分组，并通过 PagerDuty、OpsGenie、邮件、聊天工具等各类集成渠道发送通知。

因此，要让 Alertmanager 发挥作用，必须把它与 Prometheus 集成起来，让 Prometheus 知道"把告警发给谁"。

5. 将 Alertmanager 集成到 Prometheus

集成过程分为两步：先把 Alertmanager 服务暴露出来，再在Prometheus资源中声明alerting.alertmanagers配置。

5.1 暴露 Alertmanager 服务

要访问 Alertmanager 的 Web 界面，需要把服务暴露到集群外部。为了简单起见，这里使用NodePort类型的Service：

apiVersion: v1 kind: Service metadata: name: alertmanager-example spec: type: NodePort ports: - name: web nodePort: 30903 port: 9093 protocol: TCP targetPort: web selector: alertmanager: example

该清单与 example/user-guides/alerting/alertmanager-example-service.yaml 完全一致，关键点在于：

• selector: alertmanager: example必须与Alertmanager资源名对应——Operator 生成的 Alertmanager Pod 带有alertmanager: <alertmanager-name>标签，这里的example正是前面Alertmanager对象的名字；
• targetPort: web引用的是容器端口的名称，即 Alertmanager 的 9093 Web 端口；
• nodePort: 30903固定了节点上的外部端口。

Service 创建成功后，Alertmanager 的 Web 服务器即可通过节点的 IP 地址与端口30903访问：http://<node-ip>:30903/。

注意：这种直接暴露 Alertmanager Web 服务器的方式在生产环境中可能并不合适。更多暴露方案（ClusterIP + Kubernetes API 代理、Ingress 等）请参考 Documentation/platform/exposing-prometheus-and-alertmanager.md。

5.2 在 Prometheus 中配置 Alertmanager

此时 Alertmanager 集群已完全可用且具备高可用能力，但还没有任何告警会发给它。接下来创建一个会向该 Alertmanager 集群发送告警的 Prometheus 实例：

apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: example spec: serviceAccountName: prometheus replicas: 2 alerting: alertmanagers: - namespace: default name: alertmanager-example port: web

这是 example/user-guides/alerting/prometheus-example.yaml 的核心告警配置片段。Prometheus资源会通过alerting.alertmanagers列表，发现前面创建的Service背后的所有Alertmanager 实例——注意name、namespace、port三个字段必须与 AlertmanagerService的定义完全匹配：

• name: alertmanager-example：对应 Service 的名称；
• namespace: default：对应 Service 所在的命名空间；
• port: web：对应 Service 端口名称web（9093）。

从 API 定义看，pkg/apis/monitoring/v1/prometheus_types.go 中PrometheusSpec的Alertmanagers []AlertmanagerEndpoints字段即承载此配置，其注释明确说明这是"Prometheus 应向哪些 alertmanager endpoints 发送告警"的选择器列表。

5.3 验证集成结果

打开 Prometheus 的 Web 界面，进入"Status > Runtime & Build Information"页面，检查 Prometheus 是否已发现 3 个 Alertmanager 实例（对应 3 副本的StatefulSet）。如果一切正常，就说明 Prometheus 已把 Alertmanager 集群作为告警接收端纳管，后续通过PrometheusRule定义的告警规则一旦触发，就会按 Alertmanager 的路由与通知配置分发出去。

6. 更深一层：Operator 的告警发现机制

从实现层面看，alerting.alertmanagers之所以能"自动发现多个实例"，是因为 Operator 在生成 Prometheus 配置时会根据该字段解析出一个可用的 Alertmanager 服务端点列表，并将其写入 Prometheus 的alertmanager_config。当Service后面有多个 Pod 时（例如这里 3 副本的 Alertmanager），Prometheus 会把告警负载均衡地发送给集群中的各个成员，从而实现告警投递的高可用。

AlertmanagerEndpoints类型还支持更多高级字段（如scheme、pathPrefix、apiVersion、bearerTokenFile、tlsConfig等），可用于自定义告警投递的协议、路径与认证方式，具体字段定义同样位于 pkg/apis/monitoring/v1/prometheus_types.go 附近，需要更精细控制时可查阅 API 参考 Documentation/api-reference/api.md。

7. 补充：Prometheus 与 Alertmanager 的多种暴露方式

本文使用了最简单的NodePort方式暴露服务。在真实生产环境中，还可以根据场景选择以下方式（详见 Documentation/platform/exposing-prometheus-and-alertmanager.md）：

• Kubernetes API 代理：创建ClusterIP类型的 Service，借助kubectl proxy通过http://127.0.0.1:8001/api/v1/proxy/namespaces/<namespace>/services/<service-name>:<port>/访问。此时需要在Prometheus/Alertmanager资源中配置spec.externalUrl指向完整的外部访问 URL；
• Ingress：为内部ClusterIPService 创建 Ingress 规则，将/prometheus、/alertmanager等路径路由到对应的监控服务，同样需要配合spec.externalUrl使用。若 Ingress 暴露在公网，务必启用外部认证或 IP 白名单等访问控制。

无论采用哪种方式，spec.externalUrl都必须与实际的访问地址保持一致，否则 Prometheus / Alertmanager Web 界面中的链接与回调地址会出现错乱。

8. 小结

至此，你已完成 Prometheus Operator 平台侧的完整入门链路：

1. 通过ServiceAccount+ClusterRole+ClusterRoleBinding为 Prometheus 配置了服务发现所需的 RBAC 权限；
2. 创建了最小化的Prometheus资源并验证其运行状态；
3. 部署了 3 副本的Alertmanager高可用集群；
4. 通过NodePortService 暴露 Alertmanager，并在Prometheus资源的spec.alerting.alertmanagers中完成告警链路集成，最终在 Prometheus Web 界面确认实例发现成功。

下一步，你可以结合 Documentation/getting-started/introduction.md 中提到的ServiceMonitor、PodMonitor、PrometheusRule等资源，为应用配置抓取目标与告警规则，或参考 Documentation/user-guides/basic-auth.md 等用户指南完善认证与安全配置，将这套监控栈真正落地到生产环境。

• 云原生
• 可观测性