Comment migrer votre application Ruby d'OpenSearch vers Elasticsearch ?

Passez à la pratique avec Elasticsearch : explorez nos notebooks d’exemples, lancez un essai gratuit sur le cloud ou testez Elastic dès maintenant sur votre machine locale.

Le client OpenSearch Ruby a été dérivé du client Elasticsearch Ruby dans la version 7.x, les bases de code sont donc relativement similaires. Cela signifie que lors de la migration d'un code Ruby d'OpenSearch vers Elasticsearch, le code des bibliothèques clientes respectives sera très familier. Dans ce billet, je vais montrer un exemple d'application Ruby qui utilise OpenSearch et les étapes pour migrer ce code vers Elasticsearch.

Les deux clients sont publiés sous la célèbre licence Apache 2.0, ce qui en fait des logiciels libres et gratuits. La licence d'Elasticsearch a été récemment mise à jour et le cœur d'Elasticsearch et de Kibana est publié sous la licence Open Source AGPL approuvée par l'OSI depuis la version 8.16.

Prise en compte de la version d'Elasticsearch lors de la migration d'une application Ruby

Lors de la migration, il convient de prendre en compte la version d'Elasticsearch qui sera utilisée. Nous recommandons d'utiliser la dernière version stable, qui, au moment de la rédaction de ce document, est 8.17.0. Les versions mineures du client Elasticsearch Ruby suivent les versions mineures d'Elasticsearch. Ainsi, pour Elasticsearch 8.17.x, vous pouvez utiliser la version 8.17.x de la gem Ruby.

OpenSearch a été dérivé d'Elasticsearch 7.10.2. Les API peuvent donc avoir changé et des fonctionnalités différentes peuvent être utilisées sur l'un ou l'autre. Mais cela n'entre pas dans le cadre de cet article, et je vais seulement examiner les opérations les plus courantes dans un exemple d'application.

Pour Ruby on Rails, vous pouvez utiliser le client Elasticsearch officiel ou les bibliothèques d'intégration Rails. Nous recommandons de migrer vers la dernière version stable d'Elasticsearch et du client respectivement. La version de la gem elasticsearch-rails 8.0.0 supporte Rails 6.1, 7.0 et 7.1 et Elasticsearch 8.x.

Le code

Pour cet exemple, j'ai suivi les étapes d'installation d'OpenSearch à partir d'une archive. Après avoir téléchargé et extrait l'archive, j'ai dû définir un mot de passe administrateur initial que j'utiliserai plus tard pour instancier le client.

J'ai créé un répertoire avec un Gemfile qui ressemble à ceci :

Après avoir lancé bundle install, la gem est installée pour mon projet. Ceci a installé la version 3.4.0 de opensearch-ruby et la version d'OpenSearch que j'utilise est 2.18.0. J'ai écrit le code dans un fichier example_code.rb dans le même répertoire. Le code initial de ce fichier est l'instanciation d'un client OpenSearch :

Le paramètre de l'option de transport ssl: { verify: false} est transmis conformément au guide de l'utilisateur afin de faciliter les tests. En production, cela doit être configuré en fonction du déploiement d'OpenSearch.

Depuis la version 2.12.0 d'OpenSearch, la variable d'environnement OPENSEARCH_INITIAL_ADMIN_PASSWORD doit être définie avec un mot de passe fort lors de l'exécution du script d'installation. En suivant les étapes d'installation d'OpenSearch à partir d'une archive, j'ai exporté la variable dans ma console et elle est maintenant disponible pour mon script Ruby.

Une API simple pour s'assurer que le client se connecte à OpenSearch consiste à utiliser l'API cluster.health:

Et en effet, cela fonctionne :

J'ai testé certains des exemples courants que nous avons dans la documentation du client Elasticsearch Ruby, et ils fonctionnent comme prévu :

Migration d'une application Ruby vers Elasticsearch

La première étape consiste à ajouter elasticsearch-ruby dans le fichier Gemfile. Après l'exécution de bundle install, le client Elasticsearch Ruby gem sera installé. Si vous souhaitez tester votre code avant de migrer complètement, vous pouvez initialement laisser la gem opensearch-ruby en place.

La prochaine étape importante sera l'instanciation du client. Cela va dépendre de la manière dont vous utilisez Elasticsearch. Afin de conserver une approche similaire pour ces exemples, je suivrai les étapes de la section Télécharger Elasticsearch et l'exécuter localement.

Lors de l'exécution de bin/elasticsearch, Elasticsearch démarre avec des fonctions de sécurité automatiquement configurées. Veillez à copier le mot de passe de l'utilisateur élastique (mais vous pouvez le réinitialiser en lançant bin/elasticsearch-reset-password -u elastic). Si vous suivez cet exemple, assurez-vous d'arrêter OpenSearch avant de démarrer Elasticsearch, car ils fonctionnent sur le même port.

Au début de example_code.rb, j'ai commenté l'instanciation du client OpenSearch et j'ai ajouté l'instanciation d'un client Elasticsearch :

Comme vous pouvez le constater, le code est presque identique dans ce scénario de test. Elle diffère en fonction du déploiement d'Elasticsearch et de la manière dont vous décidez de vous connecter et de vous authentifier. Il en va de même pour OpenSearch en ce qui concerne la sécurité, l'option de ne pas vérifier ssl ne sert qu'à des fins de test et ne doit pas être utilisée en production.

Une fois le client configuré, j'exécute à nouveau le code avec : bundle exec ruby example_code.rb. Et tout fonctionne !

Déboguer les problèmes de migration

En fonction des API que votre application utilise, il est possible que vous receviez une erreur lorsque vous exécutez votre code contre Elasticsearch si les API d'OpenSearch divergent. La documentation sur les API REST est une référence essentielle pour obtenir des informations détaillées sur l'utilisation des API. Veillez à consulter la documentation relative à la version d'Elasticsearch que vous utilisez. Vous pouvez également consulter la référence Elasticsearch::API.

Voici quelques exemples d'erreurs que vous pouvez rencontrer avec Elasticsearch :

• ArgumentError: Required argument '<ARGUMENT>' missing - Il s'agit d'une erreur du client qui se produit lorsqu'il manque un paramètre requis dans une demande.
• Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Cette erreur provient d'Elasticsearch et signifie que le code client utilise un paramètre qu'Elasticsearch ne reconnaît pas pour l'API utilisée.

Le client Elasticsearch lèvera les erreurs d'Elasticsearch avec le message d'erreur détaillé envoyé par le serveur. Ainsi, pour les paramètres ou les points de terminaison non pris en charge, l'erreur devrait vous informer de ce qui est différent.

Conclusion

Comme nous l'avons démontré avec cet exemple de code, la migration d'une application Ruby d'OpenSearch vers Elasticsearch n'est pas trop complexe du côté de Ruby. Vous devez être conscient des versions et des éventuelles divergences entre les API des moteurs de recherche. Mais pour les actions les plus courantes, le principal changement lors de la migration des clients se situe au niveau de l'instanciation. Ils sont tous deux similaires à cet égard, mais la façon dont l'hôte et les informations d'identification sont définis varie en fonction de la manière dont la pile est déployée. Une fois que le client est configuré et que vous avez vérifié qu'il se connecte à Elasticsearch, vous pouvez remplacer le client OpenSearch par le client Elasticsearch.