métriques d'état de Kube
v2.14.0
kube-state-metrics (KSM) est un service simple qui écoute le serveur API Kubernetes et génère des métriques sur l'état des objets. (Voir les exemples dans la section Métriques ci-dessous.) Il ne se concentre pas sur la santé des composants Kubernetes individuels, mais plutôt sur la santé des différents objets à l'intérieur, tels que les déploiements, les nœuds et les pods.
kube-state-metrics consiste à générer des métriques à partir d'objets de l'API Kubernetes sans modification. Cela garantit que les fonctionnalités fournies par kube-state-metrics ont le même niveau de stabilité que les objets de l'API Kubernetes eux-mêmes. À son tour, cela signifie que les métriques kube-state-metrics dans certaines situations peuvent ne pas afficher exactement les mêmes valeurs que kubectl, car kubectl applique certaines heuristiques pour afficher des messages compréhensibles. kube-state-metrics expose les données brutes non modifiées de l'API Kubernetes, de cette façon les utilisateurs disposent de toutes les données dont ils ont besoin et exécutent les heuristiques comme bon leur semble.
Les métriques sont exportées sur le point de terminaison HTTP /metrics sur le port d'écoute (par défaut 8080). Ils sont servis en texte clair. Ils sont conçus pour être consommés soit par Prometheus lui-même, soit par un scraper compatible avec le scraping d'un point de terminaison client Prometheus. Vous pouvez également ouvrir /metrics dans un navigateur pour voir les métriques brutes. Notez que les métriques exposées sur le point de terminaison /metrics reflètent l’état actuel du cluster Kubernetes. Lorsque les objets Kubernetes sont supprimés, ils ne sont plus visibles sur le point de terminaison /metrics .
Note
Ce README est généré à partir d'un modèle. Veuillez y apporter vos modifications et exécuter make generate-template .
Gestion des versions
Version Kubernetes
Matrice de compatibilité
Compatibilité des versions du groupe de ressources
Image du conteneur
Documentation sur les métriques
Résolution des conflits dans les noms d'étiquettes
Kube-state-metrics auto-métriques
Recommandation de ressources
Latence
Une note sur les coûts
kube-state-metrics vs metrics-server
Mise à l'échelle des métriques Kube-State
Partage automatisé
Recommandation de ressources
Partage horizontal
Sharding de démonset pour les métriques de pod
Installation
Construire le conteneur Docker
Usage
Déploiement de Kubernetes
Environnement à privilèges limités
Tableau de barre
Développement
Contributions des développeurs
Communauté
kube-state-metrics utilise client-go pour communiquer avec les clusters Kubernetes. La version du cluster Kubernetes prise en charge est déterminée par client-go . La matrice de compatibilité pour client-go et le cluster Kubernetes peut être trouvée ici. Toute compatibilité supplémentaire n'est qu'un effort, ou se trouve être encore/déjà prise en charge.
Au maximum, 5 kube-state-metrics et 5 versions de Kubernetes seront enregistrées ci-dessous. Généralement, il est recommandé d'utiliser la dernière version de kube-state-metrics. Si vous exécutez une version très récente de Kubernetes, vous souhaiterez peut-être utiliser une version inédite pour bénéficier de la gamme complète des ressources prises en charge. Si vous exécutez une ancienne version de Kubernetes, vous devrez peut-être exécuter une ancienne version afin de bénéficier d'une prise en charge complète de toutes les ressources. Sachez que les responsables ne prendront en charge que la dernière version. Les versions plus anciennes peuvent être prises en charge par les utilisateurs intéressés de la communauté.
| métriques-état-kube | Version client Kubernetes |
|---|---|
| v2.10.1 | v1.27 |
| v2.11.0 | v1.28 |
| v2.12.0 | v1.29 |
| v2.13.0 | v1.30 |
| v2.14.0 | v1.31 |
| principal | v1.31 |
Les ressources dans Kubernetes peuvent évoluer, c'est-à-dire que la version de groupe d'une ressource peut passer d'alpha à bêta et enfin GA dans différentes versions de Kubernetes. Pour l'instant, kube-state-metrics n'utilisera que l'API la plus ancienne disponible dans la dernière version.
La dernière image du conteneur peut être trouvée à l'adresse :
registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.14.0 (arch : amd64 , arm , arm64 , ppc64le et s390x )
Voir toutes les images multi-architecture ici
Toutes les ressources et métriques basées sur les API alpha Kubernetes sont exclues de toute garantie de stabilité, qui peut être modifiée à chaque version donnée.
Consultez le répertoire docs pour plus d’informations sur les métriques exposées.
La famille de métriques *_labels expose les étiquettes Kubernetes en tant qu'étiquettes Prometheus. Comme Kubernetes est plus libéral que Prometheus en termes de caractères autorisés dans les noms d'étiquettes, nous convertissons automatiquement les caractères non pris en charge en traits de soulignement. Par exemple, app.kubernetes.io/name devient label_app_kubernetes_io_name .
Cette conversion peut créer des conflits lorsque plusieurs étiquettes Kubernetes telles que foo-bar et foo_bar seraient converties en la même étiquette Prometheus label_foo_bar .
Kube-state-metrics ajoute automatiquement un suffixe _conflictN pour résoudre ce conflit, il convertit donc les étiquettes ci-dessus en label_foo_bar_conflict1 et label_foo_bar_conflict2 .
Si vous souhaitez avoir plus de contrôle sur la façon dont ce conflit est résolu, vous pouvez envisager de résoudre ce problème à un niveau différent de la pile, par exemple en standardisant les étiquettes Kubernetes à l'aide d'un Webhook d'admission qui garantit qu'il n'y a aucun conflit possible.
kube-state-metrics expose ses propres métriques de processus générales sous --telemetry-host et --telemetry-port (par défaut 8081).
kube-state-metrics expose également des mesures de réussite et d'erreur de liste et de surveillance. Ceux-ci peuvent être utilisés pour calculer le taux d’erreur des ressources de liste ou de surveillance. Si vous rencontrez ces erreurs dans les métriques, il s'agit probablement d'un problème de configuration ou d'autorisation, et la prochaine chose à enquêter serait d'examiner les journaux de kube-state-metrics.
Exemple des métriques mentionnées ci-dessus :
kube_state_metrics_list_total{resource="*v1.Node",result="success"} 1
kube_state_metrics_list_total{resource="*v1.Node",result="error"} 52
kube_state_metrics_watch_total{resource="*v1beta1.Ingress",result="success"} 1kube-state-metrics expose également certaines métriques de requête http, par exemple :
http_request_duration_seconds_bucket{handler="metrics",method="get",le="2.5"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="5"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="10"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="+Inf"} 30
http_request_duration_seconds_sum{handler="metrics",method="get"} 0.021113919999999998
http_request_duration_seconds_count{handler="metrics",method="get"} 30kube-state-metrics expose également les métriques de build et de configuration :
kube_state_metrics_build_info{branch="main",goversion="go1.15.3",revision="6c9d775d",version="v2.0.0-beta"} 1
kube_state_metrics_shard_ordinal{shard_ordinal="0"} 0
kube_state_metrics_total_shards 1 kube_state_metrics_build_info est utilisé pour exposer la version et d'autres informations de build. Pour en savoir plus sur le modèle d'informations, veuillez consulter l'article de blog ici. Les métriques de partitionnement exposent les indicateurs --shard et --total-shards et peuvent être utilisées pour valider la configuration d'exécution, voir /examples/prometheus-alerting-rules .
kube-state-metrics expose également des métriques sur son fichier de configuration et le fichier de configuration Custom Resource State :
kube_state_metrics_config_hash{filename="crs.yml",type="customresourceconfig"} 2.38272279311849e+14
kube_state_metrics_config_hash{filename="config.yml",type="config"} 2.65285922340846e+14
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="crs.yml",type="customresourceconfig"} 1.6704882592037103e+09
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="config.yml",type="config"} 1.6704882592035313e+09
kube_state_metrics_last_config_reload_successful{filename="crs.yml",type="customresourceconfig"} 1
kube_state_metrics_last_config_reload_successful{filename="config.yml",type="config"} 1L'utilisation des ressources pour les métriques Kube-State change avec la taille des objets Kubernetes (pods/nœuds/déploiements/secrets, etc.) du cluster. Dans une certaine mesure, les objets Kubernetes d'un cluster sont directement proportionnels au numéro de nœud du cluster.
En règle générale, vous devez allouer :
250 Mo de mémoire
0,1 cœurs
Notez que si les limites du processeur sont trop basses, les files d'attente internes de kube-state-metrics ne pourront pas être traitées assez rapidement, ce qui entraînera une consommation de mémoire accrue à mesure que la longueur de la file d'attente augmente. Si vous rencontrez des problèmes résultant d'une allocation de mémoire élevée ou d'une limitation du processeur, essayez d'augmenter les limites du processeur.
Dans un test de mise à l'échelle d'un cluster de 100 nœuds, les chiffres de latence étaient les suivants :
"Perc50": 259615384 ns, "Perc90": 475000000 ns, "Perc99": 906666666 ns.
Par défaut, kube-state-metrics expose plusieurs métriques pour les événements de votre cluster. Si vous disposez d'un grand nombre de ressources mises à jour fréquemment sur votre cluster, vous constaterez peut-être qu'une grande quantité de données est ingérée dans ces métriques. Cela peut entraîner des coûts élevés pour certains fournisseurs de cloud. Veuillez prendre un moment pour configurer les métriques que vous souhaitez exposer, ainsi que consulter la documentation de votre environnement Kubernetes afin d'éviter des coûts étonnamment élevés.
Le serveur de métriques est un projet inspiré de Heapster et mis en œuvre pour répondre aux objectifs des pipelines de métriques de base dans l'architecture de surveillance Kubernetes. Il s'agit d'un composant au niveau du cluster qui récupère périodiquement les métriques de tous les nœuds Kubernetes servis par Kubelet via l'API Metrics. Les métriques sont agrégées, stockées en mémoire et servies au format Metrics API. Le serveur de métriques stocke uniquement les dernières valeurs et n'est pas responsable de la transmission des métriques vers des destinations tierces.
kube-state-metrics se concentre sur la génération de métriques complètement nouvelles à partir de l'état des objets de Kubernetes (par exemple, des métriques basées sur les déploiements, les jeux de réplicas, etc.). Il conserve en mémoire un instantané complet de l’état de Kubernetes et génère en permanence de nouvelles métriques basées sur celui-ci. Et tout comme le serveur de métriques, il n’est pas non plus responsable de l’exportation de ses métriques n’importe où.
Avoir kube-state-metrics en tant que projet distinct permet également d'accéder à ces métriques à partir de systèmes de surveillance tels que Prometheus.
Afin de partager les métriques Kube-State horizontalement, certaines fonctionnalités de partitionnement automatisées ont été implémentées. Il est configuré avec les drapeaux suivants :
--shard (indexé à zéro)
--total-shards
Le partitionnement est effectué en prenant une somme md5 de l'UID de l'objet Kubernetes et en effectuant une opération modulo sur celui-ci avec le nombre total de fragments. Chaque fragment décide si l'objet est géré ou non par l'instance respective de kube-state-metrics. Notez que cela signifie que toutes les instances de kube-state-metrics, même si elles sont fragmentées, auront le trafic réseau et la consommation de ressources nécessaires au démarshaling des objets pour tous les objets, pas seulement pour ceux dont ils sont responsables. Pour optimiser davantage cela, l'API Kubernetes devrait prendre en charge les fonctionnalités de liste/surveillance fragmentées. Dans le cas optimal, la consommation de mémoire pour chaque partition sera de 1/n par rapport à une configuration non partitionnée. En règle générale, kube-state-metrics doit être optimisé en termes de mémoire et de latence pour pouvoir renvoyer ses métriques assez rapidement à Prometheus. Une façon de réduire la latence entre kube-state-metrics et kube-apiserver consiste à exécuter KSM avec l'indicateur --use-apiserver-cache . En plus de réduire la latence, cette option entraînera également une réduction de la charge sur etcd.
Le partitionnement doit être utilisé avec précaution et une surveillance supplémentaire doit être mise en place afin de garantir que le partitionnement est configuré et fonctionne comme prévu (par exemple, des instances pour chaque fragment sur le total des fragments sont configurées).
Le partitionnement automatique permet à chaque fragment de découvrir sa position nominale lorsqu'il est déployé dans un StatefulSet, ce qui est utile pour configurer automatiquement le partitionnement. Il s'agit d'une fonctionnalité expérimentale et peut être interrompue ou supprimée sans préavis.
Pour activer le partitionnement automatisé, kube-state-metrics doit être exécuté par un StatefulSet et le nom du pod et l'espace de noms doivent être transmis au processus kube-state-metrics via les indicateurs --pod et --pod-namespace . Des exemples de manifestes illustrant la fonctionnalité de partage automatique peuvent être trouvés dans /examples/autosharding .
Cette façon de déployer des fragments est utile lorsque vous souhaitez gérer les fragments KSM via une seule ressource Kubernetes (un seul StatefulSet dans ce cas) au lieu d'avoir un Deployment par fragment. L’avantage peut être particulièrement important lors du déploiement d’un nombre élevé de partitions.
L'inconvénient de l'utilisation d'une configuration auto-partitionnée vient de la stratégie de déploiement prise en charge par StatefulSet s. Lorsqu'ils sont gérés par un StatefulSet , les pods sont remplacés un par un, chaque pod étant d'abord terminé, puis recréé. Outre le fait que ces déploiements soient plus lents, ils entraîneront également de courts temps d'arrêt pour chaque fragment. Si un grattage de Prometheus se produit lors d'un déploiement, il peut manquer certaines des métriques exportées par kube-state-metrics.
Pour les métriques de pod, elles peuvent être partagées par nœud avec l'indicateur suivant :
--node=$(NODE_NAME)
Chaque pod kube-state-metrics utilise FieldSelector (spec.nodeName) pour surveiller/répertorier les métriques du pod uniquement sur le même nœud.
Un exemple de jeu de démons kube-state-metrics :
apiVersion: apps/v1 kind: DaemonSet spec: template: spec: containers: - image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG name: kube-state-metrics args: - --resource=pods - --node=$(NODE_NAME) env: - name: NODE_NAME valueFrom: fieldRef: apiVersion: v1 fieldPath: spec.nodeName
Pour suivre les métriques des pods non attribués, vous devez ajouter un déploiement supplémentaire et définir --track-unscheduled-pods , comme indiqué dans l'exemple suivant :
apiVersion: apps/v1 kind: Deployment spec: template: spec: containers: - image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG name: kube-state-metrics args: - --resources=pods - --track-unscheduled-pods
D'autres métriques peuvent être partagées via le partage horizontal.
Installez ce projet sur votre $GOPATH en utilisant go get :
go get k8s.io/kube-state-metrics
Exécutez simplement la commande suivante dans ce dossier racine, qui créera un binaire autonome lié statiquement et construira une image Docker :
make container
Créez et exécutez simplement kube-state-metrics dans un pod Kubernetes doté d'un jeton de compte de service ayant un accès en lecture seule au cluster Kubernetes.
La pile ( kube-prometheus ) installe kube-state-metrics comme l'un de ses composants ; vous n'avez pas besoin d'installer kube-state-metrics si vous utilisez la pile kube-prometheus.
Si vous souhaitez réviser la configuration par défaut de Kube-Prometheus, par exemple pour activer des métriques autres que celles par défaut, consultez Personnalisation de Kube-Prometheus.
Pour déployer ce projet, vous pouvez simplement exécuter kubectl apply -f examples/standard et un service et un déploiement Kubernetes seront créés. (Remarque : ajustez l'apiVersion de certaines ressources si la version de votre cluster Kubernetes n'est pas 1.8+, consultez le fichier yaml pour plus d'informations).
Pour que Prometheus découvre les instances de kube-state-metrics, il est conseillé de créer une configuration de scrape Prometheus spécifique pour kube-state-metrics qui récupère les deux points de terminaison des métriques. La découverte basée sur les annotations est déconseillée car un seul des points de terminaison pourrait être sélectionné, et kube-state-metrics a dans la plupart des cas des exigences d'authentification et d'autorisation spéciales car il accorde essentiellement un accès en lecture via le point de terminaison des métriques à la plupart des informations disponibles.
Remarque : Utilisateurs de Google Kubernetes Engine (GKE) – GKE dispose d'autorisations de rôle strictes qui empêcheront la création des rôles kube-state-metrics et des liaisons de rôle. Pour contourner ce problème, vous pouvez attribuer à votre identité GCP le rôle d'administrateur de cluster en exécutant la ligne suivante :
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')
Notez que votre identité GCP est sensible à la casse, mais gcloud info du SDK Google Cloud 221.0.0 ne le sont pas. Cela signifie que si votre membre IAM contient des majuscules, la ligne ci-dessus peut ne pas fonctionner pour vous. Si vous avez 403 réponses interdites après avoir exécuté la commande ci-dessus et kubectl apply -f examples/standard , vérifiez le membre IAM associé à votre compte sur https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID . S'il contient des lettres majuscules, vous devrez peut-être définir l'indicateur --user dans la commande ci-dessus sur le rôle sensible à la casse répertorié sur https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID.
Après avoir exécuté ce qui précède, si vous voyez Clusterrolebinding "cluster-admin-binding" created , vous pouvez alors continuer la configuration de ce service.
Les points de terminaison de contrôle de santé suivants sont disponibles ( self fait référence au port de télémétrie, tandis que main fait référence au port d'exposition) :
/healthz (exposé sur main ) : renvoie un code d'état 200 si l'application est en cours d'exécution. Nous vous recommandons de l'utiliser pour la sonde de démarrage.
/livez (exposé sur main ) : renvoie un code d'état 200 si l'application n'est pas affectée par une panne du serveur API Kubernetes. Nous vous recommandons de l'utiliser pour la sonde de vivacité.
/readyz (exposed on self ) : renvoie un code d'état 200 si l'application est prête à accepter les demandes et à exposer les métriques. Nous vous recommandons de l'utiliser pour la sonde de préparation.
Notez qu’il est déconseillé d’utiliser le point de terminaison des métriques de télémétrie pour toute sonde lors de la transmission par proxy des données d’exposition.
Si vous souhaitez exécuter kube-state-metrics dans un environnement dans lequel vous n'avez pas de rôle de lecteur de cluster, vous pouvez :
créer un compte de service
apiVersion : v1kind : ServiceAccountmetadata : nom : kube-state-metrics espace de noms : votre-espace-de-noms-où-kube-state-metrics-sera-déployé
donnez-lui des privilèges view sur des espaces de noms spécifiques (en utilisant roleBinding) ( remarque : vous pouvez ajouter ce roleBinding à tous les NS auxquels vous souhaitez que votre compte de service accède )
apiVersion : rbac.authorization.k8s.io/v1kind : RoleBindingmetadata : nom : kube-state-metrics espace de noms : project1roleRef : apiGroup : rbac.authorization.k8s.io genre : ClusterRole nom : vuessujets : - kind : ServiceAccountname : kube-state-metricsnamespace : votre-espace de noms-où-kube-state-metrics-will-deployed
puis spécifiez un ensemble d'espaces de noms (à l'aide de l'option --namespaces ) et un ensemble d'objets Kubernetes (à l'aide de --resources ) auxquels votre compte de service a accès dans la configuration de déploiement kube-state-metrics
spec : modèle : spec : conteneurs :
- nom : kube-state-metricsargs :
- '--resources=pods' - '--namespaces=project1'Pour la liste complète des arguments disponibles, consultez la documentation dans docs/developer/cli-arguments.md
À partir du graphique kube-state-metrics v2.13.3 (image kube-state-metrics v1.9.8 ), le graphique Helm officiel est conservé dans prometheus-community/helm-charts. À partir du graphique kube-state-metrics v3.0.0 seules les images kube-state-metrics de v2.0.0 + sont prises en charge.
Lors du développement, testez un vidage de métriques sur votre cluster Kubernetes local en exécutant :
Les utilisateurs peuvent remplacer l'adresse apiserver dans le fichier KUBE-CONFIG avec la ligne de commande
--apiserver.
go install kube-state-metrics --port=8080 --telemetry-port=8081 --kubeconfig=--apiserver=
Ensuite, bouclez le point de terminaison des métriques
curl localhost:8080/metrics
Pour exécuter les tests e2e localement, consultez la documentation dans tests/README.md.
Lors du développement, il existe certains modèles de code à suivre pour améliorer votre expérience de contribution et vos chances de réussite aux tests e2e et autres ci. Pour en savoir plus à leur sujet, consultez la documentation dans docs/developer/guide.md.
Ce projet est sponsorisé par SIG Instrumentation.
Il existe également un canal pour #kube-state-metrics sur Slack de Kubernetes.
Vous pouvez également rejoindre la liste de diffusion SIG Instrumentation. Cela ajoutera généralement des invitations pour les réunions suivantes à votre calendrier, dans lesquelles des sujets autour des métriques kube-state-metrics pourront être discutés.
Réunion ordinaire du SIG : les jeudis à 9 h 30 (heure du Pacifique) (toutes les deux semaines). Convertissez vers votre fuseau horaire.
Réunion de triage régulière : les jeudis à 9 h 30 (heure du Pacifique) (toutes les deux semaines - en alternance avec une réunion ordinaire). Convertissez vers votre fuseau horaire.
