Cloudwatch discovery

Este documento describe la funcionalidad cloudwatch de de PandoraFMS, compuesta por el plugin de discovery.

Introducción
Pre requisitos
Parámetros y opciones de configuración
Ejecución manual
Discovery
Agentes y módulos generados por el plugin

Introducción

Este plugin permite monitorizar entornos de AWS mediante CloudWatch, recopilando información detallada sobre métricas de rendimiento y estado de los recursos en la nube. Extrae datos de múltiples servicios y regiones, incluyendo CPU, memoria, utilización de disco, latencias y otros indicadores clave configurables mediante queries personalizadas. Permite el seguimiento de métricas históricas y en tiempo real, proporcionando estadísticas agregadas o valores individuales según la configuración definida.

El script gestiona de forma automatizada la conexión a AWS usando credenciales codificadas, soporta el uso de proxies y configuraciones SSL, y ejecuta consultas en paralelo para optimizar el rendimiento en entornos con múltiples métricas y regiones. Todos los datos recopilados se transforman en módulos compatibles con Pandora FMS, generando agentes y módulos automáticamente, listos para su envío a la plataforma mediante XML, ya sea por Tentacle o mediante transferencia local.

Esta solución facilita la supervisión centralizada de la infraestructura AWS, permitiendo detectar anomalías, picos de carga o problemas potenciales antes de que afecten a la operación, integrando métricas críticas directamente en Pandora FMS para un control continuo y completo del entorno en la nube.

Pre requisitos

Conectividad a la API de AWS

El plugin es un binario que contiene las dependias empaquetadas por lo que no es necesaria la instalación de ningún tipo de dependencia para su uso.

Permisos

Para hacer las solicitudes a través de la api, la cuenta utilizada para autenticar en la ejecución requiere de unos determinados permisos (estos dependerán de las queries utilizadas y de los recursos a los que se intenta acceder).

Billing (read)

CloudWatch (list,read)

Cost Explorer Service (Full access)

EC2 (full read, limited: list)

Asignación de permisos

Cree una política en JSON como la siguiente:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Sid": "VisualEditor0",
           "Effect": "Allow",
           "Action": [
  			   "ec2:DescribeInstances",
               "ec2:DescribeVolumes",
               "aws-portal:ViewBilling",
               "cloudwatch:GetMetricStatistics",
               "ec2:DescribeAddresses",
               "ce:GetCostAndUsage",
               "ce:GetTags"
           ],
           "Resource": "*"
       }
   ]
}

Se debe de asignar la política anterior a un usuario nuevo.

El usuario que cuente con estos permisos podrá acceder a la monitorización de AWS EC2 a través de este plugin.

Para obtener estadísticas avanzadas de las instancias EC2 se debe de habilitar la monitorización detallada en la instancia específica. Esto se hace desde el menú de la instancia en AWS.

Acciones -> Monitoreo y solución de problemas -> Administrar el monitoreo detallado -> Habilitar

Parámetros y opciones de configuración

Parámetros

--creds

Base 64 de las credenciales

Las credenciales antes de pasarlas a base 64 tienen el siguiente formato :

{
  "access_key_id": "KEY",
  "secret_access_key": "PASSWORD"
}

--query_conf

Ruta al archivo de configuración de consultas AWS personalizadas

En el fichero de queries, se pueden especificar una o mas consultas de Metrics Insights. Estas siguen la estructura que esta documentada en el siguiente enlace: https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html

La estructura para poder ejecutar una o mas consultas de Metrics insights es la siguiente :

{   
    "time_frame": "<Ventana de tiempo en la que recoger los datos, opciones posibles : 5m, 10m, 15m, 30m, 1h>",
    "region_name": "< region en la que ejecutar la consulta> ",
    "MetricDataQueries": [
        < Operaciones de metrics insights >
    ]
}

Estas consultas deben ir definidas dentro de una lista y separadas por comas, por lo que la estructura, de dos consultas, sería la siguiente:

[
{   
    "time_frame": "<Ventana de tiempo en la que recoger los datos, opciones posibles : 5m, 10m, 15m, 30m, 1h>",
    "region_name": "< region en la que ejecutar la consulta> ",
    "MetricDataQueries": [
        < Operaciones de metrics insights >
    ]
}
,
{   
    "time_frame": "<Ventana de tiempo en la que recoger los datos, opciones posibles : 5m, 10m, 15m, 30m, 1h>",
    "region_name": "< region en la que ejecutar la consulta> ",
    "MetricDataQueries": [
        < Operaciones de metrics insights >
    ]
}
]

Un ejemplo de una configuración de consultas, sería el siguiente :

