API de paneles de Kibana: un contrato estable para cada tipo de panel, probado por más de 50 equipos antes de GA

Las API de dashboards y visualizaciones de Kibana están listas para producción en Elastic 9.5, disponibles en todos los niveles de suscripción, con total compatibilidad con versiones anteriores. Define tus paneles como JSON, haz commit en Git y luego despliega en diferentes entornos usando pipelines de integración continua y despliegue continuo (CI/CD), Terraform o cualquier herramienta que ya tengas. Más de 50 equipos probaron la API durante la vista previa técnica en la versión 9.4, algunos ya ejecutándola en producción. La versión 9.5 también agrega nuevos endpoints (en vista previa técnica) para las etiquetas, con endpoints de paneles Markdown y Enlaces disponibles ahora en Elastic Cloud Serverless y que aterrizan en la 9.6.

Qué significa la compatibilidad con versiones anteriores para la API de Dashboards de Kibana

Durante la vista previa técnica, la forma de la API podría cambiar entre versiones.[1] Eso ya no es así. Disponibilidad general (GA) significa:

• Compatibilidad total con versiones anteriores. Con el tiempo, se agregarán nuevos campos y tipos de panel, pero los campos y el comportamiento actuales se mantendrán sin cambios. Cualquier cambio futuro que rompa la compatibilidad será considerado con mucho cuidado y solo se introducirá en una nueva versión principal del stack.

• Listo para producción con soporte completo. La API ofrece las garantías completas de soporte de Elastic. Puedes usarla de manera segura en entornos de producción para despliegues automatizados, promoción del entorno y administración programática del dashboard.

Nuevos endpoints de la API Kibana para los paneles de etiquetas, markdown y enlaces

Elastic 9.5 también introduce un nuevo endpoint independiente para etiquetas, que permite categorizar y filtrar paneles. Ahora puedes administrarlos mediante programación a través de endpoints CRUD dedicados, lo que facilita organizar paneles a gran escala en todos los entornos.

Los nuevos endpoints de paneles Markdown y Enlaces ya están disponibles en Serverless y llegarán en la próxima versión de la pila (9.6).

¿Qué tipos de paneles soporta la API de Kibana Dashboards?

La API de dashboards admite todos los paneles por valor en la versión 9.5 (los definidos directamente en un dashboard, a diferencia de los paneles de biblioteca guardados para su reutilización). Cada tipo de panel admitido tiene un esquema tipificado y validado.

Cómo gestionar los dashboards de Kibana como código

La API de dashboards permite un flujo de trabajo completo de dashboards como código: exportar un dashboard como JSON limpio y diferenciable, hacer commit en Git como fuente de verdad, revisar los cambios en pull requests, y desplegar la misma definición en desarrollo, staging y producción. Una vez que un dashboard se administra como código, trata a Git como la única fuente de verdad: los cambios efectuados directamente en la UI se sobrescriben la próxima vez que despliegues.

El principal desafío al mover un dashboard entre espacios, clústeres o etapas es que los dashboards hacen referencia a objetos como Data view y visualizaciones de biblioteca mediante un ID. Debido a que estos ID se generan automáticamente y difieren de un entorno a otro, un dashboard exportado desde un entorno puede apuntar a objetos que no existen en otro. Hay tres formas de manejarlo, enumeradas aquí de la más a la menos automatizada:

• Usa Terraform. El proveedor Elastic Stack Terraform rastrea cada recurso y mapea automáticamente los ID por entorno, por lo que las referencias se mantienen estables mientras promocionas un dashboard desde el desarrollo hasta la producción.

• Definir por valor Paneles de lenguaje de búsqueda de Elasticsearch (ES|QL). La forma más portátil de construir un panel es definir su visualización con ES|QL directamente en el dashboard. Una consulta ES|QL lee los índices que se especifican en ella, por lo que el panel no contiene referencias externas a vistas de datos ni a objetos de biblioteca. El resultado es un dashboard totalmente autónomo y portátil.

• Asigna ID coincidentes. Si haces referencia a objetos guardados, como Data view o visualizaciones de biblioteca, créalos con un ID elegido usando PUT (upsert) en lugar de POST (que genera automáticamente un ID). Emplea ID legibles por humanos, como logs-prod, para que sean fáciles de reutilizar y reconocer en diferentes entornos.

Para un recorrido detallado de estos patrones de portabilidad y del flujo de trabajo completo de dashboards como código, consulta la documentación de Gestionar dashboards como código.

Crea un dashboard de Kibana con la API de dashboards usando PUT

Aquí hay un ejemplo rápido de crear un dashboard con un panel métrico usando PUT en lugar de POST para asignar un ID personalizado usando el nombre del dashboard (service-health-overview). La misma lógica funciona para crear visualizaciones independientes guardadas en la biblioteca.

PUT kbn:/api/dashboards/service-health-overview
{
  "title": "Service health overview",
  "description": "Key service metrics — managed via API",
  "tags": [
    "production",
    "sre-team"
  ],
  "panels": [
    {
      "type": "vis",
      "grid": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 8
      },
      "config": {
        "title": "Error rate (5xx)",
        "type": "metric",
        "data_source": {
          "type": "esql",
          "query": "FROM logs-* | WHERE http.response.status_code >= 500 | STATS error_rate=count(*) BY host.name"
        },
        "metrics": [
          {
            "type": "primary",
            "column": "count"
          }
        ]
      }
    }
  ]
}

Roadmap de la API de paneles de Kibana: Maps, Vega y endpoints independientes

Estamos ampliando activamente el alcance de la API. El siguiente paso es agregar compatibilidad con mapas y paneles Vega, incluyendo esquemas tipados para ellos. También estamos creando endpoints CRUD independientes para las sesiones de Discover (más allá de su compatibilidad actual como paneles del dashboard), Vega, Maps y Anotaciones, desacoplados del ciclo de vida del dashboard.

Para las definiciones completas de esquemas, visita la documentación de la API de Dashboards. Para los usuarios de Terraform, el proveedor Terraform de Elastic Stack es compatible con la API GA Dashboards.

Nota

1. Los endpoints de núcleo no han cambiado desde la vista previa técnica. Si construiste integraciones contra 9.4, funcionan en 9.5. Los únicos cambios incompatibles son dos menores que afectan al listado del dashboard y a los formatos de unidades de duración, documentados aquí.