Registry / devops / opensearch-rest-resources

opensearch-rest-resources

library0.0.13jsnpmunverified

An AWS CDK construct library (v0.0.13) for managing OpenSearch REST resources like roles, role mappings, and users via CloudFormation custom resources. Designed for domains with fine-grained access control enabled. It uses the Domain L2 construct and assumes master user credentials are stored in AWS Secrets Manager. Supports role, role mapping, and user resources out of the box with a low-level API for arbitrary REST endpoints. Currently limited to OpenSearch domains in a VPC with specific access policies. This is a relatively early release with infrequent updates; check for breaking changes before upgrading.

devops

npm install opensearch-rest-resources

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENSEARCH-REST-RE

opensearch-rest-resources

devopsjavascriptv0.0.13

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenSearchRole

✓ import { OpenSearchRole } from 'opensearch-rest-resources'

✗ const OpenSearchRole = require('opensearch-rest-resources').OpenSearchRole

ESM-style import is preferred; package ships TypeScript declarations.

OpenSearchRoleMapping

✓ import { OpenSearchRoleMapping } from 'opensearch-rest-resources'

✗ import OpenSearchRoleMapping from 'opensearch-rest-resources'

Named export, not default export.

OpenSearchUser

✓ import { OpenSearchUser } from 'opensearch-rest-resources'

Exported only since v0.0.8; earlier versions do not have it.

ResourceBase

✓ import { ResourceBase } from 'opensearch-rest-resources'

Low-level API for custom REST resources; not meant for direct use in most cases.

Creates an OpenSearch role and role mapping using CDK with fine-grained access control.

import { IVpc } from 'aws-cdk-lib/aws-ec2'; import { IRole } from 'aws-cdk-lib/aws-iam'; import { Domain } from 'aws-cdk-lib/aws-opensearchservice'; import { OpenSearchRole, OpenSearchRoleMapping } from 'opensearch-rest-resources'; declare const vpc: IVpc; declare const backendRole: IRole; declare const domain: Domain; const role = new OpenSearchRole(this, 'Role1', { vpc, domain, roleName: 'Role1', payload: { clusterPermissions: ['indices:data/write/bulk'], indexPermissions: [ { indexPatterns: ['*'], allowedActions: ['read', 'write', 'index', 'create_index'], }, ], }, }); new OpenSearchRoleMapping(this, 'RoleMapping1', { vpc, domain, roleName: role.roleName, payload: { backendRoles: [backendRole.roleArn], }, removalPolicy: RemovalPolicy.RETAIN, });

Debug

Known issues

breakingPre-v0.0.8: 'OpenSearchUser' class was not exported; attempting to import it throws a runtime error.

fix

Upgrade to >=0.0.8 or stick to Role/RoleMapping only.

affects: <0.0.8

breakingThe library only supports master user credentials stored in Secrets Manager with a specific secret format. If your secret structure differs, resource creation fails silently.

fix

Ensure your Secrets Manager secret contains keys 'username' and 'password'.

affects: >=0.0.1

deprecatedThe 'removalPolicy' property on OpenSearchRoleMapping and OpenSearchUser is deprecated in favor of 'removalPolicy' on the base class; the old property may be removed in future versions.

fix

Use the 'removalPolicy' property inherited from ResourceBase.

affects: >=0.0.10

gotchaThe library assumes the OpenSearch domain is configured with a VPC and a security group that allows inbound traffic from the custom resource Lambda. If not, resources may time out.

fix

Check VPC settings and security group rules for the Lambda function created by the construct.

affects: >=0.0.1

gotchaRole names must be unique within an OpenSearch domain; creating duplicate roles may lead to conflicts and stack failures.

fix

Use unique names for each OpenSearchRole resource, or use the 'roleName' property to reference an existing role.

affects: >=0.0.1

breakingIn v0.0.12, the 'payload' property for OpenSearchRole and OpenSearchUser changed format to match the OpenSearch REST API more closely. Old payloads may cause errors.

fix

Review the updated payload structure in the documentation or reference the OpenSearch API.

affects: =0.0.12

Errors

Common errors & fixes

Error: Cannot find module 'opensearch-rest-resources'

Package not installed or not recognized in a non-CDK environment.

fix

npm install opensearch-rest-resources and ensure you are in a CDK app directory.

Property 'payload' is missing in type '{ vpc: IVpc; domain: Domain; roleName: string; }'

Required 'payload' property not provided to OpenSearchRole or OpenSearchRoleMapping constructor.

fix

Add 'payload' property with the appropriate JSON structure.

Resource handler returned message: "Invalid request" (500)

The payload sent to OpenSearch API is malformed or permission issue with the master user.

fix

Check that the master user credentials are correct and the payload matches OpenSearch API documentation.

Time out on custom resource. The custom resource request failed on the resource provider.

The Lambda function backing the custom resource was unable to reach the OpenSearch domain (likely VPC or security group issue).

fix

Verify that the Lambda function has network connectivity to the OpenSearch domain, and that the domain's access policy allows the Lambda's source IP or VPC.

Cannot destructure property 'username' of '(intermediate value)' as it is undefined.

The Secrets Manager secret for master user does not contain 'username' key or the secret ARN is incorrect.

fix

Ensure your secret has keys 'username' and 'password'. Set the secret ARN via props or CDK context.

Upgrade

Version history

0.0.13latest on npm

Audit

Dependencies

aws-cdk-librequiredpeer dependency for CDK constructs to interact with OpenSearch Domain and other AWS resources

constructsrequiredpeer dependency required by AWS CDK library for construct base classes

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/tmokmss/opensearch-rest-resources ↗

packageopensearch-rest-resources ↗

homepagehttps://github.com/tmokmss/opensearch-rest-resources#readme ↗