API Kibana Dashboards : un contrat stable pour chaque type de panneau, testé par plus de 50 équipes avant DG

Les API Kibana Dashboards et de visualisation sont prêtes pour la production dans Elastic 9.5 ; elles sont disponibles pour tous les niveaux d'abonnement et offrent une rétrocompatibilité totale. Définissez vos tableaux de bord au format JSON, validez-les dans Git, puis déployez-les dans différents environnements à l'aide de pipelines d'intégration et de déploiement continus (CI/CD), de Terraform ou de tout autre outil que vous utilisez déjà. Plus de 50 équipes ont testé l'API lors de la préversion technique 9.4, certaines l'exploitant même déjà en production. La version 9.5 ajoute également de nouveaux points de terminaison (en préversion technique) pour le panneau Tags, avec des points de terminaison pour les panneaux Markdown et Links disponibles dès maintenant dans Elastic Cloud Serverless et prochainement dans la version 9.6.

Ce que la rétrocompatibilité implique pour l'API Kibana Dashboards

Pendant la préversion technique, la forme de l'API pouvait changer d'une version à l'autre.[1] Ce n'est plus le cas. La disponibilité générale (DG) signifie :

• Rétrocompatibilité totale. De nouveaux champs et types de panneaux seront ajoutés au fil du temps, mais les champs et comportements existants demeureront inchangés. Toute modification majeure susceptible de rompre la compatibilité sera examinée avec la plus grande attention et ne sera introduite que dans une nouvelle version majeure de la pile technologique.

• Prête pour la production avec compatibilité totale. L'API bénéficie des garanties de compatibilité complète d'Elastic. Vous pouvez l'utiliser en toute sécurité dans les environnements de production pour les déploiements automatisés, la promotion de l'environnement et la gestion programmatique des tableaux de bord.

Nouveaux points de terminaison de l'API Kibana pour les panneaux Tags, Markdown et Links

Elastic 9.5 introduit également un nouveau point de terminaison autonome pour le panneau Tags, qui vous permet de catégoriser et filtrer les tableaux de bord. Vous pouvez désormais les gérer par programmation via des points de terminaison CRUD dédiés, ce qui facilite leur organisation à grande échelle dans différents environnements.

De nouveaux points de terminaison pour les panneaux Markdown et Liens sont désormais disponibles dans Serverless et seront intégrés dans la prochaine version de la pile (9.6).

Quels types de panneaux l'API Kibana Dashboards prend-elle en charge ?

L'API Dashboards prend en charge tous les panneaux par valeur de la version 9.5 (ceux définis directement dans un tableau de bord, par opposition aux panneaux de bibliothèque enregistrés pour être réutilisés). Chaque type de panneau pris en charge dispose d'un schéma typé et validé.

Comment gérer les tableaux de bord Kibana sous forme de code

L'API Dashboards permet un workflow complet de tableaux de bord sous forme de code : exportez un tableau de bord au format JSON propre et facilement comparable, validez-le dans Git comme source de référence, examinez les modifications via des requêtes pull et déployez la même définition dans les environnements de développement, de préproduction et de production. Une fois qu'un tableau de bord est géré sous forme de code, considérez Git comme source de référence unique : les modifications effectuées directement dans l'interface utilisateur seront écrasées lors du prochain déploiement.

La principale difficulté lors du transfert d'un tableau de bord entre des espaces, des clusters ou des environnements est que les tableaux de bord font référence à des objets (data views ou visualisations de bibliothèques, par exemple) au moyen d'identifiants. Comme ces identifiants sont générés automatiquement et varient d'un environnement à l'autre, un tableau de bord exporté depuis un environnement peut pointer vers des objets inexistants dans un autre. Il existe trois méthodes pour gérer cette situation, présentées ici de la plus automatisée à la moins automatisée :

• Utilisez Terraform. Le fournisseur Elastic Stack Terraform suit chaque ressource et associe automatiquement les identifiants par environnement, afin que les références restent cohérentes lorsque vous faites passer un tableau de bord de l'environnement de développement à l'environnement de production.

• Définissez par valeur les panneaux Elasticsearch Query Language (ES|QL). La méthode la plus portable pour créer un panneau consiste à définir sa visualisation à l'aide d'ES|QL directement dans le tableau de bord. Une requête ES|QL lit les données à partir des index qui y sont spécifiés ; le panneau ne contient donc aucune référence externe à des data views ou à des objets de bibliothèque. On obtient ainsi un tableau de bord entièrement autonome et portable.

• Attribuer les identifiants correspondants. Si vous référencez des objets enregistrés, tels que des data views ou des visualisations de bibliothèque, créez-les avec un identifiant spécifique en utilisant la méthode PUT (upsert) plutôt que POST (qui génère automatiquement un identifiant). Utilisez des identifiants explicites et lisibles, comme logs-prod, afin qu'ils soient faciles à reconnaître et à réutiliser d'un environnement à l'autre.

Pour une présentation détaillée de ces modèles de portabilité et du workflow complet des tableaux de bord sous forme de code, consultez la documentation Gérer les tableaux de bord sous forme de code.

Création d'un tableau de bord Kibana avec l'API Dashboards en utilisant PUT

Voici un exemple rapide de création d'un tableau de bord avec un panneau de métriques, utilisant la méthode PUT au lieu de POST pour attribuer un identifiant personnalisé basé sur le nom du tableau de bord (service-health-overview). La même logique s'applique à la création de visualisations autonomes enregistrées dans la bibliothèque.

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 l'API Kibana Dashboards : Maps, Vega et points de terminaison autonomes

Nous travaillons activement à étendre la surface de l'API. La prise en charge des panneaux Maps et Vega est la prochaine étape, avec ajout de schémas typés. Nous développons également des points de terminaison CRUD autonomes pour les sessions Discover (au-delà de leur prise en charge actuelle en tant que panneaux de tableau de bord), les panneaux Vega, Maps et les Annotations, le tout dissocié du cycle de vie des tableaux de bord.

Pour les définitions complètes des schémas, consultez la documentation de l'API Dashboards. Pour les utilisateurs de Terraform, le fournisseur Elastic Stack Terraform prend en charge l'API Dashboards en DG.

Remarque

1. Les points de terminaison principaux restent inchangés par rapport à la préversion technique. Si vous avez développé des intégrations pour la version 9.4, elles fonctionneront avec la version 9.5. Les seuls changements entraînant une rupture de compatibilité sont deux modifications mineures concernant la liste des tableaux de bord et les formats d'unité de durée ; elles sont documentées ici.