Primeiros passos com a coleção autoimplantada

Neste documento, descrevemos como configurar o Google Cloud Managed Service para Prometheus com a coleção autoimplantada. Um aplicativo de exemplo é implantado em um cluster do Kubernetes e é monitorado por um servidor Prometheus que armazena métricas coletadas no Monarch.

Esta página mostra como fazer o seguinte:

  • Configure o ambiente e as ferramentas de linha de comando.
  • Configurar uma conta de serviço para clusters ativados para Identidade da carga de trabalho.
  • Execute o binário do Prometheus no Kubernetes.
  • Controle quais métricas são ingeridas no Managed Service para Prometheus.
  • Integre o Managed Service para Prometheus com configurações de prometheus-operator.
  • Compile e execute manualmente o binário do Prometheus.

Com a coleta de dados autoimplantada, você gerencia a instalação do Prometheus como sempre fez. A única diferença é que você executa o binário de substituição do Managed Service para Prometheus no gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0, em vez do binário upstream do Prometheus.

O binário drop-in fornece outras opções de configuração com as flags --export.*. Para mais informações, consulte a saída da opção --help. Este documento destaca as opções mais importantes.

O Managed Service para Prometheus não aceita a exportação de métricas de um servidor de federação ou de um servidor usado como receptor de gravação remota. É possível replicar toda a funcionalidade do servidor de federação, incluindo a redução do volume de ingestão. Basta agregar dados antes de enviar para o Monarch, usando filtros e agregações locais.

O streaming de dados para o Managed Service para Prometheus consome recursos adicionais. Se você estiver implantando coletores, recomendamos aumentar os limites de CPU e memória em cinco vezes e ajustá-los com base no uso real.

Para mais informações sobre coleta de dados gerenciada e autoimplantada, consulte Coleta de dados com o Managed Service para Prometheus.

Antes de começar

Nesta seção, descrevemos a configuração necessária para as tarefas descritas neste documento.

Configurar projetos e ferramentas

Para usar o Google Cloud Managed Service para Prometheus, você precisa dos seguintes recursos:

  • Um projeto do Google Cloud com a API Cloud Monitoring ativada.

    • Se você não tiver um projeto do Cloud, faça o seguinte:

      1. No console, acesse Novo projeto:

        Crie um novo projeto

      2. No campo Project Name, insira um nome para o projeto e clique em Criar.

      3. Acesse o Faturamento:

        Acessar "Faturamento"

      4. Selecione o projeto recém-criado se ele ainda não estiver selecionado na parte superior da página.

      5. Você precisará escolher um perfil para pagamentos atual ou criar um novo.

      A API Monitoring é ativada por padrão para novos projetos.

    • Se você já tem um projeto do Cloud, verifique se a API Monitoring está ativada:

      1. Acessar APIs e serviços

        Acessar APIs e serviços

      2. Selecione o projeto.

      3. Clique em Ativar APIs e serviços.

      4. Pesquise "Monitoring".

      5. Nos resultados da pesquisa, clique em "API Cloud Monitoring".

      6. Se a opção "API ativada" não for exibida, clique no botão Ativar.

  • Um cluster do Kubernetes. Se você não tiver um cluster do Kubernetes, siga as instruções no Guia de início rápido do GKE.

Você também precisa das seguintes ferramentas de linha de comando:

  • gcloud
  • kubectl

As ferramentas gcloud e kubectl fazem parte da Google Cloud CLI. Para mais informações sobre como instalá-los, consulte Como gerenciar componentes da CLI do Google Cloud. Para ver os componentes da CLI gcloud que você instalou, execute o seguinte comando:

gcloud components list

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 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 gmp-test do Kubernetes para os recursos que você criar como parte do aplicativo de exemplo:

