Kibana Dashboards API: Ein stabiler Vertrag für jeden Panel-Typ, vor GA von über 50 Teams getestet

Observe, protect, and search your data with a single solution. From application monitoring to threat detection, Kibana is your versatile platform for critical use cases. Start your free 14-day trial now.

Die Kibana-Dashboard- und Visualisierungs-APIs sind in Elastic 9.5 produktionsbereit, über alle Abonnementstufen hinweg verfügbar und mit vollständiger Abwärtskompatibilität. Definieren Sie Ihre Dashboards als JSON, übertragen Sie sie in Git und stellen Sie sie anschließend mithilfe von CI/CD-Pipelines (Continuous Integration und Continuous Deployment), Terraform oder anderen Tools, die Sie bereits einsetzen, in verschiedenen Umgebungen bereit. Über 50 Teams testeten die API während der technischen Vorschau in Version 9.4, einige setzen sie bereits in der Produktion ein. In Version 9.5 werden außerdem neue Endpunkte (in der technischen Vorschau) für Tags hinzugefügt, wobei die Endpunkte für die Bedienfelder Markdown und Links bereits in Elastic Cloud Serverless verfügbar sind und in Version 9.6 eingeführt werden.

Was Abwärtskompatibilität für die Kibana-Dashboards API bedeutet

Während der technischen Vorschau kann sich die API-Struktur zwischen den Releases ändern.[1] Diese Zeiten sind vorbei. Allgemeine Verfügbarkeit (General Availability, GA) bedeutet:

• Vollständige Abwärtskompatibilität. Im Laufe der Zeit werden neue Felder und Paneltypen hinzugefügt, aber bestehende Felder und Verhaltensweisen bleiben unverändert. Alle zukünftigen kompatibilitätsbrechenden Änderungen würden sehr sorgfältig geprüft und nur in einer neuen Haupt-Stack-Version eingeführt.

• Produktionsbereit mit voller Unterstützung. Die API bietet die vollständigen Support-Garantien von Elastic. Sie können es bedenkenlos in Produktionsumgebungen für automatisierte Deployments, Umgebungs-Promotion und programmatisches Dashboard-Management verwenden.

Neue Kibana-API-Endpoints für die Panels „Tags“, „Markdown“ und „Links“

Elastic 9.5 führt außerdem einen neuen eigenständigen Endpoint für Tags ein, der es ermöglicht, Dashboards zu kategorisieren und zu filtern. Sie können diese nun programmatisch über dedizierte CRUD-Endpoints verwalten, was die Organisation von Dashboards in großem Umfang über verschiedene Umgebungen hinweg vereinfacht.

Neue Endpoints für die Markdown- und Links-Bedienfelder sind ab sofort in Serverless verfügbar und werden in der nächsten Stack-Version (9.6) implementiert.

Welche Panel-Typen unterstützt die Kibana-Dashboards-API?

Die Dashboards-API unterstützt alle By-Value-Panels in Version 9.5 (d. h. diejenigen, die direkt in einem Dashboard definiert wurden, im Gegensatz zu Bibliotheks-Panels, die zur Wiederverwendung gespeichert wurden). Jeder unterstützte Paneltyp verfügt über ein typisiertes, validiertes Schema.

Wie man Kibana-Dashboards als Code verwaltet

Die Dashboards-API ermöglicht einen vollständigen „Dashboards-as-Code“-Workflow: Exportieren Sie ein Dashboard als sauberes, vergleichbares JSON, übertragen Sie es als maßgebliche Quelle in Git, überprüfen Sie Änderungen in Pull-Anfragen und stellen Sie dieselbe Definition in den Umgebungen Entwicklung, Staging und Produktion bereit. Sobald ein Dashboard als Code verwaltet wird, ist Git als einzige Quelle der Wahrheit zu behandeln: Änderungen, die direkt in der Benutzeroberfläche vorgenommen werden, werden beim nächsten Bereitstellen überschrieben.

