自部署收集使用入门

本文档介绍了如何使用自部署收集为 Prometheus 设置 Google Cloud Managed Service。示例应用会部署到 Kubernetes 集群，并由将收集的指标存储在 Monarch 中的 Prometheus 服务器进行监控。

本页面介绍如何完成以下任务：

• 设置环境和命令行工具。
• 为启用了 Workload Identity 的集群配置服务帐号。
• 在 Kubernetes 上运行普适性 Prometheus 二进制文件。
• 控制将哪些指标注入到 Managed Service for Prometheus。
• 将 Managed Service for Prometheus 与 prometheus-operator 设置集成。
• 手动编译并运行 Prometheus 二进制文件。

借助自部署数据收集，您可以像往常一样管理 Prometheus 安装。唯一的区别在于运行 Managed Service for Prometheus 普适性替换二进制文件 gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0，而不是上游 Prometheus 二进制文件。

普适性二进制文件提供带有 --export.* 标志的其他配置选项。如需了解详情，请参阅 --help 选项的输出。本文档介绍了最重要的选项。

Managed Service for Prometheus 不支持从联合服务器或用作远程写入接收器的服务器导出指标。您可以使用过滤条件和局部聚合来复制所有联合服务器功能，包括在发送到 Monarch 之前通过聚合数据来减少注入量。

将数据流式传输到 Managed Service for Prometheus 会消耗额外的资源。如果您要自行部署收集器，我们建议将 CPU 和内存限额提高 5 倍，并根据实际使用情况调整限额。

如需详细了解代管式和自行部署的数据收集，请参阅使用 Managed Service for Prometheus 收集数据。

准备工作

本部分介绍本文档中描述的任务所需的配置。

设置项目和工具

要使用 Google Cloud Managed Service per Prometheus，您需要以下资源：

• 启用了 Cloud Monitoring API 的 Google Cloud 项目。

  • 如果您没有 Cloud 项目，请执行以下操作：

    1. 在控制台中，进入新建项目：

       创建新项目

    2. 在项目名称字段中，为您的项目输入一个名称，然后点击创建。

    3. 转到结算：

       转到“结算”

    4. 在页面顶部选择您刚刚创建的项目（如果尚未选择）。

    5. 系统会提示您选择现有付款资料或创建新的付款资料。

    默认情况下，新项目会启用 Monitoring API。

  • 如果您已有 Cloud 项目，请确保已启用 Monitoring API：

    1. 转到 API 和服务：

       转到 API 和服务

    2. 选择您的项目。

    3. 点击启用 API 和服务。

    4. 搜索“Monitoring”。

    5. 在搜索结果中，点击“Cloud Monitoring API”。

    6. 如果未显示“API 已启用”，请点击启用按钮。

• Kubernetes 集群。如果您没有 Kubernetes 集群，请按照 GKE 快速入门中的说明进行操作。

您还需要以下命令行工具：

• gcloud
• kubectl

gcloud 和 kubectl 工具是 Google Cloud CLI 的一部分。如需了解如何安装这些工具，请参阅管理 Google Cloud CLI 组件。如需查看已安装的 gcloud CLI 组件，请运行以下命令：

gcloud components list

配置您的环境

为避免重复输入您的项目 ID 或集群名称，请执行以下配置：

• 按如下方式配置命令行工具：

  • 配置 gcloud CLI 以引用您的 Cloud 项目的 ID：

    gcloud config set project PROJECT_ID
    

  • 配置 kubectl CLI 以使用集群：

    kubectl config set-cluster CLUSTER_NAME
    

  如需详细了解这些工具，请参阅以下内容：

  • gcloud CLI 概览
  • kubectl 命令

设置命名空间

为您在示例应用中创建的资源创建 gmp-test Kubernetes 命名空间：

kubectl create ns gmp-test

验证服务帐号凭据

如果您的 Kubernetes 集群启用了 Workload Identity，则可以跳过此部分。

