公开用于自动扩缩的自定义指标

本文档介绍了如何将 Pod 或工作负载中的一个或多个指标发送到自动扩缩器。

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

然后，工作负载自动调节程序可以使用这些数据更高效地扩缩工作负载。例如，您可以使用此功能来监控队列深度或有效请求，然后允许自动扩缩器增加或减少 Pod 数量。 在 vLLM 示例中，可用于跟踪利用率的指标是 vllm:gpu_cache_usage_perc。

要求

Pod 的要求如下：

  • 使用快速渠道提供的 GKE 1.35.1-gke.1396000 版或更高版本。
  • 将Pod 横向自动扩缩与性能配置文件搭配使用。

指标的要求如下。

  • 指标必须可通过 HTTP 端点访问。端点路径默认为 /metrics。
  • 指标的格式必须符合 Prometheus 标准。
  • 仅支持指标。
  • 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
            prometheusMetricName: METRIC_PROMETHEUS_NAME

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

    • NAME：AutoscalingMetric 对象的名称。
    • NAMESPACE：Pod 所在的命名空间。
    • APP_LABEL_NAME 和 APP_LABEL_VALUE：与发出指标的 Pod 相匹配的标签名称和值。
    • METRIC_PORT：端口号
    • METRIC_PATH：指标的路径。验证您的服务或应用使用的路径；此路径通常为 /metrics。
    • METRIC：您要公开的指标的名称。名称必须与正则表达式 ^[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 文件的名称。

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

  4. 现在，您已将指标公开给自动扩缩器，接下来可以配置工作负载自动扩缩器以使用这些指标。 为此，请添加以下自定义资源：

    apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: NAME_HPA
  namespace: NAMESPACE
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: DEPLOYMENT
  minReplicas: MIN_REPLICAS
  maxReplicas: MAX_REPLICAS
  metrics:
    - type: Pods
      pods:
        metric:
          name: autoscaling.gke.io|NAME|METRIC
        target:
          type: AverageValue
          averageValue: AVERAGE_VALUE

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

    • NAME_HPA：HorizontalPodAutoscaler 对象的名称。
    • NAMESPACE：Pod 所在的命名空间。
    • DEPLOYMENT：您要定位的部署的名称。
    • MIN_REPLICAS：部署可扩缩到的副本数下限。
    • MAX_REPLICAS：部署可扩缩到的副本数上限。
    • NAME：AutoscalingMetric 对象的名称。
    • METRIC：您要公开的指标的名称。
    • AVERAGE_VALUE：相应指标的目标平均值。自动扩缩器会调整副本数量，以使所有 Pod 的平均指标值保持在目标值。

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

    kubectl apply -f FILE_NAME_HPA.yaml

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

使用指标标签过滤指标

在 GKE 1.36.0-gke.1759000 或更高版本中，可以使用指标标签过滤指标。

指标通常包含标签。标签是键值对，可用于为值添加维度。例如，一个按方法和环境细分的 HTTP 端点请求数指标可以使用标签来指定此上下文。此示例可能如下所示：

http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222

您可以使用标签过滤条件来确保指标规范与某个指标完全匹配。例如，如需仅选择上例中的第一个指标，请为 AutoscalingMetric gauge 指标使用以下规范：

apiVersion: autoscaling.gke.io/v1beta1
kind: AutoscalingMetric
metadata:
  name: filter-sample
spec:
  # Several lines are omitted here.
      metrics:
      - gauge:
          name: http_requests_total
          filter:
            matchLabels:
              method: GET
              env: prod

matchLabels 键值对的键必须与正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]* 匹配：也就是说，以字母或下划线开头，并且仅包含字母、数字或下划线。

排查为自动扩缩公开的指标

您可以查看 AutoscalingMetric 自定义资源的状态，以查找配置错误。为此，请执行以下操作：

  1. 运行以下命令，检查 AutoscalingMetric 自定义资源：

    kubectl describe autoscalingmetric NAME -n NAMESPACE

  2. 查看 Status 字段，了解有关已配置指标的信息，例如有关配置错误的警告，以及指标应在 HorizontalPodAutoscaler 对象中显示的准确名称。

后续步骤