Skip to main content

OpenSearch API

OpenSearch API client that allows to prepare the data or setup access roles for existing Opensearch clusters. The construct supports both OpenSearch provisioned clusters and OpenSearch Serverless collections.

Overview​

The construct leverages the CDK Provider Framework to deploy a custom resource to manage, and provide addRoleMapping and callOpenSearchApi methods. Both methods return the custom resource so that allows to enforce sequental execution of the API calls. By default all API calls will be executed simultaneously and are independent of each other.

const domainEndpoint='search-XXXXXX.XXXXXX.es.amazonaws.com';
const apiRole = Role.fromRoleName(this, 'ApiRole', '<IAMRoleWithOpenSearchPermissions>');
const osApi = new dsf.consumption.OpenSearchApi(this, 'MyOpenSearchApi',{
iamHandlerRole:apiRole,
openSearchEndpoint:domainEndpoint,
openSearchClusterType:dsf.consumption.OpenSearchClusterType.PROVISIONED,
removalPolicy:cdk.RemovalPolicy.DESTROY
});
warning

The IAM Role passed as iamHandlerRole property has to have all necessary permissions to execute API calls to the cluster.

callOpenSearchApi​

Generic method to execute any Opensearch API, subject to correct permissions attached to the IAM Role.

  //create index template
  const indexTemplateCr = osApi.callOpenSearchApi('CreateIndexTemplate','_index_template/movies',
    {
      "index_patterns": [
        "movies-*"
      ],
      "template": {
        "settings": {
          "index": {
            "number_of_shards": 1,
            "number_of_replicas": 0
          }
        },
        "mappings": {
          "properties": {
            "title": {
              "type": "text"
            },
            "year": {
              "type": "integer"
            }
          }
        }
      }
    });
    const metadata='{ "index" : { "_index" : "movies-02"}}';
    const bulk=`${metadata}
    {"title": "Barbie", "year": 2023}
    ${metadata}
    {"title": "Openheimer", "year": 2023}`;

    // bulk ingestion using POST
    const bulkCr = osApi.callOpenSearchApi('AddBulk','_bulk',bulk+'\n\n','POST');
    //dependency to enforce sequential API calls
    bulkCr.node.addDependency(indexTemplateCr);

    const add1Cr = osApi.callOpenSearchApi('AddData1', 'movies-01/_doc/1111',{"title": "Rush", "year": 2013}, 'PUT');
    add1Cr.node.addDependency(indexTemplateCr);
    const add2Cr = osApi.callOpenSearchApi('AddData3', 'movies-01/_doc/2222',{"title": "Toy Story", "year": 2014}, 'PUT');
    add2Cr.node.addDependency(indexTemplateCr);
    const add3Cr = osApi.callOpenSearchApi('AddData4', 'movies-01/_doc',{"title": "The Little Mermaid", "year": 2015}, 'POST');
    add3Cr.node.addDependency(indexTemplateCr);

addRoleMapping​

Use this method to add role mappings to OpenSearch cluster using _security plugin. This method is only applicable to provisioned OpenSearch clusters.

OpenSearch Roles API does not allow to update individual roles, requiring to pass array of roles that needs to be applied. To avoid overwriting prevously added roles addRoleMapping method provides persist parameter to store previously added roles inside the construct. To avoid racing conditions you also need to execute multiple addRoleMapping calls sequentionally as shown below.

  const domainEndpoint='search-XXXXXX.XXXXXX.es.amazonaws.com';
  const apiRole = Role.fromRoleName(this, 'ApiRole', '<IAMRoleWithOpenSearchPermissions>');
  const osApi = new dsf.consumption.OpenSearchApi(this, 'MyOpenSearchApi',{
    iamHandlerRole:apiRole,
    openSearchEndpoint:domainEndpoint,
    openSearchClusterType:dsf.consumption.OpenSearchClusterType.PROVISIONED,
    removalPolicy:cdk.RemovalPolicy.DESTROY
  });

  const firstCall = osApi.addRoleMapping('AnotherAdmin', 'all_access','<IAMRole>', true);
  const secondCall = osApi.addRoleMapping('AnotherAdmin', 'all_access','<IAMRole>', true);

  //dependency to enforce sequential API calls
  secondCall.node.addDependency(firstCall);