Consulta mediante Grafana

Después de implementar Google Cloud Managed Service para Prometheus, puedes consultar los datos enviados al servicio administrado y mostrar los resultados en gráficos y paneles.

En este documento, se describen los permisos de métricas, que determinan los datos que puedes consultar, y cómo usar Grafana para recuperar y usar los datos que recopilaste.

Todas las interfaces de consulta de los servicios administrados para Prometheus están configuradas a fin de recuperar datos de Monarch mediante la API de Cloud Monitoring. Cuando consultas Monarch en lugar de consultar datos desde servidores locales de Prometheus, obtienes supervisión global a gran escala.

Antes de comenzar

Si aún no implementaste el servicio administrado, configura la colección administrada o la colección autoimplementada. Puedes omitirlo si solo te interesa consultar las métricas de Cloud Monitoring mediante PromQL.

Configura tu entorno

Para evitar ingresar repetidamente el ID del proyecto o el nombre del clúster, realiza la siguiente configuración:

  • Configura las herramientas de línea de comandos como se indica a continuación:

    • Configura la CLI de gcloud para hacer referencia al ID del proyecto de Google Cloud:

      gcloud config set project PROJECT_ID

    • Configura la CLI de kubectl para usar tu clúster:

      kubectl config set-cluster CLUSTER_NAME

    Para obtener más información sobre estas herramientas, consulta lo siguiente:

Configura un espacio de nombres

Crea el espacio de nombres NAMESPACE_NAME de Kubernetes para los recursos que crees como parte de la aplicación de ejemplo:

kubectl create ns NAMESPACE_NAME

Verifica las credenciales de la cuenta de servicio

Puedes omitir esta sección si tu clúster de Kubernetes tiene habilitada Workload Identity.

Cuando se ejecuta en GKE, el servicio administrado para Prometheus recupera credenciales de forma automática del entorno en función de la cuenta de servicio predeterminada de Compute Engine. La cuenta de servicio predeterminada tiene los permisos necesarios, monitoring.metricWriter y monitoring.viewer, de forma predeterminada. Si no usas Workload Identity y ya quitaste cualquiera de esas funciones de la cuenta de servicio de nodo predeterminada, tendrás que volver a agregar esos permisos faltantes antes de continuar.

Si no ejecutas en GKE, consulta Proporciona credenciales explícitamente.

Configura una cuenta de servicio para Workload Identity

Puedes omitir esta sección si tu clúster de Kubernetes no tiene habilitada Workload Identity.

El servicio administrado para Prometheus captura datos de métricas mediante la API de Cloud Monitoring. Si tu clúster usa Workload Identity, debes otorgar permiso a tu cuenta de servicio de Kubernetes a la API de Monitoring. En esta sección, se describe lo siguiente:

Crea y vincula la cuenta de servicio

Este paso aparece en varios lugares en la documentación del servicio administrado para Prometheus. Si ya realizaste este paso como parte de una tarea anterior, no es necesario que lo repitas. Ve a la sección Autoriza la cuenta de servicio.

Con la siguiente secuencia de comandos, se crea la cuenta de servicio gmp-test-sa y se la vincula a la cuenta de servicio de Kubernetes predeterminada en el espacio de nombres 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

Si usas un espacio de nombres o una cuenta de servicio de GKE diferentes, ajusta los comandos de forma adecuada.

Autoriza la cuenta de servicio

Los grupos de permisos relacionados se recopilan en funciones y se otorgan las funciones a una principal, en este ejemplo, la cuenta de servicio de Google Cloud. Para obtener más información sobre las funciones de Monitoring, consulta Control de acceso.

Con el siguiente comando, se otorga a la cuenta de servicio de Google Cloud, gmp-test-sa, las funciones de la API de Monitoring que necesita para leer datos de métricas.

Si ya otorgaste a la cuenta de servicio de Google Cloud una función específica como parte de la tarea anterior, no necesitas volver a hacerlo.

