Depois de implantar o Google Cloud Managed Service para Prometheus, você pode consultar os dados enviados ao serviço gerenciado e exibir os resultados em gráficos e painéis.
Neste documento, descrevemos os escopos de métricas, que determinam os dados que você pode consultar, e as seguintes maneiras de recuperar e usar os dados coletados baseadas no Prometheus:
- A API Prometheus HTTP
- A interface do Prometheus
Todas as interfaces de consulta do serviço gerenciado para o Prometheus são configuradas para recuperar dados do Monarch usando a API Cloud Monitoring. Ao consultar o Monarch em vez de consultar dados dos servidores locais do Prometheus, você tem o monitoramento global em escala.
Antes de começar
Se você ainda não implantou o serviço gerenciado, configure a coleção gerenciada ou a coleção autoimplantada. Pule isso se quiser apenas consultar métricas do Cloud Monitoring usando o PromQL.
Configurar o ambiente
Para evitar inserir repetidamente o ID do projeto ou o nome do cluster, execute a seguinte configuração:
Configure as ferramentas de linha de comando da seguinte maneira:
Configure a CLI gcloud para se referir ao ID do projeto do Google Cloud:
gcloud config set project PROJECT_ID
Configure a CLI
kubectl
para usar o cluster:kubectl config set-cluster CLUSTER_NAME
Para mais informações sobre essas ferramentas, consulte estes recursos:
Configurar um namespace
Crie o namespace NAMESPACE_NAME
do Kubernetes para os recursos que você criar
como parte do aplicativo de exemplo:
kubectl create ns NAMESPACE_NAME
Verificar as credenciais da conta de serviço
Pule essa seção se o cluster do Kubernetes tiver a Identidade da carga de trabalho ativada.
Quando executado no GKE, o Managed Service para Prometheus
recuperará automaticamente as credenciais do ambiente com base na
conta de serviço padrão do Compute Engine. A conta de serviço padrão tem as
permissões necessárias, monitoring.metricWriter
e monitoring.viewer
, por
padrão. Se você não usar a Identidade da carga de trabalho e tiver removido qualquer um desses papéis da conta de serviço do nó padrão, será necessário adicionar novamente essas permissões que faltam antes de continuar.
Se você não estiver executando no GKE, consulte Fornecer credenciais explicitamente.
Configurar uma conta de serviço para a Identidade da carga de trabalho
Você poderá pular esta seção se o cluster do Kubernetes não tiver a Identidade da carga de trabalho ativada.
O Managed Service para Prometheus captura dados de métricas usando a API Cloud Monitoring. Se o cluster estiver usando a identidade da carga de trabalho, você precisa conceder permissão à conta de serviço do Kubernetes para a API Monitoring. Esta seção descreve:
- Como criar uma conta de serviço dedicada do Google Cloud,
gmp-test-sa
. - Vincular a conta de serviço do Google Cloud à conta de serviço do
Kubernetes padrão em um namespace de teste,
NAMESPACE_NAME
. - Como conceder a permissão necessária à conta de serviço do Google Cloud.
Criar e vincular a conta de serviço
Essa etapa aparece em vários lugares na documentação do Managed Service para Prometheus. Se você já realizou esta etapa como parte de uma tarefa anterior, não é necessário repeti-la. Pule para Autorizar a conta de serviço.
A sequência de comandos a seguir cria a conta de serviço gmp-test-sa
e a vincula à conta de serviço padrão do Kubernetes no namespace NAMESPACE_NAME
:
gcloud config set project PROJECT_ID \ && gcloud iam service-accounts create gmp-test-sa \ && gcloud iam service-accounts add-iam-policy-binding \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \ gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \ && kubectl annotate serviceaccount \ --namespace NAMESPACE_NAME \ default \ iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
Se você estiver usando um namespace ou uma conta de serviço diferente do GKE, ajuste os comandos adequadamente.
Autorizar a conta de serviço
Grupos de permissões relacionadas são coletados em papéis, e você concede os papéis a um principal, neste exemplo, a conta de serviço do Google Cloud. Para mais informações sobre os papéis do Monitoring, consulte Controle de acesso.
O comando a seguir concede à conta de serviço do Google Cloud,
gmp-test-sa
, os papéis da API Monitoring necessários para
ler
dados de métricas.
Se você já concedeu à conta de serviço do Google Cloud um papel específico como parte da tarefa anterior, não é necessário fazer isso novamente.
Para autorizar a conta de serviço a ler um escopo de métricas de vários projetos, siga estas instruções e consulte alterar o projeto consultado.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/monitoring.viewer
Depurar a configuração da Identidade da carga de trabalho
Se você estiver com problemas para fazer a Identidade da carga de trabalho funcionar, consulte a documentação para verificar a configuração da Identidade da carga de trabalho e o Guia de solução de problemas da Identidade da carga de trabalho.
Como erros de digitação e cópias e colagens incompletas são as fontes mais comuns de erros ao configurar a Identidade da carga de trabalho, é altamente recomendável usar as variáveis editáveis e os ícones clicáveis de copiar/colar incorporados nos exemplos de código nestas instruções.
Identidade da carga de trabalho em ambientes de produção
O exemplo descrito neste documento vincula a conta de serviço do Google Cloud à conta de serviço padrão do Kubernetes e concede à conta de serviço do Google Cloud todas as permissões necessárias para usar a API Monitoring.
Em um ambiente de produção, convém usar uma abordagem mais refinada, com uma conta de serviço para cada componente, cada uma com permissões mínimas. Para mais informações sobre como configurar contas de serviço para gerenciamento de identidades de carga de trabalho, consulte Como usar a Identidade da carga de trabalho.
Escopos de consultas e métricas
Os dados que você pode consultar são determinados pelo escopo de métricas da construção do Cloud Monitoring, independentemente do método usado para consultar os dados. Por exemplo, se você usar o Grafana para consultar dados gerenciados pelo serviço do Prometheus, cada escopo de métricas precisará ser configurado como uma fonte de dados separada.
Um escopo de métricas do Monitoring é uma construção somente leitura que permite consultar dados de métricas pertencentes a vários projetos do Google Cloud. Cada escopo de métricas é hospedado por um projeto do Google Cloud designado, chamado de projeto de escopo.
Por padrão, um projeto é o projeto de escopo para o próprio escopo de métricas, e o escopo das métricas contém as métricas e a configuração desse projeto. Um projeto de escopo pode ter mais de um projeto monitorado no escopo de métricas, e as métricas e configurações de todos os projetos monitorados no escopo de métricas são visíveis para o projeto de escopo. Um projeto monitorado também pode pertencer a mais de um escopo de métricas.
Quando você consulta as métricas em um projeto, e se ele hospeda um escopo de métricas de vários projetos, é possível recuperar dados de vários projetos. Se o escopo das métricas contiver todos os projetos, as consultas e regras serão avaliadas globalmente.
Para mais informações sobre escopos e projetos de escopo, consulte Escopos de métricas. Para informações sobre como configurar um escopo de métricas de vários projetos, consulte Visualizar métricas de vários projetos.
Serviço gerenciado para dados do Prometheus no Cloud Monitoring
A maneira mais simples de verificar se os dados do Prometheus estão sendo exportados é usar a página do Metrics Explorer do Cloud Monitoring no console do Google Cloud, compatível com PromQL. Para instruções, veja Como consultar usando PromQL no Cloud Monitoring.
Interface de front-end do Prometheus independente
É possível usar a interface de front-end do Prometheus para acessar e visualizar dados ingeridos. Essa interface executa consultas PromQL em todos os dados do projeto do Google Cloud, conforme determinado pelo escopo das métricas associadas ao projeto.
A interface também funciona como um proxy de autenticação para acessar dados
ingeridos. Esse recurso pode ser usado em ferramentas de cliente que não são compatíveis com OAuth2
para contas de serviço,
incluindo Grafana ou escalonamento automático horizontal de pods usando a biblioteca
prometheus-adapter
.
É altamente recomendável configurar o Grafana para ver dados do Managed Service para Prometheus usando o sincronizador de fonte de dados. As instruções para configurar o Grafana usando a interface de front-end independente do Prometheus estão incluídas aqui como referência para usuários que já configuraram o Grafana usando esse método.
Implantar a interface de front-end
Para implantar a interface de front-end do Prometheus para o serviço gerenciado para o Prometheus, execute os seguintes comandos:
Implante o serviço
frontend
e configure-o para consultar o projeto de escopo do escopo de métricas de sua escolha:curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.10.0/examples/frontend.yaml | sed 's/\$PROJECT_ID/PROJECT_ID/' | kubectl apply -n NAMESPACE_NAME -f -
Encaminhe o serviço
frontend
para sua máquina local. O exemplo a seguir encaminha o serviço para a porta 9090:kubectl -n NAMESPACE_NAME port-forward svc/frontend 9090
Esse comando não retorna e, enquanto está em execução, informa acessos ao URL.
Se você quiser continuar usando uma implantação do Grafana instalada pelo kube-prometheus,
implante a interface do Prometheus no namespace monitoring
.
É possível acessar a interface de front-end do Prometheus no navegador
no URL http://localhost:9090
. Se você estiver usando o Cloud Shell nesta etapa, poderá
ter acesso usando o botão Visualização da Web.
A captura de tela a seguir mostra uma tabela na interface de front-end independente do Prometheus que exibe a métrica up
:
Também é possível configurar a autenticação e autorização adequadas no serviço frontend
usando, por exemplo, Identity-Aware Proxy.
Para mais informações sobre como expor serviços, consulte Como expor aplicativos usando serviços.
Alterar o projeto consultado para receber monitoramento de vários projetos
A implantação frontend
usa o projeto configurado do Google Cloud como o
projeto de escopo. Se este for o projeto de escopo de um escopo de métricas de vários projetos, ele poderá ler métricas de todos os projetos no escopo de métricas.
É possível especificar um projeto com um escopo de métricas de vários projetos usando a sinalização --query.project-id
.
Normalmente, um projeto dedicado é usado como projeto de escopo, e este projeto não é o mesmo em que a implantação frontend
é executada.
Para permitir que a implantação leia um projeto de destino diferente, faça o seguinte:
- Informe à implementação de
frontend
qual é o projeto de destino. Conceda permissão à conta de serviço para ler o projeto de destino. Se você estiver usando a conta de serviço
default
do Compute Engine, poderá seguir um destes procedimentos:Ative a identidade da carga de trabalho para o cluster e siga as etapas de configuração.
Forneça uma chave de conta de serviço explícita.
Para conceder as permissões necessárias para acessar um projeto diferente do Google Cloud, faça o seguinte:
Conceda permissão à conta de serviço para ler o projeto de destino que você quer consultar:
gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \ --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/monitoring.viewer
Abra a implantação
frontend
criada anteriormente para edição:kubectl -n NAMESPACE_NAME edit deploy frontend
Especifique o projeto de destino usando a sinalização
--query.project-id
:apiVersion: apps/v1 kind: Deployment metadata: namespace: NAMESPACE_NAME name: frontend spec: template containers: - name: frontend args: - --query.project-id=SCOPING_PROJECT_ID ...
Salve o arquivo e feche o editor. Depois que a alteração é aplicada, os pods de front-end são reiniciados e consultam o novo projeto de escopo.
Autenticar a interface de front-end
A implantação frontend
oferece suporte à
autenticação básica de acesso
para acesso autenticado nas versões 0.5.0 e mais recentes. Para ativar a autenticação,
adicione as variáveis de ambiente AUTH_USERNAME
e AUTH_PASSWORD
à
implantação:
apiVersion: apps/v1 kind: Deployment metadata: namespace: NAMESPACE_NAME name: frontend spec: template containers: - name: frontend env: - name: AUTH_USERNAME value: USERNAME - name: AUTH_PASSWORD value: PASSWORD ...
Fornecer credenciais explicitamente
É possível pular esta seção se você estiver executando o contêiner frontend
em um cluster do Google Kubernetes Engine. Se você estiver com problemas de autenticação no GKE, consulte Verificar as credenciais da conta de serviço.
Durante a execução no GKE, o front-end recupera as credenciais automaticamente do ambiente com base na conta de serviço do nó ou na configuração da identidade da carga de trabalho.
Em clusters do Kubernetes que não são do GKE, as credenciais precisam ser explicitamente fornecidas ao front-end usando sinalizações ou a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
.
Defina o contexto para seu projeto de destino:
gcloud config set project PROJECT_ID
Crie uma conta de serviço:
gcloud iam service-accounts create gmp-test-sa
Nesta etapa, é criada a conta de serviço que você pode já tiver criado nas instruções de Identidade da carga de trabalho.
Conceda as permissões necessárias à conta de serviço:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/monitoring.viewer
Crie e faça o download de uma chave para a conta de serviço:
gcloud iam service-accounts keys create gmp-test-sa-key.json \ --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
Adicione o arquivo de chave como secret ao cluster que não é do GKE:
kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \ --from-file=key.json=gmp-test-sa-key.json
Abra o recurso de implantação de front-end para edição:
kubectl -n NAMESPACE_NAME edit deploy frontend
Adicione o texto exibido em negrito ao recurso:
apiVersion: apps/v1 kind: Deployment metadata: namespace: NAMESPACE_NAME name: frontend spec: template containers: - name: frontend args: - --query.credentials-file=/gmp/key.json ... volumeMounts: - name: gmp-sa mountPath: /gmp readOnly: true ... volumes: - name: gmp-sa secret: secretName: gmp-test-sa ...
Salve o arquivo e feche o editor. Depois que a alteração é aplicada, os pods são recriados e começam a autenticar no back-end da métrica com a conta de serviço especificada.
GOOGLE_APPLICATION_CREDENTIALS
.Como usar o Grafana pelo proxy de front-end
O serviço gerenciado para Prometheus usa a fonte de dados integrada do Prometheus para o Grafana, o que significa que você pode continuar usando os painéis pessoais ou criados pela comunidade do Grafana sem alterações. Também é possível importar os painéis do Grafana para o Cloud Monitoring.
Como autenticar nas APIs do Google Cloud
Todas as APIs do Google Cloud exigem autenticação com OAuth2. No entanto, o Grafana não oferece suporte à autenticação OAuth2 para contas de serviço usadas com fontes de dados do Prometheus. Para usar o Grafana com o Managed Service para Prometheus, use a interface de front-end independente do Prometheus como proxy de autenticação.
Você precisa apontar o Grafana no proxy de interface de front-end autônomo para consultar os dados globalmente. Se você não seguir essas etapas, o Grafana só executará consultas nos dados do servidor local do Prometheus.
Se você ainda não tiver implantado o serviço da interface Prometheus
frontend
como um proxy, implante-o agora executando o seguinte comando:curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.10.0/examples/frontend.yaml | sed 's/\$PROJECT_ID/PROJECT_ID/' | kubectl apply -n NAMESPACE_NAME -f -
Para clusters do Kubernetes que não são do GKE, como clusters do Anthos, consulte também Fornecer credenciais explicitamente para conceder ao serviço
frontend
as permissões necessárias para consultar métricas.Consulte alterar o projeto consultado para saber como configurar o escopo de métricas usado pelo serviço
frontend
para consultar vários projetos.Se você tiver uma implantação do Grafana, como uma instalada pela biblioteca
kube-prometheus
ou uma instalada com um gráfico de helm, poderá continuar usando-a com o serviço gerenciado para Prometheus. Nesse caso, consulte Configurar uma fonte de dados para ver as próximas etapas. Caso contrário, primeiro implante o Grafana.Implante o Grafana
Se você não tiver uma implantação do Grafana em execução no cluster, será possível criar uma implantação de teste temporária para fazer experimentos.
Para criar uma implantação temporária do Grafana, aplique o manifesto
grafana.yaml
do serviço gerenciado para o Prometheus ao cluster e encaminhe o serviçografana
para a máquina local. O exemplo a seguir encaminha o serviço para a porta 3000.Aplique o manifesto
grafana.yaml
:kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/beb779d32f4dd531a3faad9f2916617b8d9baefd/examples/grafana.yaml
Encaminhe o serviço
grafana
para sua máquina local. Este exemplo encaminha o serviço para a porta 3000:kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
Esse comando não retorna e, enquanto está em execução, informa acessos ao URL.
É possível acessar o Grafana no navegador, no URL
http://localhost:3000
, com o username:passwordadmin:admin
.
Configure uma fonte de dados
Para consultar o Managed Service para Prometheus no Grafana usando a interface do Prometheus como proxy de autenticação, é preciso adicionar uma nova fonte de dados ao Grafana. Para adicionar uma fonte de dados ao serviço gerenciado, faça o seguinte:
Acesse sua implantação do Grafana, por exemplo, navegando até o URL
http://localhost:3000
para acessar a página de boas-vindas do Grafana.Selecione Configuração no menu principal do Grafana e selecione Fontes de dados.
Selecione Adicionar fonte de dados e selecione o Prometheus como o banco de dados de séries temporais.
No campo URL do painel HTTP, insira o URL do serviço gerenciado para o Prometheus
frontend
. Se você configurou a interface do Prometheus para ser executada na porta 9090, o URL de serviço desse campo seráhttp://frontend.NAMESPACE_NAME.svc:9090
.No campo Tempo limite do painel HTTP, defina o valor como
120
.Se você tiver configurado a interface de front-end com a autenticação básica, ative a chave Autenticação básica no painel Autenticação e preencha o nome de usuário e a senha.
No campo Tempo limite da consulta, defina o valor como
2m
.No campo Método HTTP, selecione
GET
.No campo Prometheus type, selecione
Prometheus
.No campo Versão do Prometheus, selecione
2.40.x
ou uma versão mais recente.Se você tiver várias fontes de dados do Prometheus, poderá dar a ela um nome como "Serviço gerenciado do Prometheus". Não altere os valores padrão dos outros campos.
Clique em Salvar e testar e procure a mensagem "A fonte de dados está funcionando".
Usar a nova fonte de dados
Agora é possível criar painéis do Grafana usando a nova fonte de dados. Também é possível redirecionar painéis existentes para a nova fonte de dados. A captura de tela a seguir mostra um gráfico do Grafana que exibe a métrica
up
:Como conectar o Managed Service para Prometheus ao Thanos
É possível federar o Managed Service para Prometheus em uma pilha Thanos autoimplantada usando o thanos-promql-connector de código aberto. O Google Cloud não oferece suporte para essa integração.
API Prometheus HTTP
O serviço gerenciado para o Prometheus é compatível com a API Prometheus HTTP do upstream no URL prefixado por
https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/
. Para informações sobre os endpoints compatíveis, consulte Compatibilidade da API.Essa API pode ser acessada por qualquer ferramenta que interaja com um servidor Prometheus padrão. Esse é apenas um endpoint da API. ele não exibe uma IU. Como uma API do Google Cloud, a API usa a autenticação OAuth2 e, como parte da API Cloud Monitoring, o valor de
PROJECT_ID
é o projeto de escopo de um escopo de métricas. Assim, é possível recuperar dados de qualquer projeto no escopo das métricas. Para mais informações sobre o escopo, consulte Escopos de métricas.Para usar esse endpoint, forneça uma expressão PromQL. Por exemplo, a consulta instantânea a seguir recupera todas as séries temporais que têm o nome da métrica
up
:curl https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/query \ -d "query=up" \ -H "Authorization: Bearer $(gcloud auth print-access-token)"
Se a solicitação for bem-sucedida, a consulta retornará um resultado como o seguinte, que foi formatado para legibilidade:
{ "status":"success", "data":{ "resultType":"vector", "result":[{ "metric": { "__name__":"up", "cluster":"gmp-test", "instance":"prom-example-84c6f547f5-g4ljn:web", "job":"prometheus", "location":"us-central1-a", "project_id":"a-gcp-project" }, "value": [1634873239.971,"1"] }] } }
Para mais informações sobre como consultar as métricas do sistema do Google Cloud usando o PromQL, consulte PromQL para métricas do Cloud Monitoring.
Compatibilidade de API
Os endpoints da API Prometheus HTTP a seguir são compatíveis com o serviço gerenciado para o Prometheus com o URL prefixado por
https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/
.Para ter acesso à documentação completa, consulte a documentação de referência da API Cloud Monitoring.
Para ver informações sobre a compatibilidade com o PromQL, consulte Compatibilidade com o PromQL (em inglês).
Os endpoints a seguir são totalmente compatíveis:
/api/v1/query
/api/v1/query_range
/api/v1/metadata
/api/v1/labels
/api/v1/query_exemplars
O endpoint
/api/v1/label/<label_name>/values
só funciona se o rótulo__name__
for fornecido usando-o como o valor<label_name>
ou correspondendo exatamente a ele usando um seletor de série. Por exemplo, as seguintes chamadas são totalmente compatíveis:/api/v1/label/__name__/values
/api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
/api/v1/label/labelname/values?match[]={__name__="metricname"}
Essa limitação causa falhas nas consultas de variáveis
label_values($label)
no Grafana. Em vez disso, uselabel_values($metric, $label)
. Esse tipo de consulta é recomendado porque evita buscar valores de rótulos em métricas que não são relevantes para o painel fornecido.O endpoint
/api/v1/series
é compatível com solicitaçõesGET
, mas nãoPOST
. Quando você usa o sincronizador de fonte de dados ou o proxy de front-end, essa restrição é gerenciada para você. Também é possível configurar as fontes de dados do Prometheus no Grafana para que emitam apenas solicitaçõesGET
.