使用自定义指标或外部指标自动扩缩 Pod

本文档介绍了如何获取和使用自定义指标和外部指标来横向扩缩 Pod。

如需提取指标，您可以使用受管理的指标适配器。此托管式解决方案适用于 Cloud Monitoring 中可使用 PromQL 查询的指标，以及所有自定义指标。自定义指标是指以 Prometheus 格式通过 HTTP 端点公开的 Pod 指标。

或者，如需使用任何指标进行自动扩缩，您可以手动配置指标适配器以将指标发送到自动扩缩器，从而获取该指标。此工作流程涉及安装第三方适配器（例如自定义指标适配器）和配置权限。例如，请参阅根据指标优化 Pod 自动扩缩教程。

提取指标

您可以通过以下方式提取指标：

• 在集群内可以提取由 Pod 发出的自定义指标。这些指标可用于自动扩缩，而无需通过 Cloud Monitoring 等监控系统进行传输。
• 可以使用 PromQL 查询提取存储在 Cloud Monitoring 中的 Pod 指标。这些指标由 Pod 发出，并导出到 Cloud Monitoring，通常使用 Google Cloud Managed Service for Prometheus。 与之前的方法相比，此方法可让您使用 PromQL 功能，例如计算百分位数或读取历史值。
• 可以使用 PromQL 查询从 Cloud Monitoring 中提取外部指标。
• 通过手动配置指标适配器以将指标发送到自动扩缩器，可以提取指标。此工作流程涉及安装第三方工具和配置权限。例如，请参阅根据指标优化 Pod 自动扩缩教程。

提取指标后，您可以在 HorizontalPodAutoscaler 对象中引用该指标。如需了解详情，请参阅在 Pod 横向自动扩缩器中使用指标部分。

如需大致了解如何根据指标进行自动扩缩，请参阅关于根据指标自动扩缩工作负载。

提取集群中的自定义指标

自定义指标来自您运行的服务或应用。如需查看公开指标的一个示例，请参阅 vLLM Engine 公开的指标。

要求

Pod 的要求如下：

• GKE 1.35.1-gke.1396000 或更高版本，且集群位于快速渠道中。
• 将Pod 横向自动扩缩与性能配置文件搭配使用。

指标的要求如下：

• 指标必须可通过 HTTP 端点访问。端点路径默认为 /metrics。
• 指标的格式必须符合 Prometheus 标准。
• 仅支持 Gauge 指标。
• Pod 标签选择器中的标签名称不得包含特殊字符。仅支持 a-z 字母（小写或大写）、数字、连字符和下划线。
• 当您使用基于指标标签的过滤时，标签键必须与正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]* 相匹配（以字母或下划线开头，并且只能包含字母、数字或下划线）。
• 每个集群最多可公开 20 个唯一指标。

定义指标

1. 选择要公开的指标。您可以选择工作负载公开的任何指标，前提是该指标还需满足上一部分中列出的要求。

   如果您的工作负载公开了多个名称相同但标签不同的指标，请添加标签过滤条件，以确保仅选择一个指标。

2. 添加以下自定义资源，替换特定于您的指标和 Pod 的详细信息：

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
     - pod:
         selector:
           matchLabels:
             APP_LABEL_NAME: APP_LABEL_VALUE
         containers:
         - endpoint:
             port: METRIC_PORT
             path: METRIC_PATH
           metrics:
           - gauge:
               name: METRIC_NAME
               prometheusMetricName: METRIC_PROMETHEUS_NAME
   

   替换以下内容以与您的工作负载相符：

   • NAME：AutoscalingMetric 对象的名称。
   • NAMESPACE：Pod 所在的命名空间。
   • APP_LABEL_NAME 和 APP_LABEL_VALUE：与发出指标的 Pod 相匹配的标签名称和值。
   • METRIC_PORT：端口号
   • METRIC_PATH：指标的路径。验证您的服务或应用使用的路径；此路径通常为 /metrics。
   • METRIC_NAME：您要公开的指标的名称。名称必须与正则表达式 ^[a-z]([-a-z0-9]*[a-z0-9])? 匹配，且长度不得超过 63 个字符。此表达式表示第一个字符必须是小写字母，且所有后续字符必须是连字符、小写字母或数字。不过，最后一个字符不能是连字符。

   • 可选：METRIC_PROMETHEUS_NAME：Pod 公开的 Prometheus 指标名称。您可以使用此字段重命名指标，例如，因为 Pod 公开的指标名称不符合自动扩缩器设置的名称限制。

     如需详细了解名称限制，请参阅 Pod 横向自动扩缩的限制。

