Ce document explique comment extraire et utiliser des métriques personnalisées et externes pour effectuer un scaling horizontal des pods.
Pour récupérer les métriques, vous pouvez utiliser un adaptateur de métriques géré par GKE. Cette solution gérée est disponible à la fois pour les métriques Cloud Monitoring pouvant être interrogées avec PromQL et pour certaines métriques de pod personnalisées exposées sous un point de terminaison HTTP au format Prometheus.
L'autoscaler de charge de travail peut ensuite utiliser ces données pour mettre à l'échelle les charges de travail de manière plus efficace. Par exemple, vous pouvez utiliser cette fonctionnalité pour surveiller la profondeur de la file d'attente ou l'utilisation du cache, puis autoriser l'autoscaler à augmenter ou diminuer le nombre de pods. Dans l'exemple vLLM, vllm:gpu_cache_usage_perc est une métrique qui peut être utile pour suivre l'utilisation du cache.
Au lieu d'utiliser l'adaptateur de métriques gérées, vous pouvez récupérer la métrique en configurant manuellement un adaptateur de métriques pour envoyer des métriques à un autoscaler. Ce workflow implique l'installation d'un adaptateur tiers, tel que l'adaptateur Stackdriver, et la configuration des autorisations. Par exemple, consultez le tutoriel Optimiser l'autoscaling des pods en fonction des métriques.
Le reste de ce document se concentre sur l'adaptateur de métriques gérées.
Récupérer les métriques
Vous pouvez récupérer des métriques à l'aide de l'adaptateur de métriques gérées de différentes manières :
- Les métriques de pod personnalisées émises par les pods peuvent être récupérées dans le cluster. Ces métriques peuvent être utilisées pour l'autoscaling sans avoir à transiter par un système de surveillance tel que Cloud Monitoring.
- Les métriques de pod personnalisées stockées dans Cloud Monitoring peuvent être récupérées à l'aide d'une requête PromQL. Ces métriques sont émises par les pods et exportées vers Cloud Monitoring, généralement à l'aide de Google Cloud Managed Service pour Prometheus. Par rapport à la méthode précédente, cette approche vous permet d'utiliser des fonctionnalités PromQL telles que le calcul des centiles ou la lecture des valeurs historiques.
- Les métriques externes peuvent être extraites de Cloud Monitoring à l'aide d'une requête PromQL.
Une fois la métrique récupérée, vous la référencez dans un objet HorizontalPodAutoscaler. Pour en savoir plus, consultez la section Utiliser les métriques dans l'autoscaler horizontal de pods.
Pour obtenir une présentation de l'autoscaling basé sur les métriques, consultez À propos de l'autoscaling des charges de travail en fonction des métriques.
Récupérer des métriques personnalisées dans le cluster
Les métriques personnalisées proviennent du service ou de l'application que vous exécutez. Pour obtenir un exemple de métriques exposées, consultez les métriques exposées par le moteur vLLM.
Conditions requises
Voici les exigences concernant les pods :
- GKE 1.37.0-gke.3100000 et versions ultérieures. Cette fonctionnalité est également disponible en preview pour les versions 1.36.4-gke.1247000 et ultérieures de GKE.
- Utilisez l'autoscaling horizontal des pods avec le profil de performances.
Voici les exigences concernant les métriques :
- Les métriques doivent être émises par les pods de la charge de travail mise à l'échelle automatiquement.
- Les métriques doivent être accessibles sur un point de terminaison HTTP. Le chemin du point de terminaison est
/metricspar défaut. - Les métriques doivent être mises en forme conformément à la norme Prometheus.
- Seules les métriques de jauge sont acceptées.
- Par défaut, un maximum de 50 métriques uniques peuvent être exposées par nœud. Si vous devez exposer plus de métriques, vous pouvez demander une quantité de mémoire supplémentaire plus importante.
- Si vous utilisez la version preview de cette fonctionnalité, dans GKE version 1.36.4-gke.1247000 à version 1.37.0-gke.3100000, les exigences supplémentaires suivantes s'appliquent :
- Les noms de libellés dans les sélecteurs de libellés de pod ne doivent pas contenir de caractères spéciaux. Seuls les lettres de a à z (minuscules ou majuscules), les chiffres, les traits d'union et les traits de soulignement sont acceptés.
- Lorsque vous utilisez le filtrage basé sur les étiquettes de métriques, la clé d'étiquette doit correspondre à l'expression régulière
^[a-zA-Z_][a-zA-Z0-9_]*(commencer par une lettre ou un trait de soulignement, et ne contenir que des lettres, des chiffres ou des traits de soulignement). - Vous pouvez exposer jusqu'à 20 métriques uniques par cluster.
Définir la métrique
Choisissez une métrique à exposer. Vous pouvez choisir n'importe quelle métrique exposée par votre charge de travail et qui répond également aux exigences listées dans la section précédente.
Si votre charge de travail expose plusieurs métriques portant le même nom, mais avec des libellés différents, ajoutez un filtre de libellé pour vous assurer qu'une seule est sélectionnée.
Ajoutez la ressource personnalisée suivante, en remplaçant les détails spécifiques à votre métrique et à votre 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_NAMERemplacez les éléments suivants pour qu'ils correspondent à votre charge de travail :
NAME: nom de l'objet AutoscalingMetric.NAMESPACE: espace de noms dans lequel se trouvent les pods.APP_LABEL_NAMEetAPP_LABEL_VALUE: nom et valeur du libellé correspondant aux pods qui émettent la métrique.METRIC_PORT: numéro de port.METRIC_PATH: chemin d'accès à la métrique. Vérifiez le chemin d'accès utilisé par votre service ou application. Il s'agit souvent de/metrics.METRIC_NAME: nom de la métrique que vous exposez. Le nom doit correspondre à l'expression régulière^[a-z]([-a-z0-9]*[a-z0-9])?et ne pas dépasser 63 caractères. Cette expression signifie que le premier caractère doit être une lettre minuscule, et tous les caractères suivants doivent être des tirets, des lettres minuscules ou des chiffres. Toutefois, le dernier caractère ne peut pas être un tiret.Facultatif :
METRIC_PROMETHEUS_NAME: nom de la métrique Prometheus telle qu'exposée par le pod. Vous pouvez utiliser ce champ pour renommer la métrique, par exemple parce que le nom de la métrique exposée par le pod ne respecte pas les restrictions de nom définies par l'autoscaler.Pour en savoir plus sur les restrictions concernant les noms, consultez les limites de l'autoscaling horizontal de pods. Vous pouvez également filtrer les métriques à l'aide de libellés de métriques.
Appliquez le fichier manifeste à l'aide de la commande suivante :
kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yamlRemplacez
FILE_NAME_AUTOSCALING_METRICpar le nom du fichier YAML.Vérifiez la définition de la métrique et récupérez le nom de la métrique à utiliser pour l'objet HorizontalPodAutoscaler :
Exécutez la commande
kubectl describepour la ressource personnalisée AutoscalingMetric :kubectl describe autoscalingmetric NAME -n NAMESPACERemplacez les éléments suivants :
NAME: nom de l'objet AutoscalingMetric.NAMESPACE: espace de noms de l'objet AutoscalingMetric.
Examinez le champ
Status. Si aucune erreur n'est listée, l'objet est valide.Copiez le nom dans le champ
HPA Name. Il s'agit du nom que vous ajoutez à l'objet HorizontalPodAutoscaler. Ce nom a le format suivant :autoscaling.gke.io|NAME|METRIC_NAME.
La métrique est désormais définie dans l'objet AutoscalingMetric. Pour effectuer l'autoscaling avec cette métrique, vous devez la référencer dans un objet HorizontalPodAutoscaler. Pour en savoir plus, consultez la section Utiliser les métriques dans l'objet HorizontalPodAutoscaler.
Lorsque vous ajoutez la ressource personnalisée, la métrique est envoyée à l'API Autoscaling. La métrique est lue toutes les quelques secondes et envoyée à l'autoscaler de charge de travail.
Filtrer les métriques à l'aide d'étiquettes de métrique
Le filtrage des métriques à l'aide de libellés de métriques est disponible sur GKE 1.36.0-gke.1759000 ou version ultérieure.
Les métriques émises par vos charges de travail incluent souvent des libellés. Les libellés sont des paires clé/valeur qui vous permettent d'ajouter des dimensions à une valeur. Par exemple, une métrique comptabilisant le nombre de requêtes envoyées à un point de terminaison HTTP, segmentées par méthode et environnement, peut utiliser des libellés pour spécifier ce contexte. Voici un exemple :
http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222
Vous pouvez utiliser des filtres de libellés pour vous assurer que votre spécification de métrique correspond exactement à une métrique. Par exemple, pour ne sélectionner que la première métrique de l'exemple précédent, utilisez la spécification suivante pour la métrique 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
Les clés des paires clé-valeur matchLabels doivent correspondre à l'expression régulière ^[a-zA-Z_][a-zA-Z0-9_]*, c'est-à-dire commencer par une lettre ou un trait de soulignement, et ne contenir que des lettres, des chiffres ou des traits de soulignement.
Récupérer des métriques personnalisées ou externes depuis Cloud Monitoring
Vous pouvez extraire des métriques de Cloud Monitoring pour mettre à l'échelle vos charges de travail. GKE permet d'extraire deux types de métriques de Cloud Monitoring :
- Métriques personnalisées : utilisez ce type pour appliquer des fonctionnalités PromQL, comme le calcul des centiles ou la lecture des valeurs historiques, aux métriques émises par les charges de travail de votre cluster.
- Métriques externes : utilisez ce type pour effectuer un scaling basé sur une entité en dehors du cluster, comme le nombre de messages en attente dans un abonnement Pub/Sub.
Sinon, récupérez les métriques personnalisées du cluster.
Conditions requises
- GKE version 1.36.2-gke.2771000 ou ultérieure.
- Les métriques doivent être stockées dans Cloud Monitoring. Par exemple, vous pouvez utiliser Google Cloud Managed Service pour Prometheus.
- Un maximum de 100 métriques est autorisé par cluster. Cette limite correspond au total combiné des métriques personnalisées et externes.
- Les métriques de Cloud Monitoring doivent se trouver dans le même Google Cloud projet que le cluster faisant l'objet d'un autoscaling.
Définir la métrique
Vous utilisez un fichier YAML pour définir les métriques, y compris la requête PromQL spécifique.
Choisissez l'une des configurations suivantes, selon que vous récupérez une métrique personnalisée ou une métrique externe :
Créez un objet AutoscalingMetric et définissez la métrique à récupérer.
Métrique personnalisée (pods)
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"Remplacez les éléments suivants :
NAME: nom de l'objet AutoscalingMetric.NAMESPACE: espace de noms de l'objet AutoscalingMetric, qui doit correspondre à l'espace de noms de la charge de travail que vous souhaitez mettre à l'échelle.METRIC_NAME: nom de la métrique utilisée par l'objet HorizontalPodAutoscaler.PROMQL_QUERY: requête PromQL qui interroge la métrique. La requête PromQL doit renvoyer un vecteur avec une entrée par pod dans la ressource avec autoscaling (par exemple, une entrée par pod dans un déploiement).
Vous pouvez définir plusieurs métriques dans un même fichier manifeste AutoscalingMetric en ajoutant des entrées
promqlau tableaumetrics.Dans ce fichier manifeste, les éléments suivants s'appliquent :
- Le champ
type: Podsindique que les métriques sont émises par les pods. Facultatif : Les champs
metricLabelscorrespondent aux noms de libellés dans le résultat de la requête PromQL qui liste les détails de la ressource (tels que le nom du pod, l'espace de noms ou les informations du cluster). La métrique personnalisée émise par un pod doit inclure un libellé correspondant au champpodName, qui indique à quel pod la métrique est associée. Ce libellé est configuré automatiquement lorsque vous envoyez des métriques à Cloud Monitoring à l'aide de Google Cloud Managed Service pour Prometheus.Si ces champs ne sont pas spécifiés dans l'objet AutoscalingMetric, les valeurs par défaut suivantes sont utilisées pour trouver les informations dans le libellé. Ces valeurs par défaut sont les mêmes noms de libellés que ceux configurés par Google Cloud Managed Service pour Prometheus :
podName: "pod"namespace: "namespace"clusterName: "cluster"location: "location"projectId: "project_id"
Métrique externe
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'Remplacez les éléments suivants :
NAME: nom de l'objet AutoscalingMetric.NAMESPACE: espace de noms de l'objet AutoscalingMetric, qui doit correspondre à l'espace de noms de la charge de travail que vous souhaitez mettre à l'échelle.METRIC_NAME: nom de la métrique utilisée par AHP.PROMQL_QUERY: requête PromQL qui interroge la métrique. La requête PromQL doit renvoyer une valeur scalaire ou un vecteur avec une entrée unique.
Vérifiez les requêtes PromQL dans Cloud Monitoring pour vous assurer qu'elles renvoient les métriques attendues. Il est plus facile de vérifier les requêtes au moment de leur configuration que de résoudre les problèmes de comportement inattendu plus tard.
Pour vérifier les requêtes, consultez la section suivante : Vérifier les requêtes PromQL.
Appliquez le fichier manifeste AutoscalingMetric au cluster :
kubectl apply -f MANIFEST_FILE.yamlRemplacez
MANIFEST_FILEpar le nom du fichier YAML.Vérifiez la définition de la métrique et récupérez le nom de la métrique à utiliser pour l'objet HorizontalPodAutoscaler :
Exécutez la commande
kubectl describepour la ressource personnalisée AutoscalingMetric :kubectl describe autoscalingmetric NAME -n NAMESPACERemplacez les éléments suivants :
NAME: nom de l'objet AutoscalingMetric.NAMESPACE: espace de noms de l'objet AutoscalingMetric.
Examinez le champ
Status. Si aucune erreur n'est listée, l'objet est valide.Copiez le nom dans le champ
HPA Name. Il s'agit du nom que vous ajoutez à l'objet HorizontalPodAutoscaler. Ce nom a le format suivant :autoscaling.gke.io|NAME|METRIC_NAME.
La métrique est désormais définie dans l'objet AutoscalingMetric. Pour effectuer l'autoscaling avec cette métrique, vous devez la référencer dans un objet HorizontalPodAutoscaler. Pour en savoir plus, consultez la section Utiliser les métriques dans l'objet HorizontalPodAutoscaler.
Utiliser les métriques dans l'objet HorizontalPodAutoscaler
Créez un objet HorizontalPodAutoscaler. Le type de métrique HorizontalPodAutoscaler doit correspondre à la valeur du champ
typedéfini dans la ressource personnalisée AutoscalingMetric. Choisissez l'une des configurations suivantes en fonction de votre type de métrique :Option 1 : Métrique externe
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_VALUEOption 2 : Métrique "Pods"
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_VALUERemplacez les éléments suivants :
HPA_NAME: nom de l'objet HorizontalPodAutoscaler.NAMESPACE: espace de noms de l'objet HorizontalPodAutoscaler, qui doit correspondre à l'espace de noms de la charge de travail et de la ressource AutoscalingMetric.DEPLOYMENT_NAME: nom du déploiement de charge de travail que vous souhaitez mettre à l'échelle.MIN_REPLICAS: nombre minimal de pods en cours d'exécution.MAX_REPLICAS: nombre maximal de pods en cours d'exécution.NAME: nom de la ressource personnalisée AutoscalingMetric que vous avez créée.METRIC_NAME: nom de la métrique définie dans la ressource AutoscalingMetric.AVERAGE_VALUE: valeur cible de la métrique à laquelle l'autoscaler met à l'échelle la charge de travail.
Lorsque vous créez votre propre objet HorizontalPodAutoscaler, tenez compte des points suivants :
- Les objets AutoscalingMetric, Deployment et HorizontalPodAutoscaler doivent se trouver dans le même espace de noms.
- L'exemple précédent utilise la paire clé-valeur
type: AverageValue. Notez quetype: Valueest également accepté pour les métriques externes. - L'exemple précédent n'utilise un objet Deployment qu'à titre d'illustration. Vous pouvez également effectuer l'autoscaling de tout objet compatible avec les objets HorizontalPodAutoscaler, comme un objet ReplicaSet.
Appliquez le fichier manifeste HorizontalPodAutoscaler :
kubectl apply -f HPA_MANIFEST_FILE.yamlRemplacez
HPA_MANIFEST_FILEpar le nom du fichier YAML.
Résoudre les problèmes liés aux métriques récupérées pour l'autoscaling
Pour résoudre les problèmes liés à la récupération des métriques, vous pouvez consulter les journaux ou l'état de la ressource personnalisée AutoscalingMetric.
L'adaptateur de métriques d'autoscaling ne comporte aucune réplique
Lorsque vous inspectez le déploiement autoscaling-metrics-adapter dans kube-system, vous remarquerez peut-être qu'il ne comporte aucune réplique.
Par défaut, l'adaptateur s'exécute sans réplique pour préserver les ressources du cluster. Ce comportement est normal. Le déploiement n'évolue que jusqu'à un réplica lorsqu'une ressource personnalisée AutoscalingMetric nécessitant un traitement PromQL existe dans le cluster.
Si vous avez configuré un objet AutoscalingMetric avec une requête PromQL, mais que l'adaptateur n'a pas été mis à l'échelle, vérifiez que l'objet a bien été créé dans le cluster.
Examiner les journaux
Pour identifier les problèmes liés au contrôleur chargé d'obtenir les métriques de Cloud Monitoring, vous pouvez consulter ses journaux.
Vous pouvez afficher les journaux dans la console Google Cloud :
Accédez à la page Explorateur de journaux :
Dans le volet "Requête", saisissez la requête suivante :
resource.type="k8s_container" resource.labels.namespace_name="kube-system" resource.labels.container_name="autoscaling-metrics-adapter"
Vous pouvez également exécuter la commande suivante pour afficher les journaux à l'aide de kubectl :
kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system
Examiner l'état d'AutoscalingMetric
Vous pouvez examiner l'état de la ressource personnalisée AutoscalingMetric pour rechercher les erreurs de configuration.
Inspectez la ressource personnalisée AutoscalingMetric :
kubectl describe autoscalingmetric NAME -n NAMESPACERemplacez les éléments suivants :
NAME: nom de la ressource personnalisée AutoscalingMetric que vous avez créée.NAMESPACE: espace de noms de la ressource personnalisée.
Pour en savoir plus sur les métriques configurées, consultez le champ
Status. Ces informations incluent les éventuels avertissements concernant les erreurs de configuration et le nom exact de la métrique tel qu'il doit apparaître dans l'objet HorizontalPodAutoscaler.Voici un exemple d'état valide :
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>Voici un exemple d'état avec une erreur de configuration :
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>
Vérifier les requêtes PromQL
Si vous récupérez des métriques depuis Cloud Monitoring à l'aide d'une requête PromQL, un problème lié à la requête peut entraîner des erreurs lors de la récupération de la métrique ou entraîner la récupération d'une valeur inattendue. Par exemple, si vous vous attendez à ce qu'un pourcentage soit renvoyé sous la forme d'une valeur comprise entre 1 et 100, mais que vous recevez une valeur comprise entre 0 et 1, l'autoscaling qui en résulte se comporte de manière inattendue.
Vous pouvez tester les requêtes PromQL dans Cloud Monitoring pour vérifier qu'elles renvoient les métriques attendues.
Pour vérifier les requêtes, procédez comme suit :
Dans la console Google Cloud , accédez à la page Explorateur de métriques.
En haut du volet Générateur de requêtes, sélectionnez l'onglet PromQL.
Dans l'éditeur de requête, saisissez la requête PromQL que vous souhaitez tester.
Cliquez sur Exécuter la requête pour afficher les métriques dans le graphique.
Étapes suivantes
- Pour obtenir une présentation de l'autoscaling basé sur les métriques, consultez À propos de l'autoscaling des charges de travail en fonction des métriques.
- Pour effectuer l'autoscaling à l'aide de métriques qui ne peuvent pas être définies avec une requête PromQL, consultez Optimiser l'autoscaling des pods en fonction des métriques.