Autoscaler les pods à l'aide de métriques personnalisées ou externes

Ce document explique comment extraire et utiliser des métriques personnalisées et externes pour mettre à l'échelle des pods horizontalement.

Pour extraire les métriques, vous utilisez un adaptateur de métriques géré. Cette solution gérée est disponible pour les métriques dans Cloud Monitoring qui peuvent être interrogées avec PromQL, ainsi que pour toutes les métriques personnalisées. Les métriques personnalisées sont des métriques exposées par les pods sous un point de terminaison HTTP, au format Prometheus.

Vous pouvez également effectuer un autoscaling à l'aide de n'importe quelle métrique. Pour cela, vous pouvez extraire la métrique en configurant manuellement un adaptateur de métriques afin d'envoyer des métriques à un autoscaler. Ce workflow implique l'installation d'un adaptateur tiers, tel que l' adaptateur de métriques personnalisées, et la configuration des autorisations. Pour obtenir un exemple, consultez le tutoriel Optimiser l'autoscaling des pods en fonction des métriques.

Extraire des métriques

Vous pouvez extraire des métriques de différentes manières :

• Les métriques personnalisées émises par les pods peuvent être extraites 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 stockées dans Cloud Monitoring peuvent être extraites à 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.
• Les métriques peuvent être extraites en configurant manuellement un adaptateur de métriques afin d'envoyer des métriques à un autoscaler. Ce workflow implique l'installation d'outils tiers et la configuration des autorisations. Pour obtenir un exemple, consultez le tutoriel Optimiser l'autoscaling des pods en fonction des métriques.

Une fois la métrique extraite, vous y faites référence 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 des métriques, consultez la section À propos de l'autoscaling des charges de travail en fonction des métriques.

Extraire 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 conditions requises pour les pods :

• GKE 1.35.1-gke.1396000 ou version ultérieure avec des clusters dans le canal rapide.
• Utilisez l'autoscaling horizontal des pods avec le profil de performances.

Voici les conditions requises pour les métriques :

• Les métriques doivent être accessibles sur un point de terminaison HTTP. Le chemin d'accès au point de terminaison est /metrics par défaut.
• Les métriques doivent être mises en forme conformément à la norme Prometheus.
• Seules les métriques de type "gauge" sont acceptées.
• Les noms des libellés dans les sélecteurs de libellés de pod ne doivent pas contenir de caractères spéciaux. Seules 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 un filtrage basé sur des é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

1. 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 métrique est sélectionnée.

2. 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_NAME
   

   Remplacez 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_NAME et APP_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. Ce chemin d'accès est souvent /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 traits d'union, des lettres minuscules ou des chiffres. Toutefois, le dernier caractère ne peut pas être un trait d'union.

   • Facultatif : METRIC_PROMETHEUS_NAME : nom de la métrique Prometheus tel qu'exposé par le pod. Vous pouvez utiliser ce champ pour renommer la métrique, par exemple, car 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 de nom, consultez les limites de l'autoscaling horizontal des pods.

3. Appliquez le fichier manifeste à l'aide de la commande suivante :

   kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml
   

   Remplacez FILE_NAME_AUTOSCALING_METRIC par le nom du fichier YAML.

4. Vérifiez la définition de la métrique et récupérez le nom de la métrique à utiliser pour l'objet HorizontalPodAutoscaler :

   1. Exécutez la commande kubectl describe pour la ressource personnalisée AutoscalingMetric :

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Remplacez les éléments suivants :

      • NAME: nom de l'objet AutoscalingMetric.
      • NAMESPACE: espace de noms de l'objet AutoscalingMetric.

   2. Examinez le champ Status. Si aucune erreur n'est listée, l'objet est valide.

   3. 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 maintenant définie dans l'objet AutoscalingMetric. Pour effectuer un autoscaling avec cette métrique, vous devez y faire référence 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 d'autoscaling. La métrique est lue toutes les quelques secondes et envoyée à l'autoscaler de la charge de travail.

Extraire des métriques personnalisées ou externes de Cloud Monitoring

Vous pouvez extraire des métriques de Cloud Monitoring pour mettre à l'échelle vos charges de travail. GKE est compatible avec l'extraction de deux types de métriques à partir de Cloud Monitoring :

• Métriques personnalisées : utilisez ce type pour appliquer des fonctionnalités PromQL, telles que 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 en fonction d'une entité en dehors de le cluster, telle que le nombre de messages en attente dans un abonnement Pub/Sub.

