OpenSearch Aws Sigv4 Client

The opensearch-aws-sigv4 library provides an AWS Sigv4 client for OpenSearch.

Compatibility

The OpenSearch Aws Sigv4 Client is compatible with Ruby 2.5 and higher.

The client's API is compatible with OpenSearch's API versions from 1.0.0 till current.

See COMPATIBILITY for more details.

Installation

Install the package from Rubygems:

gem install opensearch-aws-sigv4

To use an unreleased version, either add it to your Gemfile for Bundler:

gem 'opensearch-aws-sigv4', git: 'git://github.com/opensearch-project/opensearch-ruby.git'

or install it from a source code checkout:

git clone https://github.com/opensearch-project/opensearch-ruby
cd opensearch-ruby/opensearch-aws-sigv4
bundle install
rake install

Usage

This library is an AWS Sigv4 wrapper for opensearch-ruby, which is a Ruby client for OpenSearch. The OpenSearch::Aws::Sigv4Client is, therefore, has all features of OpenSearch::Client. And since opensearch-ruby is a dependency of opensearch-aws-sigv4, you only need to install opensearch-aws-sigv4.

Amazon Managed OpenSearch

Via the Sigv4 Client, you can interact with an Amazon Managed OpenSearch cluster just like would with a self-managed cluster:

require 'opensearch-aws-sigv4'
require 'aws-sigv4'

signer = Aws::Sigv4::Signer.new(service: 'es',
                                region: 'us-west-2',
                                access_key_id: 'key_id',
                                secret_access_key: 'secret')

client = OpenSearch::Aws::Sigv4Client.new(
  { host: 'https://your.amz-managed-opensearch.domain',
    log: true }, 
  signer)

client.cluster.health

client.transport.reload_connections!

client.search q: 'test'

Please refer to opensearch-ruby documentation for further details.

Amazon OpenSearch Serverless

You can also use this client to connect to Amazon OpenSearch Serverless (AOSS). Remember to change the service for the signer to aoss:

require 'opensearch-aws-sigv4'
require 'aws-sigv4'

signer = Aws::Sigv4::Signer.new(service: 'aoss',
                                region: 'us-west-2',
                                access_key_id: 'key_id',
                                secret_access_key: 'secret')

client = OpenSearch::Aws::Sigv4Client.new(
  { host: 'https://your.amz-opensearch-serverless.endpoint',
    log: true },
  signer)

index = 'prime'
client.indices.create(index: index)
client.index(index: index, id: '1', body: { name: 'Amazon Echo', 
                                            msrp: '5999', 
                                            year: 2011 })
client.search(body: { query: { match: { name: 'Echo' } } })
client.delete(index: index, id: '1')
client.indices.delete(index: index)

# Most administrative commands like the ones below will result in a 404 error for AOSS
client.cluster.stats
client.cat.health

NOTES: AOSS does NOT support all API endpoints provided by a standard OpenSearch cluster. Refer to AOSS Developer's Guide for more detail.

Development

You can run rake -T to check the test tasks. Use COVERAGE=true before running a test task to check the coverage with Simplecov.

License

This software is licensed under the Apache 2 license.