Para autorizar tu cuenta de servicio a fin de que lea desde un alcance de métricas de varios proyectos, sigue estas instrucciones y, luego, consulta Cambia el proyecto consultado. 

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

Depura la configuración de Workload Identity

Si tienes problemas para lograr que Workload Identity funcione, consulta la documentación a fin de verificar la configuración de Workload Identity y la Guía de solución de problemas de Workload Identity.

Como los errores tipográficos y de copia parcial son las fuentes de errores más comunes en la configuración de Workload Identity, recomendamos usar las variables editables y los íconos de copiar y pegar en los que se puede hacer clic incorporados en las muestras de código de estas instrucciones.

Workload Identity en entornos de producción

En el ejemplo descrito en este documento, se vincula la cuenta de servicio de Google Cloud a la cuenta de servicio de Kubernetes predeterminada y se le otorga a la cuenta de servicio de Google Cloud todos los permisos necesarios para usar la API de Monitoring.

En un entorno de producción, se recomienda usar un enfoque más detallado, con una cuenta de servicio para cada componente, cada una con permisos mínimos. Si deseas obtener más información sobre la configuración de cuentas de servicio para la administración de identidades de cargas de trabajo, consulta Usa Workload Identity.

Permisos de las consultas y las métricas

Los datos que puedes consultar se determinan por el permiso de las métricas de construcción de Cloud Monitoring, independientemente del método que uses para consultar los datos. Por ejemplo, si usas Grafana para consultar el servicio administrado de datos de Prometheus, cada permiso de métrica debe configurarse como una fuente de datos independiente.

El alcance de las métricas de Monitoring es una construcción de solo lectura que te permite consultar datos de métricas que pertenecen a varios proyectos de Google Cloud. Cada permiso de métricas está alojado en un proyecto de Google Cloud designado, llamado proyecto de permisos.

De forma predeterminada, un proyecto es el proyecto de permisos para su propio permiso de métricas, y el permiso de métricas contiene las métricas y la configuración de ese proyecto. Un proyecto de permisos puede tener más de un proyecto supervisado en su permiso, y las métricas y configuraciones de todos los proyectos supervisados en el alcance de las métricas son visibles para el proyecto de permisos. Un proyecto supervisado también puede pertenecer a más de un permiso de métricas.

Cuando consultas las métricas de un proyecto de permisos y si ese proyecto aloja un permiso de métricas de varios proyectos, puedes recuperar datos de varios proyectos. Si tu permiso de métricas contiene todos tus proyectos, tus consultas y reglas se evalúan a nivel global.

Para obtener más información sobre los proyectos de permisos y los permisos de métricas, consulta Permisos de las métricas. Si deseas obtener información para configurar un permiso de métricas de varios proyectos, consulta Visualiza métricas de varios proyectos.

Datos de Managed Service para Prometheus en Cloud Monitoring

La forma más sencilla de comprobar que se exportan los datos de Prometheus es usar la página del Explorador de métricas de Cloud Monitoring en la consola de Google Cloud, que admite PromQL. Para obtener instrucciones, visita Consulta con PromQL en Cloud Monitoring.

También puedes importar tus paneles de Grafana a Cloud Monitoring. Esto te permite seguir usando los paneles Grafana creados por la comunidad o personales sin tener que configurar o implementar una instancia de Grafana.

Grafana

El servicio administrado para Prometheus usa la fuente de datos integrada de Prometheus para Grafana, lo que significa que puedes seguir usando cualquier panel de Grafana creado por la comunidad o personal sin ningún cambio.

Implementa Grafana, si es necesario

Si no tienes una implementación de Grafana en ejecución en tu clúster, puedes crear una implementación de prueba efímera para experimentar.