[
{   
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
        {
            "Expression": "SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) WHERE InstanceId = 'i-01e5fbcd406596f84' GROUP BY InstanceId",
            "Id": "q1",
            "Period": 300,
            "Label": "avg_cpu"
        },
        {
            "Id": "q2",
            "Expression": "(100 - q1)",
            "Label": "free space"
        }
    ]
},
{
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
      {
        "Id": "ebs_write_time",
        "Expression": "SELECT AVG(VolumeTotalWriteTime) FROM SCHEMA("AWS/EBS", VolumeId)",
        "Label": "Average EBS Volume Total Write Time",
        "Period":300,
        "ReturnData": true
      }
    ]
},
{
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
      {
        "Id": "ec2_cpu",
        "Expression": "SELECT MAX(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) GROUP BY InstanceId ORDER BY MAX() DESC LIMIT 10",
        "Label": "top_10",
        "Period":300,
        "ReturnData": true
      }
    ]
}
]

El campo ID y label de las operaciones que están dentro de cada consulta son importantes para relacionar estas consultas con la configuración de Pandora deseada para el dato obtenido de esta operación. Más abajo en el apartado "configuración de módulos" viene detallado como se pueden relacionar estos campos.

--conf

Ruta al archivo de configuración

Archivo de configuración (--conf)

[CONF]
agents_group       = < Grupo para los agentes creados por el plugin >
agent_name         = < Nombre del agente por defecto >
threads            = < Número de hilos utilizados por el plugin >
interval           = < Intervalo en segundos para los agentes  >
transfer_mode      = < Modo de transferencia, tentacle o local > 
tentacle_ip        = < IP de la máquina destino para los agentes creados >
tentacle_port      = < Puerto de tentacle, por defecto : 41121 >
tentacle_opts      = < Opciones adicionales de tentacle client >
use_proxy          = < Activar para poder utilizar modo proxy >
proxy_url          = < url de la direccion proxy a utilizar >
ssl_check          = < Activar para activar chequeo SSL >

Ejemplo

[CONF]
agents_group       = Applications
agent_name         = AWS 
threads            = 4
interval           = 300
transfer_mode      = tentacle
tentacle_ip        = 127.0.0.1
tentacle_port      = 41121
tentacle_opts      = 
use_proxy          = 0
proxy_url          = 
ssl_check          = 1

Configuración de módulos

La configuración de módulos debe ir definida en el conf anteriormente visto, debajo de las variables.

La estructura para poder configurar módulos para los datos obtenidos de cada operación de cada consulta es la siguiente:

[< ID - Aquí debe ir el ID que se haya definido en la operacion de metrics insights
que se espera recibir el dato >]

name = < Nombre que tendrá el módulo que generará el dato. Se puede usar la macro  __label__ ,
si se usa esta macro, el nombre del módulo será el obtenido por la etiqueta label en 
la operación que contiene el ID definido arriba. Esto es util para consultas que devuelven más
de un dato, por ejemplo una consulta que saque las 10 instancias con mas uso de cpu, si en la
operación defines label como "cpu", la devolucion obtenida sera "cpu <nombre instancia 1>,
cpu cpu <nombre instancia 2> , cpu <nombre instancia 3 > ... y asi sucesivamente y 
estos seran los nombres de los módulos generados >

type = < Tipo del módulo> 

description = < Descripción del módulo >

value = < Valor a recoger del dato obtenido en la operacion, 
opciones posibles : last, average, sum, max, min >

agent = < Agente en el que se incluira el módulo, de no existir se creará, de no definirse, los módulos
se meteran en el agente por defecto >

Ejemplo de configuración de módulos, acorde a las métricas definidas arriba:

[q1]
name = __label__
type = generic_data
description = Monitors CPU utilization
unit =percent
value = average
min_warning = 75
min_critical = 85

[q2]
name = __label__
type = generic_data
description = Monitors CPU free space
unit = percent
value = last
min_warning = 11
max_warning = 20
min_critical = 0
max_critical = 10

[ebs_write_time]
name = __label__
type = generic_data
description = Average EBS Volume Total Write Time
value = last
agent = AWS 2 Cloudwatch

[ec2_cpu]
name = __label__
type = generic_data
description = EC2
value = last

Ejecución manual

El formato de la ejecución del plugin es el siguiente:

./pandora_aws_cloudwatch \
  --creds "<BASE64_DE_TUS_CREDENCIALES>" \
  --conf "<RUTA_AL_FICHERO_DE_CONFIGURACIÓN>" \
  --query_conf "<RUTA_AL_FICHERO_DE_QUERIES_AWS>"

Por ejemplo:

./pandora_aws_cloudwatch \
  --creds "ededNFAFNAFNAFNAPOFBIUFASBFOABCOAFNOIA==" \
  --conf "</usr/share/pandora_server/util/plugin/main_modules.conf>" \
  --query_conf "</usr/share/pandora_server/util/plugin/cloudwatch_queries.conf"

La ejecución devolverá una salida en formato JSON con información sobre la ejecución, y generará un fichero XML para cada agente monitorizado que enviará al servidor de Pandora FMS por el método de transferencia indicado en la configuración.