Sinon, extrayez des 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.
• Vous pouvez utiliser jusqu'à 100 métriques par cluster. Cette limite correspond au total combiné des métriques personnalisées et externes.
• Les métriques dans Cloud Monitoring doivent se trouver dans le même Cloud de Confiance by S3NS projet que le cluster qui fait 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 extrayez une métrique personnalisée ou une métrique externe :

1. Créez un objet AutoscalingMetric et définissez la métrique à extraire.

   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 mise à l'échelle automatiquement, par exemple, une entrée par pod dans un déploiement.

   Vous pouvez définir plusieurs métriques dans un seul fichier manifeste AutoscalingMetric en ajoutant des entrées promql supplémentaires au tableau metrics.

   Dans ce fichier manifeste, les éléments suivants s'appliquent :

   • Le champ type: Pods indique que les métriques sont émises par les pods.

   • Facultatif : les champs metricLabels sont les noms des libellés dans le résultat de la requête PromQL qui listent 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 champ podName, spécifiant le pod auquel 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 le 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.

2. 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 lors de leur configuration que de résoudre les problèmes de comportements inattendus ultérieurement.

   Pour vérifier les requêtes, consultez la section suivante : Vérifier les requêtes PromQL.

3. Appliquez le fichier manifeste AutoscalingMetric au cluster :

   kubectl apply -f MANIFEST_FILE.yaml
   

   Remplacez MANIFEST_FILE par le nom du fichier YAML.

4. Vérifiez la définition de la métrique et récupérez le nom de la métrique à utiliser pour l'objet HorizontalPodAutoscaler :

   1. Exécutez la commande kubectl describe pour la ressource personnalisée AutoscalingMetric :

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Remplacez les éléments suivants :

      • NAME: nom de l'objet AutoscalingMetric.
      • NAMESPACE: espace de noms de l'objet AutoscalingMetric.

   2. Examinez le champ Status. Si aucune erreur n'est listée, l'objet est valide.

   3. 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 maintenant définie dans l'objet AutoscalingMetric. Pour effectuer un autoscaling avec cette métrique, vous devez y faire référence 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

1. Créez un objet HorizontalPodAutoscaler. Le type de métrique HorizontalPodAutoscaler doit correspondre à la valeur du champ type dé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_VALUE
   

   Option 2 : Métrique de 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_VALUE
   

   Remplacez 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 la 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 champ-valeur type: AverageValue. Notez que type: Value est également compatible avec les métriques externes.
   • L'exemple précédent n'utilise un objet Deployment qu'à titre d'exemple. Vous pouvez également mettre à l'échelle automatiquement n'importe quel objet compatible avec les objets HorizontalPodAutoscaler, tel qu'un objet ReplicaSet.

2. Appliquez le fichier manifeste HorizontalPodAutoscaler :

   kubectl apply -f HPA_MANIFEST_FILE.yaml
   

   Remplacez HPA_MANIFEST_FILE par le nom du fichier YAML.

Résoudre les problèmes liés aux métriques extraites pour l'autoscaling

Pour résoudre les problèmes liés à l'extraction de 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 instance répliquée

Lorsque vous inspectez le déploiement autoscaling-metrics-adapter dans kube-system, vous remarquerez peut-être qu'il ne comporte aucune instance répliquée.

Par défaut, l'adaptateur s'exécute avec zéro instance répliquée pour économiser les ressources du cluster. Ce comportement est normal. Le déploiement ne passe à une instance répliquée que 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 responsable de l'obtention des métriques à partir de Cloud Monitoring, vous pouvez consulter ses journaux.

Vous pouvez afficher les journaux dans la Cloud de Confiance console :

1. Accédez à la page Explorateur de journaux :

   Accéder à l'explorateur de journaux

2. 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.

1. Inspectez la ressource personnalisée AutoscalingMetric :

   kubectl describe autoscalingmetric NAME -n NAMESPACE
   

   Remplacez 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.

2. Pour en savoir plus sur les métriques configurées, consultez le champ Status. Ces informations incluent tous les 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 extrayez des métriques de 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 résultant 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 :

1. Dans la Cloud de Confiance console, accédez à la page Explorateur de métriques.

   Accéder à l'explorateur de métriques

2. En haut du volet Générateur de requêtes, sélectionnez l'onglet PromQL.

3. Dans l'éditeur de requête, saisissez la requête PromQL que vous souhaitez tester.

4. Cliquez sur Exécuter la requête pour afficher les métriques dans le graphique.

Étape suivante

• Pour obtenir une présentation de l'autoscaling basé sur des métriques, consultez la section À propos de l'autoscaling des charges de travail en fonction des métriques.
• Pour effectuer un autoscaling à l'aide de métriques qui ne peuvent pas être définies avec une requête PromQL, consultez la section Optimiser l'autoscaling des pods en fonction des métriques.