Como migrar seu aplicativo Ruby do OpenSearch para o Elasticsearch

Coloque a mão na massa com o Elasticsearch: mergulhe nos nossos notebooks de amostra no repositório Elasticsearch Labs, inicie uma avaliação gratuita na nuvem ou conheça o Elastic na sua máquina local agora.

O cliente Ruby do OpenSearch foi derivado do cliente Ruby do Elasticsearch na versão 7.x, portanto, as bases de código são relativamente semelhantes. Isso significa que, ao migrar um código-fonte Ruby do OpenSearch para o Elasticsearch, o código das respectivas bibliotecas de cliente parecerá muito familiar. Neste post do blog, vou mostrar um exemplo de aplicativo Ruby que usa o OpenSearch e os passos para migrar esse código para o Elasticsearch.

Ambos os clientes são distribuídos sob a popular Licença Apache 2.0, sendo, portanto, software livre e de código aberto. A licença do Elasticsearch foi atualizada recentemente e o núcleo do Elasticsearch e do Kibana são publicados sob a licença de código aberto AGPL, aprovada pela OSI, desde a versão 8.16.

Considerando a versão do Elasticsearch ao migrar um aplicativo Ruby.

Um aspecto a considerar na migração é qual versão do Elasticsearch será utilizada. Recomendamos usar a versão estável mais recente, que no momento em que este texto foi escrito é 8.17.0. As versões secundárias do cliente Ruby do Elasticsearch seguem as versões secundárias do Elasticsearch. Então, para o Elasticsearch 8.17.x, você pode usar a versão 8.17.x da gem Ruby.

O OpenSearch foi derivado do Elasticsearch 7.10.2. Assim, as APIs podem ter mudado e recursos diferentes podem ser usados em qualquer uma delas. Mas isso está fora do escopo desta postagem, e vou analisar apenas as operações mais comuns em um aplicativo de exemplo.

Para Ruby on Rails, você pode usar o cliente oficial do Elasticsearch ou as bibliotecas de integração do Rails. Recomendamos a migração para a versão estável mais recente do Elasticsearch e do cliente, respectivamente. A versão elasticsearch-rails da gem 8.0.0 suporta Rails 6.1, 7.0 e 7.1 e Elasticsearch 8.x.

O código

Neste exemplo, segui os passos para instalar o OpenSearch a partir de um arquivo tar. Após baixar e extrair o arquivo tar, precisei definir uma senha de administrador inicial, que usarei posteriormente para instanciar o cliente.

Criei um diretório com um Gemfile que se parece com isto:

Após executar bundle install, a gem é instalada para o meu projeto. Esta versão do opensearch-ruby instalada é 3.4.0 e a versão do OpenSearch que estou executando é 2.18.0. Eu escrevi o código em um arquivo example_code.rb no mesmo diretório. O código inicial neste arquivo é a instanciação de um cliente OpenSearch:

O parâmetro de opção de transporte ssl: { verify: false} está sendo passado conforme o guia do usuário para facilitar os testes. Em produção, isso deve ser configurado dependendo da implantação do OpenSearch.

A partir da versão 2.12.0 do OpenSearch, a variável de ambiente OPENSEARCH_INITIAL_ADMIN_PASSWORD deve ser definida com uma senha forte ao executar o script de instalação. Seguindo os passos para instalar o OpenSearch a partir de um arquivo tar.gz, exportei a variável no meu console e agora ela está disponível para o meu script Ruby.

Uma API simples para garantir que o cliente esteja se conectando ao OpenSearch é usar a API cluster.health :

E de fato funciona:

Testei alguns dos exemplos comuns que temos na documentação do cliente Ruby do Elasticsearch e eles funcionaram conforme o esperado:

Migrando um aplicativo Ruby para o Elasticsearch

O primeiro passo é adicionar elasticsearch-ruby no Gemfile. Após executar bundle install, a gem do cliente Ruby do Elasticsearch será instalada. Se você quiser testar seu código antes de migrar completamente, você pode inicialmente deixar a gem opensearch-ruby lá.

O próximo passo importante será a instanciação do cliente. Isso vai depender de como você está executando o Elasticsearch. Para manter uma abordagem semelhante nestes exemplos, estou seguindo os passos descritos em "Baixar o Elasticsearch e executá-lo localmente".

Ao executar bin/elasticsearch, o Elasticsearch será iniciado com recursos de segurança configurados automaticamente. Certifique-se de copiar a senha do usuário elastic (mas você pode redefini-la executando bin/elasticsearch-reset-password -u elastic). Se você estiver seguindo este exemplo, certifique-se de parar o OpenSearch antes de iniciar o Elasticsearch, pois ambos são executados na mesma porta.

No início de example_code.rb, comentei a instanciação do cliente OpenSearch e adicionei a instanciação para um cliente Elasticsearch:

Como você pode ver, o código é quase idêntico neste cenário de teste. Isso varia de acordo com a implementação do Elasticsearch e a forma como você decide se conectar e autenticar com ele. O mesmo se aplica aqui ao OpenSearch em relação à segurança: a opção de não verificar o SSL destina-se apenas a fins de teste e não deve ser usada em produção.

Depois que o cliente estiver configurado, eu executo o código novamente com: bundle exec ruby example_code.rb. E tudo simplesmente funciona!

Depurando problemas de migração

Dependendo das APIs que seu aplicativo utiliza, existe a possibilidade de você receber um erro ao executar seu código no Elasticsearch se as APIs do OpenSearch divergirem. A documentação das APIs REST é uma referência essencial para informações detalhadas sobre como usar as APIs. Certifique-se de consultar a documentação da versão do Elasticsearch que você está usando. Você também pode consultar a referência Elasticsearch::API .

Alguns erros que você pode encontrar no Elasticsearch podem ser:

• ArgumentError: Required argument '<ARGUMENT>' missing - Este é um erro do cliente e será gerado quando uma solicitação não contiver um parâmetro obrigatório.
• Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Esse erro vem do Elasticsearch e significa que o código do cliente está usando um parâmetro que o Elasticsearch não reconhece para a API que está sendo usada.

O cliente Elasticsearch irá gerar erros do Elasticsearch com a mensagem de erro detalhada enviada pelo servidor. Assim, mesmo para parâmetros ou endpoints não suportados, o erro deve informar qual é a diferença.

Conclusão

Como demonstramos com este exemplo de código, a migração de um aplicativo Ruby do OpenSearch para o Elasticsearch não é muito complexa do ponto de vista do Ruby. É preciso estar ciente das diferenças de versão e de quaisquer APIs potencialmente divergentes entre os mecanismos de busca. Mas, para as ações mais comuns, a principal mudança na migração de clientes está na instanciação. Nesse aspecto, ambos são semelhantes, mas a forma como o host e as credenciais são definidos varia de acordo com a maneira como o Stack está sendo implantado. Após configurar o cliente e verificar se ele está se conectando ao Elasticsearch, você pode substituir o cliente OpenSearch pelo cliente Elasticsearch sem problemas.