A fin de crear una implementación efímera de Grafana, aplica el manifiesto grafana.yaml del servicio administrado para Prometheus a tu clúster y redirecciona el servicio grafana a tu máquina local. En el siguiente ejemplo, se reenvía el servicio al puerto 3000.

  1. Aplica el manifiesto grafana.yaml:

    kubectl -n NAMESPACE_NAME apply -f  https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/6ebc1afa8e609febe8d687bb7fa6bd2375e46db1/examples/grafana.yaml

  2. Redirecciona los servicios de grafana a tu máquina local. En este ejemplo, se reenvía el servicio al puerto 3000:

    kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000

    Este comando no muestra y, mientras se ejecuta, informa los accesos a la URL.

    Puedes acceder a Grafana en tu navegador en la URL http://localhost:3000 con el nombre de usuario: contraseña admin:admin.

Luego, agrega una fuente de datos de Prometheus nueva a Grafana mediante los siguientes pasos:

  1. Ve a la implementación de Grafana, por ejemplo, si navegas a la URL http://localhost:3000 para llegar a la página de bienvenida de Grafana.

  2. Selecciona Conexiones en el menú principal de Grafana y, luego, selecciona Fuentes de datos.

    Agrega una fuente de datos en Grafana.

  3. Selecciona Agregar fuente de datos (Add data source) y selecciona Prometheus como la base de datos de series temporales.

    Agrega una fuente de datos de Prometheus.

  4. Asigna un nombre a la fuente de datos, establece el campo URL en http://localhost:9090 y, luego, selecciona Guardar y probar. Puedes ignorar cualquier error que indique que la fuente de datos no está configurada correctamente.

  5. Copia la URL del servicio local para tu implementación, que se verá de la siguiente manera:

    http://grafana.NAMESPACE_NAME.svc:3000

Configura y autentica la fuente de datos de Grafana

Todas las API de Google Cloud requieren autenticación mediante OAuth2; Sin embargo, Grafana no admite la autenticación de OAuth2 para las fuentes de datos de Prometheus. Si deseas usar Grafana con el servicio administrado para Prometheus, debes usar el sincronizador de fuentes de datos para generar credenciales OAuth2 y sincronizarlas con Grafana a través de la API de la fuente de datos de Grafana.

Debes usar el sincronizador de fuentes de datos para configurar y autorizar a Grafana para consultar datos de forma global. Si no sigues estos pasos, Grafana solo ejecuta consultas en los datos del servidor local de Prometheus.

El sincronizador de fuentes de datos es una herramienta de interfaz de línea de comandos que usa un CronJob de Kubernetes para sincronizar valores de configuración de forma remota con una fuente de datos de Prometheus de Grafana determinada. Esto garantiza que la fuente de datos de Grafana tenga configurado lo siguiente de forma correcta:

  • Autenticación, realizada con una actualización periódica de un token de acceso OAuth2
  • La API de Cloud Monitoring configurada como la URL del servidor de Prometheus
  • El método HTTP configurado como GET
  • El tipo y la versión de Prometheus configurados en un mínimo de 2.40.x
  • Los valores de tiempo de espera de HTTP y de consulta establecidos en 2 minutos

El sincronizador de fuentes de datos usa la cuenta de servicio local del clúster a fin de generar de manera periódica un token de acceso a la API de Google Cloud con los permisos de IAM necesarios para consultar los datos de Cloud Monitoring. Como los tokens de acceso a la API de Google Cloud tienen un ciclo de vida de una hora, el sincronizador de fuentes de datos se ejecuta cada 30 minutos para garantizar que tengas una conexión autenticada sin interrupciones entre Grafana y la API de Cloud Monitoring.