3. 使用以下命令应用清单：

   kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml
   

   将 FILE_NAME_AUTOSCALING_METRIC 替换为 YAML 文件的名称。

4. 验证指标定义并检索要用于 HorizontalPodAutoscaler 对象的指标名称：

   1. 针对 AutoscalingMetric 自定义资源运行 kubectl describe 命令：

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      替换以下内容：

      • NAME：AutoscalingMetric 对象的名称。
      • NAMESPACE：AutoscalingMetric 对象的命名空间。

   2. 查看 Status 字段。如果未列出任何错误，则表示该对象有效。

   3. 复制 HPA Name 字段中的名称。这是您添加到 HorizontalPodAutoscaler 对象的名称。此名称的格式如下： autoscaling.gke.io|NAME|METRIC_NAME。

该指标现在在 AutoscalingMetric 对象中定义。如需使用此指标进行自动扩缩，您需要在 HorizontalPodAutoscaler 对象中引用它。如需了解详情，请参阅使用 HorizontalPodAutoscaler 对象中的指标部分。

添加自定义资源后，指标会推送到自动扩缩 API。系统每隔几秒读取一次该指标，并将其发送到工作负载自动扩缩器。

从 Cloud Monitoring 中提取自定义指标或外部指标

您可以从 Cloud Monitoring 中提取指标，以扩缩工作负载。GKE 支持从 Cloud Monitoring 中提取两种类型的指标：

• 自定义指标：使用此类型可将 PromQL 功能（例如计算百分位数或读取历史值）应用于集群工作负载发出的指标。
• 外部指标：使用此类型可根据集群外部的实体（例如 Pub/Sub 订阅中的待处理消息数量）进行扩缩。

否则，从集群中提取自定义指标。

要求

• GKE 1.36.2-gke.2771000 版或更高版本。
• 指标必须存储在 Cloud Monitoring 中。例如，您可以使用 Google Cloud Managed Service for Prometheus。
• 每个集群最多支持 100 个指标。此限制是自定义指标和外部指标的总和。
• Cloud Monitoring 中的指标必须与正在自动扩缩的集群位于同一 Cloud de Confiance by S3NS 项目 中。

定义指标

您可以使用 YAML 文件来定义指标，包括具体的 PromQL 查询。

根据您要提取的是自定义指标还是外部指标，选择以下配置之一：

1. 创建 AutoscalingMetric 对象并定义要提取的指标。

   自定义指标 (Pod)

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: Pods # Specifies that the metric is associated with Pods.
           # metricLabels are optional, default to the labels used by Google
           # Cloud Managed Service for Prometheus. The defaults are used
           # below.
           metricLabels:
             podName: "pod"
             namespace: "namespace"
             clusterName: "cluster"
             location: "location"
             projectId: "project_id"
   

   替换以下内容：

   • NAME：AutoscalingMetric 对象的名称。
   • NAMESPACE：AutoscalingMetric 对象的命名空间，必须与您要扩缩的工作负载的命名空间一致。
   • METRIC_NAME：HorizontalPodAutoscaler 对象使用的指标的名称。
   • PROMQL_QUERY：用于查询相应指标的 PromQL 查询。PromQL 查询必须返回一个向量，其中包含自动扩缩资源中每个 Pod 的一个条目，例如，Deployment 中每个 Pod 的一个条目。

   您可以在单个 AutoscalingMetric 清单中定义多个指标，只需向 metrics 数组添加额外的 promql 条目即可。

   在此清单中，适用以下规则：

   • type: Pods 字段表示指标由 Pod 发出。

   • 可选：metricLabels 字段是 PromQL 查询结果中列出资源详细信息（例如 Pod 名称、命名空间或集群信息）的标签名称。Pod 发出的自定义指标必须包含与 podName 字段匹配的标签，以指定指标与哪个 Pod 相关联。当您使用 Google Cloud Managed Service for Prometheus 将指标发送到 Cloud Monitoring 时，系统会自动配置此标签。

     如果未在 AutoscalingMetric 对象中指定这些字段，则使用以下默认值在标签中查找信息。这些默认值与 Google Cloud Managed Service for Prometheus 配置的标签名称相同：

     • podName: "pod"
     • namespace: "namespace"
     • clusterName: "cluster"
     • location: "location"
     • projectId: "project_id"

   外部指标

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: External  # Optional, default is 'External'
   

   替换以下内容：

   • NAME：AutoscalingMetric 对象的名称。
   • NAMESPACE：AutoscalingMetric 对象的命名空间，必须与您要扩缩的工作负载的命名空间一致。
   • METRIC_NAME：HPA 使用的指标的名称。
   • PROMQL_QUERY：用于查询指标的 PromQL 查询。PromQL 查询必须返回标量值或具有唯一条目的矢量。

