From 38104af4b4b33db839d943763c56cf4eae32a126 Mon Sep 17 00:00:00 2001 From: Tal Date: Thu, 11 Apr 2024 18:05:47 +0300 Subject: [PATCH] docs(cloudwatch): add new cloudwatch docs (#1095) --- docs/mint.json | 3 +- .../documentation/cloudwatch-logs.mdx | 36 ------ .../documentation/cloudwatch-metrics.mdx | 31 ----- .../documentation/cloudwatch-provider.mdx | 108 ++++++++++++++++++ 4 files changed, 109 insertions(+), 69 deletions(-) delete mode 100644 docs/providers/documentation/cloudwatch-logs.mdx delete mode 100644 docs/providers/documentation/cloudwatch-metrics.mdx create mode 100644 docs/providers/documentation/cloudwatch-provider.mdx diff --git a/docs/mint.json b/docs/mint.json index 3268264a7..c58fa6236 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -82,8 +82,7 @@ "providers/documentation/aks-provider", "providers/documentation/axiom-provider", "providers/documentation/azuremonitoring-provider", - "providers/documentation/cloudwatch-logs", - "providers/documentation/cloudwatch-metrics", + "providers/documentation/cloudwatch-provider", "providers/documentation/console-provider", "providers/documentation/datadog-provider", "providers/documentation/ilert-provider", diff --git a/docs/providers/documentation/cloudwatch-logs.mdx b/docs/providers/documentation/cloudwatch-logs.mdx deleted file mode 100644 index bf355a65b..000000000 --- a/docs/providers/documentation/cloudwatch-logs.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "AWS CloudWatch Logs" -sidebarTitle: "CloudWatch Logs" -description: "CloudWatch Logs Provider is a provider used to query AWS CloudWatch Logs" ---- - -## Inputs -The `query` function takes the following parameters as inputs: -- `log_group`: Required. The name of the log group to query. -- `query`: Required. A query string to use to filter the log events to be returned. -- `hours`: Optional. An integer representing the number of hours to query the logs for. Defaults to 24. - -## Outputs -The function returns a list or tuple of the query results. - -## Authentication Parameters -The `query` function requires an `access_key` and `access_key_secret` to authenticate with AWS. These can be obtained by creating an AWS IAM user with the necessary permissions to query CloudWatch logs. - -## Connecting with the Provider -To obtain the `access_key` and `access_key_secret` from AWS, you will need to create an AWS IAM user with the necessary permissions to query CloudWatch logs. You can do this by following these steps: -1. Log in to the AWS Management Console. -2. Navigate to the IAM service. -3. Click on the "Users" option in the left-side menu. -4. Click on the "Add user" button. -5. Enter a user name and select "Programmatic access" as the access type. -6. Click on the "Next: Permissions" button. -7. Attach the "CloudWatchLogsReadOnlyAccess" policy to the user. -8. Click on the "Next: Review" button. -9. Review the user details and click on the "Create user" button. -10. Copy the `access_key` and `access_key_secret` displayed on the next screen and use them when creating an instance of the `CloudwatchLogsProvider` provider. - -## Notes -*No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page* - -## Useful Links -*No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page* diff --git a/docs/providers/documentation/cloudwatch-metrics.mdx b/docs/providers/documentation/cloudwatch-metrics.mdx deleted file mode 100644 index 5c2dcc274..000000000 --- a/docs/providers/documentation/cloudwatch-metrics.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "AWS CloudWatch Metrics" -sidebarTitle: "CloudWatch Metrics" -description: "CloudWatch Metrics Provider is a provider used to query AWS CloudWatch Metrics" ---- - -WIP 👨🏻‍💻 - -## Inputs - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ - -## Outputs - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ - -## Authentication Parameters - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ - -## Connecting with the Provider - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ - -## Notes - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ - -## Useful Links - -_No information yet, feel free to contribute it using the "Edit this page" link the buttom of the page_ diff --git a/docs/providers/documentation/cloudwatch-provider.mdx b/docs/providers/documentation/cloudwatch-provider.mdx new file mode 100644 index 000000000..992751648 --- /dev/null +++ b/docs/providers/documentation/cloudwatch-provider.mdx @@ -0,0 +1,108 @@ +--- +title: "CloudWatch" +sidebarTitle: "CloudWatch Provider" +description: "CloudWatch provider enables seamless integration with AWS CloudWatch for alerting and monitoring, directly pushing alarms into Keep." +--- + +## Overview + +The CloudWatch Provider offers a direct integration with AWS CloudWatch, enabling Keep users to receive CloudWatch alarms within the Keep platform. This integration centralizes the monitoring and alerting capabilities, allowing for timely responses to changes in the infrastructure or application health. + +### Key Features: + +- **Webhook Integration**: Facilitates automatic subscription to AWS SNS topics linked with CloudWatch alarms, ensuring that Keep is notified of all relevant alarms. +- **Support for Custom SNS Topics**: Allows the use of both pre-existing SNS topics and the specification of custom SNS topics for alarm notifications. +- **Broad Monitoring Scope**: Utilizes CloudWatch's comprehensive alarm system to monitor application and infrastructure health. +- **Adaptable Authentication**: Accommodates both permanent and temporary AWS credentials to suit various security and operational requirements. + +## Connecting with the Provider + +To integrate CloudWatch with Keep, you'll need the following: + +- An AWS account with permissions to access CloudWatch and SNS services. +- A configured Keep account with API access. +- Appropriate AWS IAM permissions for the CloudWatch provider. + +## Required AWS IAM Permissions (Scopes) + +To ensure the CloudWatch provider operates seamlessly, certain AWS IAM permissions (referred to as "scopes") are necessary. These scopes enable the provider to perform actions such as reading alarm details, updating alarm configurations, and subscribing to SNS topics. Below is a list of the required scopes along with explanations: + +### Mandatory Scopes + +- **`cloudwatch:DescribeAlarms`** + - **Description**: Necessary to retrieve information about CloudWatch alarms. + - **Documentation**: [API_DescribeAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DescribeAlarms.html) + - **Alias**: Describe Alarms + - **Mandatory**: Yes + - This scope is crucial for the provider to fetch and list all CloudWatch alarms. + +### Optional Scopes + +- **`cloudwatch:PutMetricAlarm`** + - **Description**: Required to update alarm configurations, particularly to add Keep as an SNS action on alarms. + - **Documentation**: [API_PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) + - **Alias**: Update Alarms + - This scope allows the modification of existing CloudWatch alarms to integrate with Keep notifications. + +- **`sns:ListSubscriptionsByTopic`** + - **Description**: Allows listing all subscriptions for a given SNS topic, enabling Keep to subscribe itself. + - **Documentation**: [SNS Access Policy](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-language-api-permissions-reference.html) + - **Alias**: List Subscriptions + - Essential for the provider to manage subscriptions to SNS topics for alarm notifications. + +- **`logs:GetQueryResults`** + - **Description**: Required for retrieving the results of CloudWatch Logs Insights queries. + - **Documentation**: [API_GetQueryResults](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetQueryResults.html) + - **Alias**: Read Query Results + - Enables the provider to fetch query results from CloudWatch Logs Insights. + +- **`logs:DescribeQueries`** + - **Description**: Necessary to describe the results of CloudWatch Logs Insights queries. + - **Documentation**: [API_DescribeQueries](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeQueries.html) + - **Alias**: Describe Query Results + - This scope is used to access detailed information about queries executed in CloudWatch Logs Insights. + +- **`logs:StartQuery`** + - **Description**: Allows starting CloudWatch Logs Insights queries. + - **Documentation**: [API_StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html) + - **Alias**: Start Logs Query + - Critical for initiating logs analysis and queries within CloudWatch Logs Insights. + +- **`iam:SimulatePrincipalPolicy`** + - **Description**: Permits Keep to test the scopes of the current IAM role without making any resource modifications. + - **Documentation**: [API_SimulatePrincipalPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html) + - **Alias**: Simulate IAM Policy + - This scope is useful for verifying the permissions associated with the IAM role used by Keep, ensuring it has the necessary access without altering any AWS resources. + +While some scopes are optional, having them configured can enhance the integration capabilities and provide a more comprehensive monitoring solution within Keep. + +### Authentication Configuration + +Connecting CloudWatch to Keep requires: + +- **AWS Access Key & Secret**: Your AWS credentials with access to CloudWatch and SNS. +- **Region**: The AWS region your CloudWatch alarms and SNS topics reside in. +- **Session Token** (optional): Necessary for temporary AWS credentials. +- **CloudWatch SNS Topic** (optional): An ARN or name of the SNS topic for sending notifications. Optional if your alarms are already configured with an SNS topic. + +## Setting Up the Integration + +For a seamless setup process, ensure your AWS IAM roles are properly configured with the necessary permissions for CloudWatch and SNS access. + +### Steps: + +1. **Configure AWS IAM Roles**: Ensure the IAM role used by the CloudWatch provider has permissions for `cloudwatch:DescribeAlarms`, `cloudwatch:PutMetricAlarm`, `sns:ListSubscriptionsByTopic`, and other relevant actions. +2. **Specify Authentication Details**: In the Keep platform, enter the AWS Access Key, Secret, and Region details in the CloudWatch provider configuration. +3. **Set Up SNS Topic (Optional)**: If using a custom SNS topic, specify its ARN or name in the provider configuration. Keep will use this topic to listen for alarm notifications. +4. **Activate the Provider**: Finalize the setup in Keep to start receiving CloudWatch alarms. + +## Troubleshooting + +- Ensure the AWS credentials provided have the correct permissions and are not expired. +- Verify that the SNS topics are correctly configured to send notifications to Keep. +- Check the CloudWatch alarms to ensure they are active and correctly configured to trigger under the desired conditions. + +## Useful Links + +- [AWS CloudWatch Documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) +- [AWS SNS Documentation](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)