Para implementar y ejecutar el sincronizador de la fuente de datos, haz lo siguiente:

  1. Elige un proyecto, un clúster y un espacio de nombres para implementar el sincronizador de fuentes de datos. Recomendamos implementar el sincronizador de fuente de datos en un clúster que pertenezca al proyecto de permisos de un permiso de métricas de varios proyectos. El sincronizador de fuentes de datos usa el proyecto de Google Cloud configurado como el proyecto de permisos.

    Luego, asegúrate de configurar y autorizar de forma adecuada el sincronizador de fuentes de datos:

    Luego, determina si debes autorizar aún más el sincronizador de fuente de datos para las consultas de varios proyectos:

  2. Determina la URL de tu instancia de Grafana, por ejemplo, https://yourcompanyname.grafana.net para una implementación de Grafana Cloud o http://grafana.NAMESPACE_NAME.svc:3000 para una instancia local configurada con el YAML de implementación de prueba.

    Si implementas Grafana de forma local y el clúster está configurado para proteger todo el tráfico en el clúster mediante TLS, debes usar https:// en la URL y autenticarte con una de las opciones de autenticación de TLS admitidas.

  3. Elige la fuente de datos de Grafana de Prometheus que deseas usar para el servicio administrado para Prometheus, que puede ser una fuente de datos nueva o preexistente, y, luego, busca y escribe el UID de la fuente de datos. El UID de la fuente de datos se puede encontrar en la última parte de la URL cuando se explora o configuras una fuente de datos, por ejemplo. https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. No copies toda la URL de la fuente de datos. Copia solo el identificador único en la URL.

    Ubica un UID de fuente de datos en Grafana.

  4. Configura una cuenta de servicio de Grafana. Para ello, crea la cuenta de servicio y genera un token que esta usará:

    1. En la barra lateral de navegación de Grafana, haz clic en Administración > Usuarios y acceso > Cuentas de servicio.

    2. Para crear la cuenta de servicio, haz clic en Agregar cuenta de servicio, asígnale un nombre y otórgale la función “Administrador” en Grafana.

    3. Haz clic en Agregar token de cuenta de servicio.

    4. Configura el vencimiento del token configurado como “Sin vencimiento” y haz clic en Generar token; luego, copia el token generado en el portapapeles para usarlo como GRAFANA_SERVICE_ACCOUNT_TOKEN en el siguiente paso:

      Genera y guarda un token de cuenta de servicio en Grafana.

  5. Configura las siguientes variables de entorno con los resultados de los pasos anteriores:

    # These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.

  6. Ejecuta el siguiente comando para crear un CronJob que actualice la fuente de datos durante la inicialización y, luego, cada 30 minutos: Si usas Workload Identity, el valor de NAMESPACE_NAME debe ser el mismo espacio de nombres que vinculaste antes a la cuenta de servicio.

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' \
| kubectl -n NAMESPACE_NAME apply -f -

  7. Ve a la fuente de datos de Grafana recién configurada y verifica que el valor de la URL del servidor de Prometheus comience con https://monitoring.googleapis.com. Es posible que debas actualizar la página. Una vez verificada, ve a la parte inferior de la página y selecciona Guardar y probar. Debes seleccionar este botón al menos una vez para asegurarte de que la función de autocompletado de etiquetas funcione en Grafana.

Ejecuta consultas mediante Grafana

Ahora puedes crear paneles de Grafana y ejecutar consultas con la fuente de datos configurada. En la siguiente captura de pantalla, se muestra un gráfico de Grafana que muestra la métrica up:

Gráfico de Grafana para la métrica up del servicio administrado para Prometheus.

Para obtener información sobre cómo consultar las métricas del sistema de Google Cloud mediante PromQL, consulta PromQL para las métricas de Cloud Monitoring.

Ejecuta el sincronizador de fuente de datos fuera de GKE

Puedes omitir esta sección si ejecutas el sincronizador de fuente de datos en un clúster de Google Kubernetes Engine. Si tienes problemas de autenticación en GKE, consulta Verifica las credenciales de la cuenta de servicio.

Cuando se ejecuta en GKE, el sincronizador de fuente de datos recupera las credenciales del entorno de forma automática según la cuenta de servicio del nodo o la configuración de Workload Identity. En los clústeres de Kubernetes que no son de GKE, las credenciales deben proporcionarse de forma explícita al sincronizador de fuentes de datos mediante la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

  1. Configura el contexto en tu proyecto de destino:

    gcloud config set project PROJECT_ID

  2. Crear una cuenta de servicio:

    gcloud iam service-accounts create gmp-test-sa

    En este paso, se crea la cuenta de servicio que puedes haber creado ya en las instrucciones de Workload Identity.

  3. Otorga permisos obligatorios a la cuenta de servicio:

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

  4. Crea y descarga una clave para la cuenta de servicio:

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

  5. Configura la ruta del archivo de claves mediante la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