2. 验证 Cloud Monitoring 中的 PromQL 查询，确保它们返回预期的指标。在设置查询时验证查询，比日后排查意外行为要容易得多。

   如需验证查询，请参阅以下部分：验证 PromQL 查询。

3. 将 AutoscalingMetric 清单应用于集群：

   kubectl apply -f MANIFEST_FILE.yaml
   

   将 MANIFEST_FILE 替换为相应 YAML 文件的名称。

4. 验证指标定义并检索要用于 HorizontalPodAutoscaler 对象的指标名称：

   1. 针对 AutoscalingMetric 自定义资源运行 kubectl describe 命令：

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      替换以下内容：

      • NAME：AutoscalingMetric 对象的名称。
      • NAMESPACE：AutoscalingMetric 对象的命名空间。

   2. 查看 Status 字段。如果未列出任何错误，则表示该对象有效。

   3. 复制 HPA Name 字段中的名称。这是您添加到 HorizontalPodAutoscaler 对象的名称。此名称的格式如下： autoscaling.gke.io|NAME|METRIC_NAME。

该指标现在在 AutoscalingMetric 对象中定义。如需使用此指标进行自动扩缩，您需要在 HorizontalPodAutoscaler 对象中引用它。如需了解详情，请参阅使用 HorizontalPodAutoscaler 对象中的指标部分。

使用 HorizontalPodAutoscaler 对象中的指标

1. 创建 HorizontalPodAutoscaler 对象。HorizontalPodAutoscaler 指标类型必须与 AutoscalingMetric 自定义资源中定义的 type 字段的值一致。根据您的指标类型，选择以下配置之一：

   方法 1：外部指标

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: External
         external:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue
             averageValue: AVERAGE_VALUE
   

   选项 2：Pod 指标

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: Pods
         pods:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue  # This is the only supported target type
             averageValue: AVERAGE_VALUE
   

   替换以下内容：

   • HPA_NAME：HorizontalPodAutoscaler 对象的名称。
   • NAMESPACE：HorizontalPodAutoscaler 对象的命名空间，必须与工作负载和 AutoscalingMetric 资源的命名空间一致。
   • DEPLOYMENT_NAME：您要扩缩的工作负载部署的名称。
   • MIN_REPLICAS：正在运行的 Pod 的数量下限。
   • MAX_REPLICAS：正在运行的 Pod 的数量上限。
   • NAME：您创建的 AutoscalingMetric 自定义资源的名称。
   • METRIC_NAME：AutoscalingMetric 资源中定义的指标的名称。
   • AVERAGE_VALUE：自动扩缩器扩缩工作负载的目标指标值。

   创建自己的 HorizontalPodAutoscaler 对象时，请注意以下事项：

   • AutoscalingMetric、Deployment 和 HorizontalPodAutoscaler 对象必须位于同一命名空间中。
   • 上述示例使用了 type: AverageValue 字段值对。请注意，外部指标也支持 type: Value。
   • 上述示例仅使用 Deployment 对象作为示例。您还可以自动扩缩 HorizontalPodAutoscaler 对象支持的任何对象，例如 ReplicaSet 对象。

