feat: support existing OS domain

Author: karancode

CONTRIBUTING.md

@@ -23,7 +23,7 @@ reported the issue. Please try to include as much information as you can. Detail
 ## Contributing via Pull Requests
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
-1. You are working against the latest source on the *main* branch.
+1. You are working against the latest source on the *master* branch.
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
 
@@ -57,3 +57,5 @@ If you discover a potential security issue in this project we ask that you notif
 ## Licensing
 
 See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+
+We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.

LICENSE

@@ -1,3 +1,18 @@
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 MIT No Attribution
 
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

README.md

@@ -1,3 +1,4 @@
+
 # Near-Real Time Usage Anomaly Detection using OpenSearch
 
 Detecting usage anomalies promptly is crucial because they can result in unforeseen charges. The Near-Real Time Usage Anomaly Detection solutions offers the capabilities to address this issue effectively. 
@@ -37,7 +38,7 @@ The primary components of the solution's architecture are:
 - OpenSearch Dashboards access enabled by user authentication through the OpenSearchUser Cognito.
 
 ## Pre-requisites
-- [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/v2/guide/home.html) version 2.69 or higher.
+- [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/v2/guide/home.html) version 2.100.0.
 -  All required libraries installed using python pip. Below commands are run locally from the root of the repository.
 
     ```
@@ -47,24 +48,37 @@ The primary components of the solution's architecture are:
 The above commands will also download the python libraries for the lambda layer.
 
 ## Deployment
-- Deploy the stack:  
+- Deploy complete stack:  
 
     ```
-    cdk deploy --parameters opensearchAlertEmail='<your-alert-mailing-list@email.com>'
-    ```
+    cdk deploy \
+    --context opensearch-version='<OPENSEARCH_n_m>' \
+    --parameters opensearchAlertEmail='<alert_email>'
+    ```  
+    This will do the following in the target account : 
+    1. Create CloudTrail trails with target CloudWatch log-group for the trails.
+    2. Create OpenSearch Domain with Cognito auth for user management.
+    3. Setup Cloudwatch subscription filter (using Lambda) to forward logs to OpenSearch.
+    4. Create Lambda functions for Opensearch configuration automation(IAM Role mapping, anomaly detector creation).
+    5. Create SNS topics for alerts and notification lambda for enriched notifications.  
 
-This will do the following in the target account : 
-1. Create CloudTrail trails with target CloudWatch log-group for the trails.
-2. Create OpenSearch Domain with Cognito auth for user management.
-3. Setup Cloudwatch subscription filter (using Lambda) to forward logs to OpenSearch.
-4. Create Lambda functions for Opensearch configuration automation(IAM Role mapping, anomaly detector creation).
-5. Create SNS topics for alerts and notification lambda for enriched notifications.  
+- Deploy to existing OpenSearch domain:  
+
+    ```
+    cdk deploy \
+    --context opensearch-version='<OPENSEARCH_n_m>' \
+    --context opensearch-domain-endpoint='<endpoint_domain>' \
+    --context opensearch-access-role-arn='<iam_role_arn>' \
+    --parameters opensearchAlertEmail='<alert_email>'
+    ```  
+    This will create CloudTrail trail and ingest the trails to the provided OpenSearch domain. It will also create the anomaly detectors in the provided domain.  
+    For setting up the access IAM role, please check [existing_domain_deploy](./existing_domain_deploy.md) guide.  
 
 > NOTE: The IAM roles use AWS ManagedPolicies for various cases like lambdaExecution, etc. If required, please update to use self managed policies.  
 
 You can set the context to disable Lambda logging with the trail by setting: `--context enable-lambda-trail=false`. This will skip the Lambda Anomaly detector creation.  
 
-Furthermore, please examine the notification subscription confirmation email delivered to `<your-alert-mailing-list@email.com>` and confirm your subscription in order to obtain alert emails.
+Furthermore, please examine the notification subscription confirmation email delivered to `<alert_email>` and confirm your subscription in order to obtain alert emails.
 
 ## Usage
 Once the deployment process concludes, the output from the CDK stack offers essential links for utilizing the solution.  
@@ -107,4 +121,4 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
 
 ## License
 
-This library is licensed under the MIT-0 License. See the LICENSE file.
+This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.

cdk.json

@@ -38,6 +38,9 @@
       "aws-cn"
     ],
     "stack-name": "usage-anomaly-detector-stack",
-    "enable-lambda-trail": "true"
+    "enable-lambda-trail": "true",
+    "opensearch-version": "OPENSEARCH_2_9",
+    "opensearch-domain-endpoint": "",
+    "opensearch-access-role-arn": ""
   }
 }

existing_domain_deploy.md

@@ -0,0 +1,16 @@
+## Usage Anomaly Detection Deployment on existing OpenSearch Domain
+
+For deploying the solution to an existing OpenSearch domain, provide an IAM role with permissions to access the domain and basic AWS Lambda execution permissions.  
+Please follow below steps for creating the role and setting permissions:  
+1. Create role and add AWS Lambda execution permissions:  
+    ```
+    export USAGE_ANOMALY_DETECTION_IAM_ROLE_NAME="<role_name>"
+
+    aws iam create-role --role-name $USAGE_ANOMALY_DETECTION_IAM_ROLE_NAME --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
+
+    aws iam attach-role-policy --role-name $USAGE_ANOMALY_DETECTION_IAM_ROLE_NAME  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+    ```
+2. Map the IAM role arn in the OpenSearch all_access backend role, as shown in the screenshot below:  
+![OpenSearch IAM role mapping](images/opensearch_iam_role_backend_mapping.png)
+
+Once done, run the cdk deploy command given in the [readme](./README.md) file with the above IAM role arn and the target OpenSearch domain endpoint.