Die größte Herausforderung beim Verschieben eines Dashboards zwischen Bereichen, Clustern oder Phasen besteht darin, dass Dashboards auf Objekte wie Datenansichten und Bibliotheksvisualisierungen anhand ihrer ID verweisen. Da diese IDs automatisch generiert werden und sich je nach Umgebung unterscheiden, kann ein aus einer Umgebung exportiertes Dashboard auf Objekte verweisen, die in einer anderen Umgebung nicht vorhanden sind. Es gibt drei Möglichkeiten, dies zu handhaben, hier aufgelistet von der am stärksten automatisierten bis zur am wenigsten automatisierten:

• Benutzen Sie Terraform. Der Elastic Stack Terraform Provider verfolgt jede Ressource und ordnet IDs pro Umgebung automatisch zu, sodass die Referenzen konsistent bleiben, wenn Sie ein Dashboard von der Entwicklung bis zur Produktion überführen.

• Nach Wert definieren Elasticsearch Abfragesprache (ES|QL)-Panels. Die portabelste Methode zum Erstellen eines Panels besteht darin, dessen Visualisierung mit ES|QL direkt im Dashboard zu definieren. Eine ES|QL-Abfrage liest aus den von Ihnen genannten Indizes, sodass das Panel keine externen Referenzen auf Data view oder Bibliotheksobjekte enthält. Das Ergebnis ist ein vollständig autarkes, portables Dashboard.

• Weisen Sie passende IDs zu. Wenn Sie auf gespeicherte Objekte wie Data View oder Bibliotheksvisualisierungen verweisen, erstellen Sie diese mit einer ausgewählten ID mittels PUT (upsert) anstatt mit POST (das automatisch eine ID generiert). Verwenden Sie für Menschen lesbare IDs, wie beispielsweise „logs-prod“, damit diese in verschiedenen Umgebungen leicht wiederverwendet und erkannt werden können.

Eine ausführliche Anleitung zu diesen Portabilitätsmustern und dem vollständigen Dashboards-as-Code-Workflow finden Sie in der Dokumentation Dashboards als Code verwalten.

Erstellen Sie ein Kibana-Dashboard mit der Dashboards-API mithilfe von PUT

Hier ein kurzes Beispiel zur Erstellung eines Dashboards mit einem Metrikbereich. Dabei wird PUT anstelle von POST verwendet, um eine benutzerdefinierte ID anhand des Dashboard-Namens (service-health-overview) zuzuweisen. Dieselbe Logik funktioniert auch für die Erstellung eigenständiger Visualisierungen, die in der Bibliothek gespeichert werden.

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"
          }
        ]
      }
    }
  ]
}

Kibana Dashboards API-Roadmap: Maps, Vega und eigenständige Endpoints

Wir erweitern aktiv die API-Schnittstelle. Als nächstes folgt die Unterstützung für Maps und Vega-Panels, wobei typisierte Schemas dafür hinzugefügt werden. Wir entwickeln außerdem eigenständige CRUD-Endpunkte für Discover-Sitzungen (zusätzlich zu ihrer bestehenden Unterstützung als Dashboard-Panels), Vega, Maps und Annotations, die vom Dashboard-Lebenszyklus entkoppelt sind.

Für die vollständigen Schema-Definitionen besuchen Sie die Dashboards API-Dokumentation. Für Terraform-Nutzer unterstützt der Elastic Stack Terraform-Provider die GA Dashboards API.

Anmerkung

1. Die Kern-Endpoints sind gegenüber der technischen Vorschau unverändert. Wenn Sie Integrationen für 9.4 erstellt haben, funktionieren sie in 9.5. Die einzigen kompatibilitätsbrechenden Änderungen sind zwei geringfügige, die sich auf die Formate für Dashboard-Auflistungen und Dauereinheiten auswirken und hier dokumentiert sind.