Autoriza al sincronizador de fuente de datos para obtener la supervisión de varios proyectos

Managed Service para Prometheus admite la supervisión de varios proyectos a través de permisos de métricas. Si tu proyecto local es tu proyecto de permisos y seguiste las instrucciones para verificar o configurar una cuenta de servicio para el proyecto local, entonces las consultas de varios proyectos deberían funcionar sin ninguna configuración adicional.

Si tu proyecto local no es tu proyecto de permisos, debes autorizar a la cuenta de servicio de Compute predeterminada del proyecto local o a tu cuenta de servicio de Workload Identity para tengan acceso monitoring.viewer al proyecto de permisos. Luego, pasa el ID del proyecto de permisos como el valor de la variable de entorno PROJECT_ID.

Si usas la cuenta de servicio default de Compute Engine, puedes realizar una de las siguientes acciones:

Para otorgar a una cuenta de servicio los permisos necesarios para acceder a un proyecto de Google Cloud diferente, haz lo siguiente:

  1. Otorga permiso a la cuenta de servicio para leer el proyecto de destino que deseas consultar:

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

  2. Cuando configures el sincronizador de fuente de datos, pasa el ID del proyecto de permisos como el valor de la variable de entorno PROJECT_ID.

Inspecciona el CronJob

Para inspeccionar el CronJob y asegurarte de que todas las variables estén configuradas de manera correcta, ejecuta el siguiente comando:

kubectl describe cronjob datasource-syncer

Para ver los registros del trabajo que configura Grafana en un principio, ejecuta el siguiente comando de inmediato después de aplicar el archivo datasource-syncer.yaml:

kubectl logs job.batch/datasource-syncer-init

Elimina

Para inhabilitar el sincronizador de la fuente de datos de Cronjob, ejecuta el siguiente comando:

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

Inhabilitar el sincronizador de fuente de datos deja de actualizar Grafana vinculado con credenciales de autenticación nuevas y, como consecuencia, las consultas al servicio administrado para Prometheus ya no funcionan.

Compatibilidad de API

Los siguientes extremos de la API de HTTP para Prometheus son compatibles con el servicio administrado para Prometheus con la URL con el prefijo https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

Para obtener la documentación completa, consulta la documentación de referencia de la API de Cloud Monitoring.

Para obtener información sobre la compatibilidad con PromQL, consulta Compatibilidad con PromQL.

  • Los siguientes extremos son totalmente compatibles:

    • /api/v1/query
    • /api/v1/query_range
    • /api/v1/metadata
    • /api/v1/labels
    • /api/v1/query_exemplars

  • El extremo /api/v1/label/<label_name>/values solo funciona si la etiqueta __name__ se proporciona mediante el uso del valor <label_name> o mediante la coincidencia exacta con un selector de serie. Por ejemplo, las siguientes llamadas son totalmente compatibles:

    • /api/v1/label/__name__/values
    • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
    • /api/v1/label/labelname/values?match[]={__name__="metricname"}

    Esta limitación hace que las consultas variables de label_values($label) en Grafana fallen. En su lugar, puedes usar label_values($metric, $label). Se recomienda este tipo de consulta, porque evita recuperar valores de etiquetas en métricas que no son relevantes para el panel determinado.

  • El extremo /api/v1/series es compatible con solicitudes GET, pero no con POST. Cuando usas el sincronizador de fuentes de datos o el proxy de frontend, esta restricción se administra por ti. También puedes configurar las fuentes de datos de Prometheus en Grafana para emitir solo solicitudes GET.

¿Qué sigue?