自部署收集使用入门

本文档介绍了如何使用自部署收集为 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.41.0-gmp.9-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 项目。
- 如果您没有 Google Cloud 项目，请执行以下操作：
  1. 在 Google Cloud 控制台中，转到新建项目：
    
    创建新项目
  2. 在项目名称字段中，为您的项目输入一个名称，然后点击创建。
  3. 转到结算：
    
    转到“结算”
  4. 在页面顶部选择您刚刚创建的项目（如果尚未选择）。
  5. 系统会提示您选择现有付款资料或创建新的付款资料。
  默认情况下，新项目会启用 Monitoring API。
- 如果您已有 Google 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 以引用您的 Google Cloud 项目的 ID：
```
gcloud config set project PROJECT_ID
```
- 配置 kubectl CLI 以使用集群：
```
kubectl config set-cluster CLUSTER_NAME
```
如需详细了解这些工具，请参阅以下内容：
- gcloud CLI 概览
- kubectl 命令

设置命名空间

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

kubectl create ns NAMESPACE_NAME

验证服务账号凭据

如果您的 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 服务账号绑定到测试命名空间 NAMESPACE_NAME 中的默认 Kubernetes 服务账号。
为 Google Cloud 服务账号授予必要的权限。

创建和绑定服务账号

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

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