在 GKE 上运行时，Managed Service for Prometheus 会自动根据 Compute Engine 默认服务帐号从环境中检索凭据。默认情况下，默认服务帐号具有必要的权限 monitoring.metricWriter 和 monitoring.viewer。如果您未使用 Workload Identity，并且之前从默认节点服务帐号中移除了其中一个角色，则必须重新添加这些缺少的权限，然后才能继续。

如果您不在 GKE 上运行，请参阅明确提供凭据。

为 Workload Identity 配置服务帐号

如果您的 Kubernetes 集群未启用 Workload Identity，则可以跳过此部分。

Managed Service for Prometheus 使用 Cloud Monitoring API 捕获指标数据。如果您的集群使用的是 Workload Identity，则必须向您的 Kubernetes 服务帐号授予 Monitoring API 权限。本节介绍以下内容：

• 创建专用 Google Cloud 服务帐号 gmp-test-sa。
• 将 Google Cloud 服务帐号绑定到测试命名空间 gmp-test 中的默认 Kubernetes 服务帐号。
• 为 Google Cloud 服务帐号授予必要的权限。

创建和绑定服务帐号

此步骤显示在 Managed Service for Prometheus 文档中的多个位置。如果您在执行先前的任务时已经执行此步骤，则无需重复执行。请直接跳到向服务帐号授权。

以下命令序列会创建 gmp-test-sa 服务帐号并将其绑定到 gmp-test 命名空间中的默认 Kubernetes 服务帐号：

gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[gmp-test/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace gmp-test \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

如果您使用的是其他 GKE 命名空间或服务帐号，请适当调整命令。

向服务帐号授权

相关权限组已收集到多个角色中，您可以将这些角色授予主帐号（在此示例中为 Google Cloud 服务帐号）。如需详细了解 Monitoring 角色，请参阅访问权限控制。

以下命令会向 Google Cloud 服务帐号 gmp-test-sa 授予写入指标数据所需的 Monitoring API 角色。

如果您在执行先前的任务时已经为 Google Cloud 服务帐号授予了特定角色，则无需再次执行此操作。

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

生产环境中的 Workload Identity

本文档中描述的示例将 Google Cloud 服务帐号绑定到默认 Kubernetes 服务帐号，并授予 Google Cloud 服务帐号使用 Monitoring API 所需的所有权限。

在生产环境中，您可能需要使用更精细的方法，其中每个组件对应一个服务帐号，并且每个服务帐号都具有最小的权限。如需详细了解如何为工作负载身份管理配置服务帐号，请参阅使用 Workload Identity。

设置自部署收集

本部分介绍如何设置和运行使用自部署收集的示例应用。

部署示例应用

代管式服务为在其 metrics 端口上发出 Prometheus 指标的示例应用提供清单。该应用使用三个副本。

要部署示例应用，请运行以下命令：

kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.3-gke.0/examples/example-app.yaml

运行替换的 Prometheus 二进制文件

要注入示例应用发出的指标数据，请部署 Google 的 Prometheus 服务器的分支版本，该服务器配置为爬取工作负载的指标及其自己的指标端点。

1. 如需部署分支服务器，请运行以下命令：

   kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.3-gke.0/examples/prometheus.yaml
   

   此已部署的 Prometheus 服务器是上游 Prometheus 二进制文件的瘦分支。其行为类似于标准 Prometheus 服务器，但它还会将数据注入 Managed Service for Prometheus。

   上面的清单仅提供了一个基本的工作示例，不会永久存储任何数据。如需了解此预定义配置的工作原理以及如何扩展该配置，请参阅开源 Prometheus 配置文档。

   预建映像仅适用于 Linux 节点。如需抓取在 Windows 节点上运行的目标，请在 Linux 节点上部署服务器并将其配置为抓取 Windows 节点上的端点，或自行构建 Windows 二进制文件。

2. 验证 Prometheus 服务器和示例应用的 pod 是否已成功部署：

   kubectl -n gmp-test get pod
   

   如果部署成功，您将会看到如下所示的输出：

   NAME                            READY   STATUS    RESTARTS   AGE
   prom-example-84c6f547f5-fglbr   1/1     Running   0          5m
   prom-example-84c6f547f5-jnjp4   1/1     Running   0          5m
   prom-example-84c6f547f5-sqdww   1/1     Running   0          5m
   prometheus-test-0               2/2     Running   1          3m
   

如果您在 GKE 上运行，则可以执行以下操作：

• 如需查询示例应用注入的指标，请参阅从 Prometheus 服务查询数据。
• 如需了解如何将 prometheus-operator 和 kube-prometheus 与自行部署的收集结合使用，以及如何为代管式服务构建和运行二进制文件，请参阅自行部署的收集的其他主题。

如果您在 GKE 之外运行，则需要创建服务帐号并授权其写入指标数据，如以下部分所述。

明确提供凭据

在 GKE 上运行时，收集 Prometheus 服务器会根据 Compute Engine 默认服务帐号或 Workload Identity 设置自动从环境中检索凭据。

在非 GKE Kubernetes 集群中，必须使用标志或 GOOGLE_APPLICATION_CREDENTIALS 环境变量将凭据明确提供给收集 Prometheus 服务器。

1. 创建服务帐号：

   gcloud iam service-accounts create gmp-test-sa
   

   此步骤会创建您可能已在 Workload Identity 说明中创建的服务帐号。

2. 向服务帐号授予所需权限：

   gcloud projects add-iam-policy-binding PROJECT_ID\
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.metricWriter
   

3. 创建并下载服务帐号的密钥：

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

4. 将密钥文件作为 Secret 添加到非 GKE 集群：

   kubectl -n gmp-test create secret generic gmp-test-sa \
     --from-file=key.json=gmp-test-sa-key.json
   

5. 打开 Prometheus StatefulSet 资源进行修改：

   kubectl -n gmp-test edit statefulset prometheus-test
   

6. 将粗体显示的文本添加到资源：

   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     namespace: gmp-test
     name: example
   spec:
     template
       containers:
       - name: prometheus
         args:
         - --export.credentials-file=/gmp/key.json
   ...
         volumeMounts:
         - name: gmp-sa
           mountPath: /gmp
           readOnly: true
   ...
       volumes:
       - name: gmp-sa
         secret:
           secretName: gmp-test-sa
   ...
   

7. 保存该文件并关闭编辑器。应用更改后，系统会重新创建 pod 并使用给定服务帐号向指标后端进行身份验证。

或者，您可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量来设置密钥文件路径，而不是使用本示例中设置的标志。

自行部署的收集的其他主题

本部分介绍了如何执行以下操作：

• 过滤您导出到代管式服务的数据。
• 转换现有部署配置。
• 在高可用性模式下运行 Prometheus 二进制文件。
• 构建并运行替换 Prometheus 二进制文件。
• 在 Google Cloud 外部运行 Managed Service for Prometheus。

过滤导出的指标

如果您收集大量数据，则可能需要防止将一些时序发送到 Managed Service for Prometheus，以降低费用。

您可以在 Prometheus 爬取配置中使用常规的指标重新添加标签配置。利用重新添加标签的配置，您可以在注入时根据标签匹配项丢弃指标。

有时，您可能希望在本地提取数据，但不想将其导出到 Managed Service for Prometheus。如需过滤导出的指标，您可以使用 --export.match 标志。

此标志用于指定一个或多个 PromQL 系列选择器且可以多次使用。如果时序满足至少一个标志中的所有选择器，则会导出到 Managed Service for Prometheus；也就是说，在确定资格时，单个标志中的条件采用 AND 运算，而不同标志中的条件采用 OR 运算。以下示例使用该标志的两个实例：

./prometheus \
  --export.match='{job="prometheus"}' \
  --export.match='{__name__=~"job:.+"}' \
  ...

此更改操作仅导致“prometheus”作业的指标以及由聚合到作业级别的记录规则生成的指标（遵循命名最佳实践时）被导出。所有其他时序的样本都会被过滤掉。默认情况下，不指定选择器，并且导出所有时序。

--export.match 标志与 Prometheus 联合的 match[] 参数具有相同的语义。因此，您可以直接使用联合服务器中的选择器作为联合 Prometheus 服务器爬取的 Prometheus 服务器上的标志，将联合设置迁移到 Managed Service for Prometheus。不支持将指标从联合服务器导出到代管式服务。

您可以将过滤条件标志与在本地运行记录规则相结合，以便在发送到 Monarch 之前“汇总”数据，从而降低基数和费用。如需了解详情，请参阅费用控制和归因。

与 prometheus-operator 结合使用

Managed Service for Prometheus 二进制文件也可以与 prometheus-operator 管理的现有 GKE Prometheus 部署结合使用。

如需使用代管式服务的二进制文件，请替换 Prometheus 资源中的映像规范：

  apiVersion: monitoring.coreos.com/v1
  kind: Prometheus
  metadata:
    name: gmp-test
    namespace: gmp-system
  spec:
    image: gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0
    ...
    replicas: 1
    serviceAccountName: default
    version: v2.35.0
    ...

如果您位于 Workload Identity 集群中，并且资源中的命名空间或服务帐号不同，请对其他命名空间和 Kubernetes 服务帐号对重复按照 Workload Identity 说明执行操作。

在非 GKE Kubernetes 集群上运行时，您需要手动提供凭据。如需提供凭据，请执行以下操作：

1. 添加相应的服务帐号密钥文件作为 Secret，如明确提供凭据中所述。

2. 修改 Prometheus 资源以添加粗体显示的文本：

     apiVersion: monitoring.coreos.com/v1
     kind: Prometheus
     metadata:
       namespace: gmp-test
       name: example
     spec:
       ...
       secrets:
       - gmp-test-sa
       containers:
       - name: prometheus
         env:
         - name: GOOGLE_APPLICATION_CREDENTIALS
           value: /gmp/key.json
         volumeMounts:
         - name: secret-gmp-test-sa
           mountPath: /gmp
           readOnly: true
   

您可以设置容器的 EXTRA_ARGS 环境变量以添加其他标志，例如指标过滤标志。此操作通过环境变量完成，因为容器规范的 args 部分由 Prometheus Operator 管理。

与 kube-prometheus 结合使用

您可以将使用常用的 kube-prometheus 库创建的部署配置为使用 Managed Service for Prometheus。

Kube-prometheus 的默认命名空间和服务帐号具有一些紧密的内部依赖项，因此我们建议您仅更改向 Managed Service for Prometheus 发送数据所需的最少数量的字段。

在 manifests/prometheus-prometheus.yaml 中，替换映像规范并通过将 replicas 减少到 1 来关闭高可用性收集功能：

    apiVersion: monitoring.coreos.com/v1
    kind: Prometheus
    ...
    spec:
      image: gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0
      ...
      replicas: 1
      version: v2.35.0
      ...
  

如果您在 GKE 上运行并且尚未修改节点上的默认服务帐号，则应用修改后的清单应立即开始向 Prometheus 发送托管式服务。否则，您可能需要配置和应用服务帐号。在 GKE 上运行并使用 Workload Identity 时，您可能需要在 monitoring 命名空间中创建并授权 prometheus-k8s 服务帐号。在非 GKE Kubernetes 集群上运行时，请按照 prometheus-operator 部分中的说明操作。

请注意，默认情况下，kube-prometheus 会收集许多指标，而在 GKE 等代管式 Kubernetes 环境中通常不需要其中的大多数指标。为了节省注入费用，您可以自定义 kube-prometheus，使其仅抓取您关注的指标并主动过滤导出的指标。

如需查看更多建议，请参阅费用控制和归因。

高可用性部署

替换的 Prometheus 二进制文件使用领导者选举内置了对高可用性收集的支持。在高可用模式下复制的 Prometheus 服务器会照常收集指标和评估规则，但只有一个服务器将数据发送到 Google Cloud Managed Service for Prometheus。

同一 Prometheus 服务器的副本必须始终具有相同的配置，包括相同的 external_labels。此要求与其他系统不同，其他系统依赖于特殊的外部标签（如 __replica__）来明确区分副本。

Kubernetes API 服务器是受支持的领导者选举后端，可通过设置以下标志来启用：

./prometheus
  ...
  --export.ha.backend=kube \
  --export.ha.kube.namespace=LEASE_NAMESPACE \
  --export.ha.kube.name=LEASE_NAME

LEASE_NAMESPACE 和 LEASE_NAME 值标识发生领导者选举的Lease 资源。指向同一资源的所有 Prometheus 服务器属于同一副本集。Prometheus 部署的 Kubernetes 服务帐号需要相应 Lease 资源的读取和写入权限。在 Kubernetes 集群外部运行 Prometheus 服务器时，您可以使用 --export.ha.kube.config 标志提供显式配置。

二进制文件部署

如果要在非容器化环境中运行，则可以直接构建替换 Prometheus 二进制文件。

构建源代码

如果您有自己编译 Prometheus 的现有流程，则可以透明地将我们的 GitHub 代码库替换到该流程中。Managed Service for Prometheus 有自己的版本标记扩展程序，用于区分其版本与上游版本。

如需构建纯文本二进制文件，必须在机器上安装 Go 工具链和最新版本的 NPM/Yarn。如需了解详情，请参阅上游构建说明。

1. 克隆代码库：

   git clone https://github.com/GoogleCloudPlatform/prometheus &&
   cd prometheus
   

2. 签出所需的版本标记：

   git checkout v2.35.0-gmp.2
   

3. 要创建 Managed Service for Prometheus tar 归档文件，请运行以下命令：

   make build && make tarball
   

生成的 tar 归档文件和二进制文件在目录结构和功能方面与其上游变体完全兼容。

在 Google Cloud 外部运行自行部署的收集

在 Compute Engine 环境、GKE 环境中或在使用充分授权的帐号运行 gcloud login 的机器上，您无需进一步配置即可运行自行部署的收集。在 Google Cloud 外部，您需要明确提供凭据、用于包含指标的 project_id 以及用于存储指标的 location（Google Cloud 区域）。

您可以使用 --export.credentials-file 标志或 GOOGLE_APPLICATION_CREDENTIALS 环境变量来提供服务帐号密钥，如明确提供凭据中所述。

我们建议您根据计划的读取租用模型选择 project_id。根据您以后计划通过指标范围组织读取的方式，选择用于存储指标的项目。如果您不介意，可以将所有内容放到一个项目中。

对于 location，我们建议您选择最靠近您的部署的 Google Cloud 区域。您选择的 Google Cloud 区域距离您的部署越远，写入延迟时间就越长，您受到潜在网络问题的影响就越大。建议您参阅跨多个云环境的区域列表。如果您不在意，则可以将所有内容放入一个 Google Cloud 区域中。 您不能使用 global 作为自己的位置。

如需查看最简单的有效示例，您可以使用以下命令运行本地自监控 Prometheus 二进制文件：

./prometheus \
  --config.file=documentation/examples/prometheus.yaml \
  --export.label.project-id=PROJECT_ID \
  --export.label.location=ZONE \

此示例假定您已将 ZONE 变量设置为 us-central1-b 之类的值。

但是，我们建议您在 Prometheus 配置的 global.external_labels 部分中为代管式服务设置 export 目标标签，例如：

global:
  external_labels:
    project_id: PROJECT_ID
    location: ZONE
    namespace: local-testing

scrape_configs:
  ...

在 Google Cloud 之外运行 Managed Service for Prometheus 会产生数据入站流量费；如果在其他云上运行，可能会产生数据出站流量费。您可以使用 --export.compression=gzip 标志启用压缩功能，以最大限度地降低此费用。

后续步骤

• 查询使用该服务收集的 Prometheus 指标。
• 设置代管式规则评估。
• 设置自部署的规则评估。
• 通过配置局部聚合来降低基数和费用。