kubectl create ns gmp-test

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 ausentes 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:

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á executou essa 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 gmp-test:

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[gmp-test/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace gmp-test \
  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 gravar 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.

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

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 toda a permissão necessária 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.

Configurar a coleção autoimplantada

Nesta seção, descrevemos como configurar e executar um aplicativo de exemplo que usa a coleção autoimplantada.

Implantar o aplicativo de exemplo

O serviço gerenciado fornece um manifesto para um aplicativo de exemplo que emite métricas do Prometheus na porta metrics. O aplicativo usa três réplicas.

Para implantar o aplicativo de exemplo, execute o seguinte comando:

kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.3-gke.0/examples/example-app.yaml

Executar o binário substituto do Prometheus

Para ingerir os dados de métrica emitidos pelo aplicativo de exemplo, implante a versão ramificada do Google do servidor Prometheus, configurada para coletar as métricas da carga de trabalho e o próprio endpoint de métricas.

  1. Para implantar o servidor ramificado, execute o seguinte comando:

    kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.4.3-gke.0/examples/prometheus.yaml
    

    O servidor Prometheus implantado é uma pequena ramificação do binário upstream do Prometheus. Ele se comporta como um servidor Prometheus padrão, mas também ingere dados no Managed Service para Prometheus.

    O manifesto acima fornece apenas um exemplo básico de trabalho e não armazena dados de forma persistente. Para informações sobre como a configuração predefinida funciona e como ampliá-la, consulte a documentação de configuração do Prometheus de código aberto.

    A imagem predefinida só funciona em nós do Linux. Para raspar os dados dos destinos em execução nos nós do Windows, implante o servidor em um nó do Linux e configure-o para raspar dados de endpoints nos nós do Windows ou crie o binário para o Windows por conta própria.

  2. Verifique se os pods do servidor do Prometheus e do aplicativo de exemplo foram implantados com sucesso:

    kubectl -n gmp-test get pod
    

    Se a implantação tiver sido bem-sucedida, você verá uma saída semelhante a esta:

    NAME                            READY   STATUS    RESTARTS   AGE
    prom-example-84c6f547f5-fglbr   1/1     Running   0          5m
    prom-example-84c6f547f5-jnjp4   1/1     Running   0          5m
    prom-example-84c6f547f5-sqdww   1/1     Running   0          5m
    prometheus-test-0               2/2     Running   1          3m
    

Se você estiver executando no GKE, faça o seguinte:

Se você estiver executando fora do GKE, será necessário criar uma conta de serviço e autorizá-la a gravar seus dados de métrica, conforme descrito na seção a seguir.

Fornecer credenciais explicitamente

Durante a execução no GKE, o servidor de coleta do Prometheus recupera automaticamente as credenciais do ambiente com base na conta de serviço padrão do Compute Engine ou na configuração da identidade da carga de trabalho.

Em clusters que não são do Kubernetes, as credenciais precisam ser explicitamente fornecidas ao servidor de coleta do Prometheus usando sinalizações ou a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

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

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

  3. 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
    
  4. Adicione o arquivo de chave como secret ao cluster que não é do GKE:

    kubectl -n gmp-test create secret generic gmp-test-sa \
      --from-file=key.json=gmp-test-sa-key.json
    

  5. Abra o recurso do StatefulSet do Prometheus para edição:

    kubectl -n gmp-test edit statefulset prometheus-test
    

  6. Adicione o texto exibido em negrito ao recurso:

    apiVersion: apps/v1
    kind: StatefulSet
    metadata:
      namespace: gmp-test
      name: example
    spec:
      template
        containers:
        - name: prometheus
          args:
          - --export.credentials-file=/gmp/key.json
    ...
          volumeMounts:
          - name: gmp-sa
            mountPath: /gmp
            readOnly: true
    ...
        volumes:
        - name: gmp-sa
          secret:
            secretName: gmp-test-sa
    ...
    

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

Como alternativa, em vez de usar as sinalizações definidas neste exemplo, defina o caminho do arquivo de chave usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Tópicos adicionais para coleção autoimplantada

Esta seção explica como fazer o seguinte:

  • Filtre os dados exportados para o serviço gerenciado.
  • Converta as configurações de implantação atuais.
  • Execute o binário do Prometheus no modo de alta disponibilidade.
  • Crie e execute o binário de substituição do Prometheus.
  • Execute o Managed Service para Prometheus fora do Google Cloud.

Filtrar métricas exportadas

Se você coletar muitos dados, convém evitar que algumas séries temporais sejam enviadas ao Managed Service para Prometheus, para manter os custos baixos.

Você pode usar configurações regulares de remarcação de métricas na configuração de extração do Prometheus. Com a remarcação de configurações, é possível descartar métricas com base em correspondências de rótulos no momento da ingestão.

Às vezes, você pode ingerir dados localmente, mas não exportá-los para o Managed Service para Prometheus. Para filtrar as métricas exportadas, use a sinalização --export.match.

A sinalização especifica um ou mais seletores de série PromQL, e a sinalização pode ser usada várias vezes. Uma série temporal será exportada para o Managed Service para Prometheus se ela atender a todos os seletores em pelo menos uma das sinalizações. ou seja, ao determinar a qualificação, as condições em uma única sinalização são AND, enquanto as condições em sinalizações separadas são definidas como OR. O exemplo a seguir usa duas instâncias da sinalização:

./prometheus \
  --export.match='{job="prometheus"}' \
  --export.match='{__name__=~"job:.+"}' \
  ...

Essa alteração faz com que apenas as métricas do job "prometheus" e as métricas produzidas pelo registro de regras agregadas para o job (seguindo práticas recomendadas de nomenclatura) sejam exportadas. As amostras de todas as outras séries são filtradas. Por padrão, nenhum seletor é especificado, e todas as séries temporais são exportadas.

A sinalização --export.match tem a mesma semântica do parâmetro match[] para a federação Prometheus. Portanto, é possível migrar as configurações de federação para o Managed Service para Prometheus usando os seletores do servidor de federação diretamente como sinalizações nos servidores do Prometheus copiados pelo servidor da Federação do Prometheus. Não é possível exportar métricas de um servidor de federação para o serviço gerenciado..

É possível combinar sinalizações de filtro com regras de gravação executadas localmente para "consolidar dados" antes de enviar para o Monarch, reduzindo a cardinalidade e o custo. Para mais informações, consulte Controles de custo e atribuição.

Usar com o prometheus-operator

O binário do Prometheus do Managed Service para Prometheus também pode ser usado com uma implantação atual do GKE do Prometheus gerenciada pelo prometheus-operator.

Para usar o binário do serviço gerenciado, substitua a especificação da imagem no recurso do Prometheus:

  apiVersion: monitoring.coreos.com/v1
  kind: Prometheus
  metadata:
    name: gmp-test
    namespace: gmp-system
  spec:
    image: gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0
    ...
    replicas: 1
    serviceAccountName: default
    version: v2.35.0
    ...

Se você estiver em um cluster de Identidade de carga de trabalho e a namespace ou conta de serviço no recurso for diferente, repita as instruções de Identidade de carga de trabalho para o par extra de namespace e conta de serviço do Kubernetes.

Ao executar em um cluster Kubernetes que não seja do GKE, você precisará fornecer credenciais manualmente. Para fornecer credenciais, faça o seguinte:

  1. Adicione um arquivo de chave de conta de serviço apropriado como secret, conforme descrito em Enviar credenciais explicitamente.

  2. Modifique o recurso do Prometheus para adicionar o texto exibido em negrito:

      apiVersion: monitoring.coreos.com/v1
      kind: Prometheus
      metadata:
        namespace: gmp-test
        name: example
      spec:
        ...
        secrets:
        - gmp-test-sa
        containers:
        - name: prometheus
          env:
          - name: GOOGLE_APPLICATION_CREDENTIALS
            value: /gmp/key.json
          volumeMounts:
          - name: secret-gmp-test-sa
            mountPath: /gmp
            readOnly: true
    

É possível definir a variável de ambiente EXTRA_ARGS do contêiner para adicionar outras sinalizações, como as sinalizações de filtragem de métrica. Isso é feito usando uma variável de ambiente porque a seção args da especificação do contêiner é gerenciada pelo Prometheus Operator.

Usar com kube-prometheus

É possível configurar as implantações usando a famosa biblioteca kube-prometheus para usar o Managed Service para Prometheus.

O kube-prometheus tem algumas dependências internas rígidas nos namespaces e contas de serviço padrão. Portanto, recomendamos apenas a alteração do número mínimo de campos necessários para enviar dados para o Managed Service para Prometheus.

Em manifests/prometheus-prometheus.yaml, substitua a especificação da imagem e desative a coleta de alta disponibilidade reduzindo replicas para 1:

    apiVersion: monitoring.coreos.com/v1
    kind: Prometheus
    ...
    spec:
      image: gke.gcr.io/prometheus-engine/prometheus:v2.35.0-gmp.2-gke.0
      ...
      replicas: 1
      version: v2.35.0
      ...
  

Se você estiver executando no GKE e não tiver modificado a conta de serviço padrão no nó, a aplicação dos manifestos modificados começará imediatamente a enviar dados ao Managed Service para Prometheus. Caso contrário, talvez seja necessário configurar e aplicar uma conta de serviço. Quando executado no GKE e usando a identidade da carga de trabalho, talvez seja necessário criar e autorizar a conta de serviço prometheus-k8s no namespace monitoring. Quando executado em um cluster do Kubernetes que não é do GKE, siga as instruções na seção do prometheus-operator.

Observe que o kube-prometheus coleta muitas métricas por padrão, que geralmente não são necessárias em um ambiente gerenciado do Kubernetes, como o GKE. Para economizar nos custos de processamento, personalize o kube-prometheus para que ele extraia apenas as métricas importantes para você e filtre as métricas exportadas de forma agressiva.

Para mais sugestões, consulte Atribuição e controles de custo.

Implantação de alta disponibilidade

O binário substituto do Prometheus vem com suporte integrado para coleta altamente disponível usando a eleição de líder. Os servidores replicados do Prometheus no modo de alta disponibilidade coletam métricas e avaliam regras como de costume, mas apenas um deles envia dados ao Google Cloud Managed Service para Prometheus.

As réplicas do mesmo servidor Prometheus sempre precisam ter configurações idênticas, incluindo o mesmo external_labels. Esse requisito é diferente de outros sistemas, que contam com um rótulo externo especial, como __replica__, para tornar as réplicas explicitamente diferentes.

O servidor da API Kubernetes é um back-end de eleição de líder compatível e pode ser ativado definindo as seguintes sinalizações:

./prometheus
  ...
  --export.ha.backend=kube \
  --export.ha.kube.namespace=LEASE_NAMESPACE \
  --export.ha.kube.name=LEASE_NAME

Os valores LEASE_NAMESPACE e LEASE_NAME identificam o recurso de locação em que a eleição de líder ocorre. Todos os servidores do Prometheus que apontam para o mesmo recurso pertencem ao mesmo conjunto de réplicas. A conta de serviço do Kubernetes da implantação do Prometheus precisa de permissão para ler e gravar o respectivo recurso de Lease. Ao executar o servidor Prometheus fora de um cluster do Kubernetes, é possível fornecer um config explícito usando a sinalização --export.ha.kube.config.

Implantações binárias

Se você quiser executá-lo em um ambiente não contentorizado, crie o binário substituto do Prometheus diretamente.

Como criar a origem

Se você já tiver um processo para compilar o Prometheus, substitua com transparência o repositório do GitHub no processo. O Managed Service para Prometheus tem a própria extensão de tag de versão para distinguir as versões das versões upstream.

Para criar o binário simples, o conjunto de ferramentas Go e as versões recentes do NPM/Yarn precisam ser instalados na máquina. Para saber mais, consulte as instruções de criação de upstream.

  1. Clone o repositório:

    git clone https://github.com/GoogleCloudPlatform/prometheus &&
    cd prometheus
    
  2. Confira a tag da versão pretendida:

    git checkout v2.35.0-gmp.2
    
  3. Para criar um tarball do Managed Service para Prometheus, execute os seguintes comandos:

    make build && make tarball
    

O tarball e os binários resultantes são totalmente compatíveis com suas variantes upstream em termos de estrutura e funcionalidade de diretório.

Executar uma coleta autoimplantada fora do Google Cloud

Em ambientes do Compute Engine, em ambientes do GKE ou em uma máquina em que você executou gcloud login com uma conta autorizada, é possível executar a coleta autoimplantada sem configuração adicional. Fora do Google Cloud, é necessário fornecer credenciais explicitamente, um project_id para conter suas métricas e um location (região do Google Cloud) para armazenar as métricas.

É possível fornecer uma chave de conta de serviço usando a sinalização --export.credentials-file ou a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, conforme descrito em Fornecer credenciais explicitamente.

Recomendamos escolher project_id com base no modelo de locação planejada para leituras. Escolha um projeto para armazenar métricas com base na forma como você planeja organizar as leituras posteriormente por escopos de métricas. Se não se importar, você pode colocar tudo em um projeto.

Para location, é recomendável escolher a região do Google Cloud mais próxima da implantação. Quanto mais distante a região escolhida do Google Cloud estiver da implantação, mais será a latência de gravação e o impacto por possíveis problemas de rede. Consulte esta lista de regiões em várias nuvens. Se você não se importar, poderá colocar tudo em uma única região do Google Cloud. Não é possível usar global como local.

Para um exemplo mínimo, execute um binário Prometheus de automonitoramento local com o seguinte comando:

./prometheus \
  --config.file=documentation/examples/prometheus.yaml \
  --export.label.project-id=PROJECT_ID \
  --export.label.location=ZONE \

Neste exemplo, presumimos que você definiu a variável ZONE como um valor como us-central1-b, por exemplo.

No entanto, recomendamos que você defina os rótulos de destino export para o serviço gerenciado na seção global.external_labels da sua configuração do Prometheus. Por exemplo:

global:
  external_labels:
    project_id: PROJECT_ID
    location: ZONE
    namespace: local-testing

scrape_configs:
  ...

A execução do Managed Service para Prometheus fora do Google Cloud gera taxas de entrada de dados e pode ser cobrada por taxas de saída de dados se a execução for em outra nuvem. Para minimizar esse custo, ative a compactação com a sinalização --export.compression=gzip.

A seguir