自部署收集使用入门

预览版

本产品或功能受《Google Cloud Platform 服务条款》的正式发布前产品条款约束。对正式发布前产品和功能的支持可能有限，并且对正式发布前产品和功能的变更可能不兼容其他正式发布前版本。 如需了解详情，请参阅发布阶段说明。

本文档介绍了如何使用自部署收集为 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.28.1-gmp.2-gke.0，而不是上游 Prometheus 二进制文件。

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

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

准备工作

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

设置项目和工具

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

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

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

    1. 在 Cloud Console 中，转到新建项目：

       创建新项目

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

    3. 转到结算：

       转到“结算”

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

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

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

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

    1. 转到 API 和服务：

       转到 API 和服务

    2. 选择您的项目。

    3. 点击启用 API 和服务。

    4. 搜索“Monitoring”。

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

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

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

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

• gcloud
• kubectl

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

gcloud components list

配置您的环境

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

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

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

    gcloud config set project PROJECT_ID
    

  • 配置 kubectl 工具以使用集群：

    kubectl config set-cluster CLUSTER_NAME
    

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

  • gcloud 工具概览
  • kubectl 命令

设置命名空间

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

kubectl create ns gmp-test

为 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.1.1/examples/example-app.yaml

运行替换的 Prometheus 二进制文件

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

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

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

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

   请注意，上面的清单仅提供了一个基本的工作示例，不会永久存储任何数据。如需了解此预定义配置的工作原理以及如何扩展该配置，请参阅开源 Prometheus 配置文档。请注意，在将数据注入代管式存储时，不支持运行高可用性 Prometheus 对。

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 二进制文件。

过滤导出的指标

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

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

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

此标志指定 PromQL 系列选择器，并且可以多次使用。如果时序满足至少一个选择器，则会导出到 Managed Service for Prometheus。以下示例使用该标志的两个实例：

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

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

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

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

与 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.28.1-gmp.2-gke.0
    ...
    replicas: 1
    serviceAccountName: default
    version: v2.28.1
    ...

如果您位于 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
   

您还可以替换容器的 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.28.1-gmp.2-gke.0
      ...
      replicas: 1
      version: v2.28.1
      ...
  

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

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

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

二进制文件部署

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

构建源代码

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

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

1. 克隆代码库：

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

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

   git checkout v2.28.1-gmp.2
   

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

   make build && make tarball
   

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

运行二进制文件

在 Compute Engine 环境中或在使用足够授权的帐号运行 gcloud login 的机器上，您无需进一步配置即可运行二进制文件。服务器会将爬取的指标发送到 Monarch。

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

如需查看最小示例，您可以使用以下命令运行本地自监控 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:
  ...

后续步骤

• 查询使用该服务收集的 Prometheus 指标。
• 设置代管式规则评估。
• 设置自部署的规则评估。