Skip to content

Latest commit

 

History

History
96 lines (75 loc) · 3.07 KB

USER_GUIDE.md

File metadata and controls

96 lines (75 loc) · 3.07 KB
Raw

User Guide

Setup

To add the gem to your project, install it using RubyGems:

gem install opensearch-aws-sigv4

or add it to your Gemfile:

gem opensearch-aws-sigv4

and run:

bundle install

Usage

This library is an AWS Sigv4 wrapper for opensearch-ruby, which is a Ruby client for OpenSearch. The OpenSearch::Aws::Sigv4Client, therefore, has all features of OpenSearch::Client.

Amazon OpenSearch Service

To sign requests for the Amazon OpenSearch Service:

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

signer = Aws::Sigv4::Signer.new(service: 'es', # signing service name, use "aoss" for OpenSearch Serverless
                                region: 'us-west-2', # signing service region
                                access_key_id: 'key_id',
                                secret_access_key: 'secret')

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

# create an index and document
index = 'prime'
client.indices.create(index: index)
client.index(index: index, id: '1', body: { name: 'Amazon Echo', 
                                            msrp: '5999', 
                                            year: 2011 })

# search for the document
client.search(body: { query: { match: { name: 'Echo' } } })

# delete the document
client.delete(index: index, id: '1')

# delete the index
client.indices.delete(index: index)

Enable Sigv4 Debug Logging

If you run into credentials errors, usually from expired session, set the sigv4_debug option to true when creating the client to print out the Sigv4 Signing Debug information.

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

client.info
(2023-04-25 11:02:59 -0600)  Sigv4 - STRING TO SIGN: 
AWS4-HMAC-SHA256
20230425T170259Z
20230425/us-east-1/aoss/aws4_request
0e20bdc5eda484f2b0e65f8a33514c48471500da91b1f0c8bb6b86770b5dc6c4

(2023-04-25 11:02:59 -0600)  Sigv4 - CANONICAL REQUEST:
GET
/

host:your.amz-managed-opensearch.domain
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20230425T170259Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

(2023-04-25 11:02:59 -0600)  Sigv4 - SIGNATURE HEADERS:
{"host"=>"your.amz-managed-opensearch.domain", 
"x-amz-date"=>"20230425T170259Z", 
"x-amz-content-sha256"=>"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", 
"authorization"=>"AWS4-HMAC-SHA256 Credential=ABCDEFGH/20230425/us-east-1/aoss/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=858f171c834231ae3c885c670217f94c68f010e85c50b0ad095444966fb5df0c"}