Por ejemplo:

{"summary": {"Total agents": 3, "Total modules": 25}}

Discovery

Este plugin puede integrarse con el Discovery de Pandora FMS.

Para ello se debe cargar el paquete ".disco" que puede descargar desde la librería de Pandora FMS:

https://pandorafms.com/library/

Una vez cargado, se podrán monitorizar entornos de Amazon creando tareas de Discovery desde la sección Management > Discovery > Cloud.

Para cada tarea se solicitarán los siguientes datos mínimos:

AWS Credentials: Credenciales de conexión al API de AWS a usar por la tarea. Se deben registrar previamente en el almacén de credenciales de Pandora FMS.
Default agent name: Nombre para el agente por defecto (en este se crearan los módulos en los que no se especifique agente.
Tentacle IP: IP del servidor de Tentacle al que enviar los datos de los agentes. Normalmente este parámetro no se modificará.
Tentacle port: Puerto del servidor de Tentacle al que enviar los datos. Normalmente este parámetro no se modificará.
Tentacle extra options: Opciones adicionales para el envio de datos mediante el cliente de Tentacle. Normalmente este parámetro no se modificará.

En la siguiente ventana las opciones de configuración son los siguientes :

Max threads: Número de hilos utilizados por el plugin
Use proxy: Activar para poder utilizar modo proxy
Proxy url: url de la direccion proxy a utilizar
Verify proxy SSL: Marcar para activar chequeo SSL
Configure Cloudwatch queries: Ventana para configurar las consultas.
Configure module data: Ventana para configurar los módulos.

Las tareas que se completen exitosamente dispondrán de un sumario de ejecución con la siguiente información:

Total agents: Número total de agentes generados por la tarea.
Total modules: Número total de módulos generados por la tarea.

Las tareas que no se completen exitosamente dispondrán de un sumario de ejecución registrando los errores producidos.

Agentes y módulos generados por el plugin

Los agentes y módulos generados por el plugin, dependen totalmente de la configuración establecida. Por ejemplo, la siguiente configuración general y de metricas :

Configuración Metricas insights

[
{   
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
        {
            "Expression": "SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) WHERE InstanceId = 'i-01e5fbcd406596f84' GROUP BY InstanceId",
            "Id": "q1",
            "Period": 300,
            "Label": "avg_cpu"
        },
        {
            "Id": "q2",
            "Expression": "(100 - q1)",
            "Label": "free space"
        }
    ]
},
{
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
      {
        "Id": "ebs_write_time",
        "Expression": "SELECT AVG(VolumeTotalWriteTime) FROM SCHEMA("AWS/EBS", VolumeId)",
        "Label": "Average EBS Volume Total Write Time",
        "Period":300,
        "ReturnData": true
      }
    ]
},
{
    "time_frame": "5m",
    "region_name": "us-east-1",
    "MetricDataQueries": [
      {
        "Id": "ec2_cpu",
        "Expression": "SELECT MAX(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) GROUP BY InstanceId ORDER BY MAX() DESC LIMIT 10",
        "Label": "cpu_usage",
        "Period":300,
        "ReturnData": true
      }
    ]
}
]

Configuración general y de módulos

[CONF]
agents_group                     = 1
agent_name                       = AWS General
interval                         = 300
threads                          = 3
transfer_mode                    = tentacle
tentacle_ip                      = 172.42.42.101
tentacle_port                    = 41121

[q1]
name = __label__
type = generic_data
description = Monitors CPU utilization
unit =percent
value = average
agent = AWS EC2
min_warning = 75
min_critical = 85

[q2]
name = __label__
type = generic_data
description = Monitors CPU free space
unit = percent
value = last
min_warning = 11
max_warning = 20
min_critical = 0
max_critical = 10

[ebs_write_time]
name = __label__
type = generic_data
description = Average EBS Volume Total Write Time
value = last
agent = AWS 2 Cloudwatch

[ec2_cpu]
name = __label__
type = generic_data
description = Cpu usage
agent = AWS EC2
value = last

Crearía lo siguiente :

Un agente llamado AWS EC2 ( ya que esta definido en los dos módulos que ejecutan queries de ec2 arriba, explícitamente)

Este agente contendría los siguientes módulos :

Un modulo por cada una de las 10 instancias de la operacion con id ec2_cpu, con el siguiente nombre : cpu_usage <nombre de cada instancia>

Un modulo para la operación q1, con el siguiente nombre: avg_cpu i-01e5fbcd406596f84

Un modulo para la operación q2, con el siguiente nombre: free cpu i-01e5fbcd406596f84

Un agente llamado AWS general (el agente por defecto)

Este agente contendría los siguientes módulos :

Un modulo para la operación ebs_write_time, con el siguiente nombre Average EBS Volume Total Write Time