2. 应用 HorizontalPodAutoscaler 清单：

   kubectl apply -f HPA_MANIFEST_FILE.yaml
   

   将 HPA_MANIFEST_FILE 替换为相应 YAML 文件的名称。

排查为自动扩缩提取的指标

如需排查提取指标方面的问题，您可以查看日志或 AutoscalingMetric 自定义资源的状态。

自动扩缩指标适配器的副本数为零

在 kube-system 中检查 autoscaling-metrics-adapter 部署时，您可能会注意到它有零个副本。

默认情况下，适配器以零个副本运行，以节省集群资源。这是预期行为。当集群中存在需要 PromQL 处理的 AutoscalingMetric 自定义资源时，部署只会扩缩到 1 个副本。

如果您使用 PromQL 查询配置了 AutoscalingMetric 对象，但适配器尚未扩缩，请验证该对象是否已在集群中成功创建。

查看日志

如需查找负责从 Cloud Monitoring 获取指标的控制器的问题，您可以查看其日志。

您可以在 Cloud de Confiance 控制台中查看日志：

1. 前往Logs Explorer页面：

   转到日志浏览器

2. 在查询窗格中，输入以下查询：

   resource.type="k8s_container"
   resource.labels.namespace_name="kube-system"
   resource.labels.container_name="autoscaling-metrics-adapter"
   

或者，如需使用 kubectl 查看日志，请运行以下命令：

kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system

查看 AutoscalingMetric 状态

您可以查看 AutoscalingMetric 自定义资源的状态，以查找配置错误。

1. 检查 AutoscalingMetric 自定义资源：

   kubectl describe autoscalingmetric NAME -n NAMESPACE
   

   替换以下内容：

   • NAME：您创建的 AutoscalingMetric 自定义资源的名称。
   • NAMESPACE：自定义资源的命名空间。

2. 如需详细了解配置的指标，请查看 Status 字段。这些详细信息包括有关配置错误的任何警告，以及指标在 HorizontalPodAutoscaler 对象中应显示的准确名称。

   以下是有效状态的示例：

   Name:         sample-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:41:58Z
     Generation:          1
     Resource Version:    1786372918604351020
     UID:                 c3f012a9-8f25-4399-ac91-12ae8f4426d7
   Spec:
     Metrics:
       Promql:
         Name:   pubsub_unacked
         Query:  sum(pubsub_subscription_num_undelivered_messages)
         Type:   External
   Status:
     Metric Statuses:
       Hpa Name:  autoscaling.gke.io|sample-metric|pubsub_unacked
       Name:      pubsub_unacked
   Events:        <none>
   

   以下是包含配置错误的状态的示例：

   Name:         bad-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:42:40Z
     Generation:          1
     Resource Version:    1786372960414079010
     UID:                 a47d3ed4-f6f2-4c2c-9341-0de4e9752c3c
   Spec:
     Metrics:
       Promql:
         Name:   duplicate_metric
         Query:  sum(up)
         Type:   External
       Promql:
         Name:   duplicate_metric
         Query:  avg(up)
         Type:   External
   Status:
     Metric Statuses:
       Errors:
         Multiple metrics defined with the same name.
       Name:  duplicate_metric
   Events:    <none>
   

验证 PromQL 查询

如果您使用 PromQL 查询从 Cloud Monitoring 中提取指标，那么查询出现问题可能会导致无法检索指标，或者检索到意外的值。例如，如果您预期返回的百分比值介于 1 到 100 之间，但实际收到的值介于 0 到 1 之间，则自动扩缩功能会以意想不到的方式运行。

您可以在 Cloud Monitoring 中测试 PromQL 查询，以验证它们是否返回了预期指标。

如需验证查询，请执行以下操作：

1. 在 Cloud de Confiance 控制台中，前往 Metrics Explorer 页面。

   转到 Metrics Explorer

2. 在查询构建器窗格顶部，选择 PromQL 标签页。

3. 在查询编辑器中，输入要测试的 PromQL 查询。

4. 点击运行查询以查看图表中的指标。

后续步骤

• 如需大致了解如何根据指标进行自动扩缩，请参阅关于根据指标自动扩缩工作负载。
• 如需使用无法通过 PromQL 查询定义的指标进行自动扩缩，请参阅根据指标优化 Pod 自动扩缩。