gcloud config set project PROJECT_ID \
&&
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[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  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 配置

如果您在使 Workload Identity 正常工作时遇到问题，请参阅验证 Workload Identity 设置的文档和 Workload Identity 故障排除指南。

由于拼写错误和部分复制粘贴是配置 Workload Identity 时最常见的错误来源，因此我们强烈建议使用这些说明中代码示例中嵌入的可编辑变量和可点击复制粘贴图标。

生产环境中的 Workload Identity

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

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

设置自部署收集

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

部署示例应用

示例应用在其 metrics 端口上发出 example_requests_total 计数器指标和 example_random_numbers 直方图指标（以及其他指标）。应用的清单定义了三个副本。

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

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/example-app.yaml

运行替换的 Prometheus 二进制文件

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

如需部署分支服务器，请运行以下命令：
```
kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/prometheus.yaml
```
此已部署的 Prometheus 服务器是上游 Prometheus 二进制文件的瘦分支。其行为类似于标准 Prometheus 服务器，但它还会将数据注入 Managed Service for Prometheus。

上面的清单提供了一个基本的有效示例，它将数据发送到全局数据存储区 Monarch。它不会永久存储数据的本地副本。如需了解此预定义配置的工作原理以及如何扩展该配置，请参阅开源 Prometheus 配置文档。

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

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

kubectl -n NAMESPACE_NAME 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 上运行，则可以执行以下操作：

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

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

明确提供凭据

在 GKE 上运行时，收集 Prometheus 服务器会根据节点的服务账号或 Workload Identity 设置自动从环境中检索凭据。在非 GKE Kubernetes 集群中，必须使用标志或 GOOGLE_APPLICATION_CREDENTIALS 环境变量将凭据明确提供给收集 Prometheus 服务器。

将上下文设置为目标项目：
```
gcloud config set project PROJECT_ID
```
创建服务账号：
```
gcloud iam service-accounts create gmp-test-sa
```
此步骤会创建您可能已在 Workload Identity 说明中创建的服务账号。

向服务账号授予所需权限：

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

创建并下载服务账号的密钥：

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

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

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

打开 Prometheus StatefulSet 资源进行修改：
```
kubectl -n NAMESPACE_NAME edit statefulset prometheus-test
```
1. 将粗体显示的文本添加到资源：
```
apiVersion: apps/v1
kind: StatefulSet
metadata:
  namespace: NAMESPACE_NAME
  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
...
```
2. 保存该文件并关闭编辑器。应用更改后，系统会重新创建 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。不支持将指标从联合服务器导出到代管式服务。

如需在过滤条件中包含 histogram 类型的指标，您必须指定 _count、_sum 和 _bucket 指标。您还可以使用通配符匹配器（例如选择器 {__name__=~"histogram_metric_.+"}）来执行此操作。

如果您使用的是 prometheus-operator 库，请使用容器的 EXTRA_ARGS 环境变量设置任何 --export.match 标志。如需了解详情，请参阅与 prometheus-operator 结合使用。

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

Cloud Monitoring 指标管理页面提供的信息可帮助您控制在收费指标上支出的金额，而不会影响可观测性。指标管理页面报告以下信息：
- 针对指标网域中基于字节和基于样本的结算以及各个指标的注入量。
- 有关指标的标签和基数的数据。
- 指标在提醒政策和自定义信息中心内的使用。
- 指标写入错误率。
如需详细了解指标管理页面，请参阅查看和管理指标使用情况。

与 prometheus-operator 结合使用

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

如需使用代管式服务的二进制文件，请替换 Prometheus 资源中的映像规范：
```
  apiVersion: monitoring.coreos.com/v1
  kind: Prometheus
  metadata:
    name: NAMESPACE_NAME
    namespace: gmp-system
  spec:
    image: gke.gcr.io/prometheus-engine/prometheus:v2.41.0-gmp.9-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.41.0-gmp.9-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 标志提供显式配置。

完成此操作后，您可以将 replicas 值增加到 2 或更大的值。

二进制文件部署

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

构建源代码

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

如需构建纯文本二进制文件，必须在机器上安装 Go 工具链和最新版本的 NPM/Yarn。如需了解详情，请参阅上游构建说明。
1. 克隆代码库：
```
git clone https://github.com/GoogleCloudPlatform/prometheus &&
cd prometheus
```
2. 签出所需的版本标记：
```
git checkout v2.41.0-gmp.9
```
3. 要创建 Managed Service for Prometheus tar 归档文件，请运行以下命令：
```
make build && make tarball
```
生成的 tar 归档文件和二进制文件在目录结构和功能方面与其上游变体完全兼容。

创建和更新指标和标签的限制

Managed Service for Prometheus 会对创建新指标和向现有指标添加新指标标签实施每分钟速率限制。此速率限制通常仅在首次与 Managed Service for Prometheus 集成时才会达到，例如，迁移现有的成熟 Prometheus 部署以使用自部署收集。这不是注入数据点的速率限制。此速率限制仅在创建从未见过的指标或向现有指标添加新标签时适用。

此配额是固定的，但在新指标和指标标签的创建达到每分钟限制时，任何问题都会自动解决。

如需了解详情，请参阅问题排查。

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

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

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

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

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

如果在 Kubernetes 环境中运行，请将 cluster 和 namespace 值设置为本地集群和命名空间。如果是在 Kubernetes 外部运行，请将它们设置为在层次结构上有意义的值。例如，在 AWS 上运行的基于虚拟机的环境中，将 cluster 值设置为 __aws__，并将 namespace 值设置为实例 ID。您可以使用调用本地元数据服务器的重新添加标签规则来动态填充实例 ID。

如需查看最简单的有效示例，您可以使用以下命令运行本地自监控 Prometheus 二进制文件：
```
./prometheus \
  --config.file=documentation/examples/prometheus.yaml \
  --export.label.project-id=PROJECT_ID \
  --export.label.location=REGION \
  --export.label.cluster=CLUSTER_NAME \
```
此示例假定您已将 REGION 变量设置为 us-central1 之类的值。

但是，我们建议您在 Prometheus 配置的 global.external_labels 部分中为代管式服务设置 export 目标标签。例如，在 Kubernetes 环境中，您可以使用以下配置：
```
global:
  external_labels:
    project_id: PROJECT_ID
    location: REGION
    cluster: CLUSTER_NAME
    namespace: local-testing

scrape_configs:
  ...
```
在 Google Cloud 之外运行 Managed Service for Prometheus 会产生数据转移费用。将数据转移到 Google Cloud 会产生费用，并且从其他云转移数据可能会产生费用。您可以使用 --export.compression=gzip 标志启用压缩功能，以最大限度地降低此费用。

后续步骤
- 使用 Cloud Monitoring 中的 PromQL 查询 Prometheus 指标。
- 使用 Grafana 查询 Prometheus 指标。
- 使用 Cloud Monitoring 中的 PromQL 提醒。
- 设置代管式规则评估。
- 设置自部署的规则评估。
- 通过配置局部聚合来降低基数和费用。

自部署收集使用入门

准备工作

设置项目和工具

配置您的环境

设置命名空间

验证服务账号凭据

为 Workload Identity 配置服务账号

创建和绑定服务账号

向服务账号授权

调试 Workload Identity 配置

生产环境中的 Workload Identity

设置自部署收集

部署示例应用

运行替换的 Prometheus 二进制文件

明确提供凭据

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

过滤导出的指标

与 prometheus-operator 结合使用

与 kube-prometheus 结合使用

高可用性部署

二进制文件部署

构建源代码

创建和更新指标和标签的限制

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

后续步骤