kube state metrics
v2.14.0
kube-state-metrics (KSM) é um serviço simples que escuta o servidor API Kubernetes e gera métricas sobre o estado dos objetos. (Veja exemplos na seção Métricas abaixo.) Ele não se concentra na integridade dos componentes individuais do Kubernetes, mas sim na integridade dos vários objetos internos, como implantações, nós e pods.
kube-state-metrics trata da geração de métricas de objetos da API do Kubernetes sem modificação. Isso garante que os recursos fornecidos pelas métricas de estado do kube tenham o mesmo grau de estabilidade que os próprios objetos da API do Kubernetes. Por sua vez, isso significa que as métricas de estado do kube em certas situações podem não mostrar exatamente os mesmos valores que o kubectl, já que o kubectl aplica certas heurísticas para exibir mensagens compreensíveis. kube-state-metrics expõe dados brutos não modificados da API Kubernetes, dessa forma os usuários têm todos os dados de que precisam e realizam heurísticas conforme acharem adequado.
As métricas são exportadas no endpoint HTTP /metrics na porta de escuta (padrão 8080). Eles são servidos como texto simples. Eles são projetados para serem consumidos pelo próprio Prometheus ou por um raspador compatível com a raspagem de um endpoint do cliente Prometheus. Você também pode abrir /metrics em um navegador para ver as métricas brutas. Observe que as métricas expostas no endpoint /metrics refletem o estado atual do cluster Kubernetes. Quando os objetos do Kubernetes são excluídos, eles não ficam mais visíveis no endpoint /metrics .
Observação
Este README é gerado a partir de um modelo. Faça suas alterações lá e execute make generate-template .
Versionamento
Versão Kubernetes
Matriz de compatibilidade
Compatibilidade de versão do grupo de recursos
Imagem do contêiner
Documentação de métricas
Resolução de conflitos em nomes de rótulos
Autométricas de métricas de estado de Kube
Recomendação de recursos
Latência
Uma nota sobre custos
kube-state-metrics vs. servidor de métricas
Dimensionando métricas de estado do kube
Fragmentação automatizada
Recomendação de recursos
Fragmentação horizontal
Fragmentação do Daemonset para métricas de pod
Configurar
Construindo o contêiner Docker
Uso
Implantação do Kubernetes
Ambiente de privilégios limitados
Gráfico do Helm
Desenvolvimento
Contribuições do desenvolvedor
Comunidade
kube-state-metrics usa client-go para se comunicar com clusters Kubernetes. A versão suportada do cluster Kubernetes é determinada por client-go . A matriz de compatibilidade para cluster client-go e Kubernetes pode ser encontrada aqui. Toda compatibilidade adicional é apenas o melhor esforço ou ainda/já é suportada.
No máximo, 5 lançamentos de kube-state-metrics e 5 kubernetes serão registrados abaixo. Geralmente, é recomendado usar a versão mais recente do kube-state-metrics. Se você executa uma versão muito recente do Kubernetes, talvez queira usar uma versão não lançada para ter toda a gama de recursos suportados. Se você executar uma versão mais antiga do Kubernetes, talvez seja necessário executar uma versão mais antiga para ter suporte total para todos os recursos. Esteja ciente de que os mantenedores oferecerão suporte apenas à versão mais recente. Versões mais antigas podem ser suportadas por usuários interessados da comunidade.
| métricas de estado do kube | Versão do cliente 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 |
Os recursos no Kubernetes podem evoluir, ou seja, a versão do grupo de um recurso pode mudar de alfa para beta e, finalmente, GA em diferentes versões do Kubernetes. Por enquanto, o kube-state-metrics usará apenas a API mais antiga disponível na versão mais recente.
A imagem mais recente do contêiner pode ser encontrada em:
registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.14.0 (arco: amd64 , arm , arm64 , ppc64le e s390x )
Veja todas as imagens multi-arquitetura aqui
Quaisquer recursos e métricas baseados em APIs alfa do Kubernetes estão excluídos de qualquer garantia de estabilidade, que pode ser alterada em qualquer lançamento.
Consulte o diretório docs para obter mais informações sobre as métricas expostas.
A família de métricas *_labels expõe os rótulos do Kubernetes como rótulos do Prometheus. Como o Kubernetes é mais liberal que o Prometheus em termos de caracteres permitidos em nomes de rótulos, convertemos automaticamente caracteres não suportados em sublinhados. Por exemplo, app.kubernetes.io/name torna-se label_app_kubernetes_io_name .
Essa conversão pode criar conflitos quando vários rótulos do Kubernetes, como foo-bar e foo_bar seriam convertidos no mesmo rótulo do Prometheus label_foo_bar .
Kube-state-metrics adiciona automaticamente um sufixo _conflictN para resolver esse conflito, convertendo os rótulos acima em label_foo_bar_conflict1 e label_foo_bar_conflict2 .
Se quiser ter mais controle sobre como esse conflito é resolvido, considere abordar esse problema em um nível diferente da pilha, por exemplo, padronizando rótulos do Kubernetes usando um Webhook de admissão que garante que não haja possíveis conflitos.
kube-state-metrics expõe suas próprias métricas gerais de processo em --telemetry-host e --telemetry-port (padrão 8081).
kube-state-metrics também expõe lista e observa métricas de sucesso e erro. Eles podem ser usados para calcular a taxa de erro da lista ou dos recursos de observação. Se você encontrar esses erros nas métricas, provavelmente é um problema de configuração ou permissão, e a próxima coisa a investigar seria observar os logs das métricas do estado do kube.
Exemplo das métricas mencionadas acima:
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 também expõe algumas métricas de solicitação http, exemplos delas são:
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 também expõe métricas de construção e configuração:
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 é usado para expor a versão e outras informações de compilação. Para obter mais informações sobre o padrão de informações, verifique a postagem do blog aqui. As métricas de fragmentação expõem os sinalizadores --shard e --total-shards e podem ser usadas para validar a configuração de tempo de execução, consulte /examples/prometheus-alerting-rules .
kube-state-metrics também expõe métricas sobre seu arquivo de configuração e o arquivo de configuração 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"} 1O uso de recursos para mudanças nas métricas de estado do kube com o tamanho dos objetos Kubernetes (pods/nós/implantações/segredos etc.) do cluster. Até certo ponto, os objetos Kubernetes em um cluster estão em proporção direta ao número do nó do cluster.
Como regra geral, você deve destacar:
Memória de 250 MiB
0,1 núcleos
Observe que se os limites da CPU forem definidos muito baixos, as filas internas do kube-state-metrics não poderão ser resolvidas com rapidez suficiente, resultando em maior consumo de memória à medida que o comprimento da fila aumenta. Se você tiver problemas resultantes de alta alocação de memória ou limitação da CPU, tente aumentar os limites da CPU.
Em um teste de escalabilidade de cluster de 100 nós, os números de latência foram os seguintes:
"Perc50": 259615384 ns, "Perc90": 475000000 ns, "Perc99": 906666666 ns.
Por padrão, kube-state-metrics expõe diversas métricas para eventos em seu cluster. Se você tiver um grande número de recursos atualizados com frequência em seu cluster, poderá descobrir que muitos dados são ingeridos nessas métricas. Isso pode acarretar custos elevados para alguns provedores de nuvem. Reserve um momento para configurar quais métricas você gostaria de expor, bem como consulte a documentação do seu ambiente Kubernetes para evitar custos elevados inesperadamente.
O servidor de métricas é um projeto inspirado no Heapster e implementado para atender aos objetivos dos principais pipelines de métricas na arquitetura de monitoramento do Kubernetes. É um componente de nível de cluster que coleta periodicamente métricas de todos os nós do Kubernetes atendidos pelo Kubelet por meio da API Metrics. As métricas são agregadas, armazenadas na memória e veiculadas no formato Metrics API. O servidor de métricas armazena apenas os valores mais recentes e não é responsável por encaminhar métricas para destinos de terceiros.
kube-state-metrics está focado na geração de métricas completamente novas a partir do estado do objeto do Kubernetes (por exemplo, métricas baseadas em implantações, conjuntos de réplicas, etc.). Ele mantém um instantâneo completo do estado do Kubernetes na memória e gera continuamente novas métricas com base nele. E assim como o servidor de métricas ele também não é responsável por exportar suas métricas para qualquer lugar.
Ter kube-state-metrics como um projeto separado também permite acesso a essas métricas a partir de sistemas de monitoramento como o Prometheus.
Para fragmentar horizontalmente as métricas do estado do kube, alguns recursos de fragmentação automatizados foram implementados. Ele é configurado com os seguintes sinalizadores:
--shard (zero indexado)
--total-shards
A fragmentação é feita pegando uma soma md5 do UID do objeto Kubernetes e executando uma operação de módulo nele com o número total de fragmentos. Cada fragmento decide se o objeto é tratado pela respectiva instância de kube-state-metrics ou não. Observe que isso significa que todas as instâncias de kube-state-metrics, mesmo que fragmentadas, terão o tráfego de rede e o consumo de recursos para desempacotar objetos para todos os objetos, não apenas aqueles pelos quais eles são responsáveis. Para otimizar ainda mais isso, a API do Kubernetes precisaria oferecer suporte a recursos de lista/observação fragmentada. No caso ideal, o consumo de memória para cada fragmento será de 1/n em comparação com uma configuração não fragmentada. Normalmente, as métricas de estado do kube precisam ser otimizadas em termos de memória e latência para que possam retornar suas métricas rapidamente ao Prometheus. Uma maneira de reduzir a latência entre kube-state-metrics e kube-apiserver é executar o KSM com o sinalizador --use-apiserver-cache . Além de reduzir a latência, esta opção também levará a uma redução na carga do etcd.
A fragmentação deve ser usada com cuidado e o monitoramento adicional deve ser configurado para garantir que a fragmentação esteja configurada e funcionando conforme o esperado (por exemplo, instâncias para cada fragmento do total de fragmentos são configuradas).
A fragmentação automática permite que cada fragmento descubra sua posição nominal quando implantado em um StatefulSet, o que é útil para configurar automaticamente a fragmentação. Este é um recurso experimental e pode ser quebrado ou removido sem aviso prévio.
Para habilitar a fragmentação automatizada, kube-state-metrics deve ser executado por um StatefulSet e o nome do pod e o namespace devem ser entregues ao processo kube-state-metrics por meio dos sinalizadores --pod e --pod-namespace . Manifestos de exemplo que demonstram a funcionalidade de autosharding podem ser encontrados em /examples/autosharding .
Essa forma de implantar shards é útil quando você deseja gerenciar shards KSM por meio de um único recurso Kubernetes (um único StatefulSet neste caso) em vez de ter uma Deployment por shard. A vantagem pode ser especialmente significativa ao implantar um grande número de fragmentos.
A desvantagem de usar uma configuração de fragmentação automática vem da estratégia de implementação suportada por StatefulSet s. Quando gerenciados por um StatefulSet , os pods são substituídos um de cada vez, sendo cada pod primeiro encerrado e depois recriado. Além de essas implementações serem mais lentas, elas também levarão a um curto tempo de inatividade para cada fragmento. Se ocorrer um problema com o Prometheus durante uma implementação, ele pode perder algumas das métricas exportadas pelo kube-state-metrics.
Para métricas de pod, elas podem ser fragmentadas por nó com o seguinte sinalizador:
--node=$(NODE_NAME)
Cada pod kube-state-metrics usa FieldSelector (spec.nodeName) para observar/listar métricas de pod apenas no mesmo nó.
Um exemplo de daemonset 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
Para rastrear métricas de pods não atribuídos, você precisa adicionar uma implantação adicional e definir --track-unscheduled-pods , conforme mostrado no exemplo a seguir:
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
Outras métricas podem ser fragmentadas por meio da fragmentação horizontal.
Instale este projeto em seu $GOPATH usando go get :
go get k8s.io/kube-state-metrics
Basta executar o seguinte comando nesta pasta raiz, que criará um binário independente e vinculado estaticamente e construirá uma imagem Docker:
make container
Basta criar e executar kube-state-metrics dentro de um pod Kubernetes que possui um token de conta de serviço com acesso somente leitura ao cluster Kubernetes.
A pilha ( kube-prometheus ) instala kube-state-metrics como um de seus componentes; você não precisa instalar kube-state-metrics se estiver usando a pilha kube-prometheus.
Se você quiser revisar a configuração padrão do kube-prometheus, por exemplo, para habilitar métricas não padrão, dê uma olhada em Personalizando o Kube-Prometheus.
Para implantar este projeto, você pode simplesmente executar kubectl apply -f examples/standard e um serviço e implantação do Kubernetes serão criados. (Observação: ajuste o apiVersion de algum recurso se a versão do seu cluster Kubernetes não for 1.8+, verifique o arquivo yaml para obter mais informações).
Para que o Prometheus descubra instâncias de kube-state-metrics, é aconselhável criar uma configuração de raspagem específica do Prometheus para kube-state-metrics que coleta ambos os endpoints de métricas. A descoberta baseada em anotações é desencorajada, pois apenas um dos endpoints poderia ser selecionado, além disso, o kube-state-metrics na maioria dos casos tem requisitos especiais de autenticação e autorização, pois essencialmente concede acesso de leitura através do endpoint de métricas para a maioria das informações disponíveis.
Observação: usuários do Google Kubernetes Engine (GKE): o GKE tem permissões de função estritas que impedirão a criação de funções e vinculações de funções do kube-state-metrics. Para contornar isso, você pode atribuir à identidade do GCP a função de administrador de cluster executando a seguinte linha:
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')
Observe que sua identidade do GCP diferencia maiúsculas de minúsculas, mas gcloud info no Google Cloud SDK 221.0.0 não. Isso significa que se o seu membro IAM contiver letras maiúsculas, a linha acima pode não funcionar para você. Se você tiver 403 respostas proibidas após executar o comando acima e kubectl apply -f examples/standard , verifique o membro IAM associado à sua conta em https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID . Se contiver letras maiúsculas, talvez seja necessário definir a sinalização --user no comando acima para a função que diferencia maiúsculas de minúsculas listada em https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID.
Depois de executar o procedimento acima, se você vir Clusterrolebinding "cluster-admin-binding" created , poderá continuar com a configuração deste serviço.
Os seguintes endpoints de verificação de integridade estão disponíveis ( self refere-se à porta de telemetria, enquanto main refere-se à porta de exposição):
/healthz (exposto em main ): Retorna um código de status 200 se o aplicativo estiver em execução. Recomendamos usar isso para a investigação de inicialização.
/livez (exposto em main ): Retorna um código de status 200 se o aplicativo não for afetado por uma interrupção do servidor API Kubernetes. Recomendamos usar isso para a sondagem de atividade.
/readyz (exposto em self ): Retorna um código de status 200 se o aplicativo estiver pronto para aceitar solicitações e expor métricas. Recomendamos usar isso para a sondagem de prontidão.
Observe que não é recomendado usar o ponto de extremidade de métricas de telemetria para qualquer investigação ao fazer proxy dos dados de exposição.
Se quiser executar kube-state-metrics em um ambiente onde você não tem função de leitor de cluster, você pode:
criar uma conta de serviço
apiVersion: v1kind: ServiceAccountmetadata: nome: kube-state-metrics namespace: seu-namespace-onde-kube-state-metrics-will-deployed
conceda privilégios view em namespaces específicos (usando roleBinding) ( nota: você pode adicionar este roleBinding a todos os NS que deseja que sua conta de serviço acesse )
apiVersion: rbac.authorization.k8s.io/v1kind: RoleBindingmetadata: nome: kube-state-metrics namespace: project1roleRef: apiGroup: rbac.authorization.k8s.io tipo: ClusterRole nome: viewsubjects: - tipo: ServiceAccountname: kube-state-metricsnamespace: seu-namespace-onde-kube-state-metrics-will-deployed
em seguida, especifique um conjunto de namespaces (usando a opção --namespaces ) e um conjunto de objetos kubernetes (usando --resources ) aos quais sua conta de serviço tem acesso na configuração de implantação kube-state-metrics
especificação: modelo: especificação: contêineres:
- nome: kube-state-metricsargs:
- '--resources=pods' - '--namespaces=projeto1'Para a lista completa de argumentos disponíveis, consulte a documentação em docs/developer/cli-arguments.md
A partir do gráfico kube-state-metrics v2.13.3 (imagem kube-state-metrics v1.9.8 ), o gráfico oficial do Helm é mantido em prometheus-community/helm-charts. A partir do gráfico kube-state-metrics v3.0.0 apenas imagens kube-state-metrics de v2.0.0 + são suportadas.
Ao desenvolver, teste um dump de métrica em seu cluster Kubernetes local executando:
Os usuários podem substituir o endereço apiserver no arquivo KUBE-CONFIG com a linha de comando
--apiserver.
go install kube-state-metrics --port=8080 --telemetry-port=8081 --kubeconfig=<KUBE-CONFIG> --apiserver=<APISERVER>
Em seguida, enrole o endpoint das métricas
curl localhost:8080/metrics
Para executar os testes e2e localmente consulte a documentação em testes/README.md.
Ao desenvolver, existem certos padrões de código a serem seguidos para melhorar sua experiência de contribuição e a probabilidade de aprovação do e2e e de outros testes ci. Para saber mais sobre eles, consulte a documentação em docs/developer/guide.md.
Este projeto é patrocinado pela SIG Instrumentation.
Há também um canal para #kube-state-metrics no Slack do Kubernetes.
Você também pode ingressar na lista de discussão da SIG Instrumentation. Isso normalmente adicionará convites para as reuniões seguintes ao seu calendário, nas quais tópicos sobre métricas de estado do kube podem ser discutidos.
Reunião regular do SIG: quintas-feiras às 9h30 PT (horário do Pacífico) (quinzenalmente). Converta para o seu fuso horário.
Reunião Regular de Triagem: Quintas-feiras às 9h30 PT (Horário do Pacífico) (quinzenalmente - alternando com reunião regular). Converta para o seu fuso horário.
