UPDATE Readme files (#9)

* UPDATE Readme files

Co-authored-by: Francesco Rossi

README.md

@@ -1,65 +1,100 @@
-# Sysdig Monitor for Cloud in AWS
-Monitor repo for Terraform AWS modules in sysdiglabs
+# AWS Cloudwatch Metrics Integration with Sysdig Monitor Terraform Module
 
-For now this repository provides the CloudWatch Metrics Stream functionality
-
-* **[CloudWatch Metrics Stream](https://docs.sysdig.com/en/docs/sysdig-monitor/integrations/cloud-accounts/connect-aws-account/cloudwatch-monitoring/)**:  You can collect both general metadata and various types of CloudWatch metrics from your AWS environment for this purpose <br/>
+This Terraform module integrates AWS Cloudwatch with Sysdig Monitor, enabling users to directly consume AWS Cloudwatch metrics within Sysdig Monitor.
 
 ## Usage
 
-There are several ways to deploy Secure for Cloud in you AWS infrastructure,
+There are several ways to integrate AWS Cloudwatch Metrics with Sysdig Monitor.
 - **[`/examples`](https://github.com/sysdiglabs/terraform-aws-monitor-for-cloud/tree/master/examples)** for the most common scenarios
-  - [CloudWatch Metrics Stream Single Account](https://github.com/sysdiglabs/terraform-aws-monitor-for-cloud/tree/master/examples/cloudwatch-metrics-stream-single-account/)
+  - [Cloudwatch Metrics Stream Single Account](https://github.com/sysdiglabs/terraform-aws-monitor-for-cloud/tree/master/examples/cloudwatch-metrics-stream-single-account/)
 
 <br/>
 
-In the long-term our purpose is to evaluate those use-cases and if they're common enough, convert them into examples to make their usage easier.
-
-## Required Permissions
-
-Sysdig needs some additional permissions in order to show correct status and additional metadata for the CloudWatch Metric Stream integration on the web UI. The following policy should be used when you set up CloudWatch Metric Streams manually and you prefer authenticating using the Access Keys.
+## IAM Permissions for Sysdig Cross-Account Role
+Sysdig requires AWS IAM permissions to display the correct status and metadata for the Cloudwatch Metric Stream integration in the web UI. If `create_new_role` is set to `true`, the following IAM permissions are granted to an IAM Role that Sysdig Monitor will use to display the correct metadata for your Cloudwatch Metric Stream.
 
 ```
-s3:ListBucket
-s3:GetBucketTagging
-s3:GetObject
-s3:GetObjectAttributes
-
-cloudwatch:GetMetricStream
-cloudwatch:ListMetricStreams
-cloudwatch:ListTagsForResource
-
-firehose:DescribeDeliveryStream
+{
+	"Version": "2012-10-17",
+	"Statement": [
+		{
+			"Action": [
+				"s3:ListBucket",
+				"s3:GetObjectAttributes",
+				"s3:GetObject"
+			],
+			"Effect": "Allow",
+			"Resource": "arn:aws:s3:::sysdig-backup-bucket*"
+		},
+		{
+			"Action": [
+				"cloudwatch:ListMetricStreams",
+				"cloudwatch:GetMetricStream"
+			],
+			"Effect": "Allow",
+			"Resource": "arn:aws:cloudwatch:*:<AWS-accountID>:metric-stream/*"
+		},
+		{
+			"Action": "firehose:DescribeDeliveryStream",
+			"Effect": "Allow",
+			"Resource": "arn:aws:firehose:*:<AWS-accountID>:deliverystream/*"
+		},
+		{
+			"Action": [
+				"cloudwatch:ListMetrics",
+				"cloudwatch:GetMetricData"
+			],
+			"Effect": "Allow",
+			"Resource": "*"
+		},
+		{
+			"Action": "ec2:DescribeInstances",
+			"Effect": "Allow",
+			"Resource": "*"
+		},
+		{
+			"Action": [
+				"s3:ListBucket",
+				"s3:ListAllMyBuckets"
+			],
+			"Effect": "Allow",
+			"Resource": "*"
+		}
+	]
+}
 ```
 
-### Provisioning Permissions
+### Administrator Permissions for Sysdig Monitor
+A Sysdig Monitor API Token that has Administrator privileges is necessary for configuring an integration between AWS Cloudwatch and Sysdig Monitor.
 
-Terraform provider credentials/token, requires `Administrative` permissions in order to be able to create the
-resources specified in the per-example diagram.
+### Getting your `sysdig_aws_account_id` and `sysdig_external_id`
+In order to establish the cross-account IAM role that Sysdig Monitor uses to connect with your AWS Metric Stream, it is necessary to fetch the `sysdig_external_id` and `sysdig_aws_account_id` associated with your Sysdig instance. This is the Sysdig AWS account ID **NOT** your AWS account ID. An API has been developed to make this process easier. You will need to use the correct API endpoint depending on your [sysdig_monitor_url](https://docs.sysdig.com/en/docs/administration/saas-regions-and-ip-ranges). For example, the following example uses the **US East** endpoint.
 
-Some components may vary, or may be deployed on different accounts (depending on the example). You can check full resources on each module "Resources" section in their README's. You can also check our source code and suggest changes.
 
-This would be an overall schema of the **created resources**, for the default setup.
-
-- CloudWatch / S3 / Kinesis Firehose
-- SSM Parameter for Sysdig API Token Storage
-- Sysdig role for Compliance
+```bash
+curl --location 'https://app.sysdigcloud.com/api/v2/providers/info/awsCloudInformation' \
+--header 'Content-Type: application/json' \
+--header "Authorization: Bearer $SYSDIG_MONITOR_API_TOKEN"
+{"apiToken":"11111111-1111-1111-1111-111111111111",
+"externalId":"11111111-2222-3333-4444-555555555555",
+"awsSystemAccountId":"123456789123"}
+```
 
-## Upgrading
+The `sysdig_aws_account_id`, and `sysdig_external_id` are all needed to configure the AWS Cloudwatch integration with Sysdig Monitor when using role delegation(`create_new_role = true`).
 
-1. Uninstall previous deployment resources before upgrading
-  ```
-  $ terraform destroy
-  ```
+### AWS Resources Created for the AWS Cloudwatch Metrics Integration
+Precise AWS resources may vary depending on module configuration but in general, the following AWS resources are created as part of the AWS Cloudwatch Metrics Integration.
 
-2. Upgrade the full terraform example with
-  ```
-  $ terraform init -upgrade
-  $ terraform plan
-  $ terraform apply
-  ```
-
-<br/>
+* aws_cloudwatch_log_group.sysdig_stream_logs
+* aws_cloudwatch_log_stream.http_log_stream
+* aws_cloudwatch_log_stream.s3_backup
+* aws_cloudwatch_metric_stream.sysdig_metris_stream_all_namespaces
+* aws_iam_role.service_role
+* aws_iam_role.sysdig_cloudwatch_integration_monitoring_role
+* aws_iam_role.sysdig_cloudwatch_metric_stream_role
+* aws_iam_role_policy.cloud_monitoring_policy
+* aws_kinesis_firehose_delivery_stream.sysdig_metric_kinesis_firehose
+* aws_s3_bucket.sysdig_stream_backup_bucket
 
 ## Authors
 
@@ -69,4 +104,3 @@ Module is maintained and supported by [Sysdig](https://sysdig.com).
 
 Apache 2 Licensed. See LICENSE for full details.
 
-

examples/cloudwatch-metrics-stream-single-account/README.md

@@ -1,31 +1,30 @@
-# Sysdig Monitor for Cloud in AWS<br/>[ Example :: CloudWatch Metrics Stream Single Account ]
-
-Deploy CloudWatch Metrics Stream feature in a single AWS account.<br/>
-All the required resources and workloads will be run under the same account.
+# AWS Cloudwatch Metrics Integration with Sysdig Monitor<br/>[ Example :: CloudWatch Metrics Stream Single Account ]
 
+Deploy AWS Cloudwatch Metrics Integration with Sysdig Monitor for a single AWS account.<br/>
 
 ### Notice
-* **Resource creation inventory** Find all the resources created by Sysdig examples in the resource-group `sysdig-monitor-for-cloud` (AWS Resource Group & Tag Editor) <br/><br/>
-* **Deployment cost** This example will create resources that cost money.<br/>Run `terraform destroy` when you don't need them anymore
+The following examples create AWS resources that incur charges which are not part of your Sysdig subscription.
 
 ![diagram](https://raw.githubusercontent.com/sysdiglabs/terraform-aws-monitor-for-cloud/main/examples/cloudwatch-metrics-stream-single-account/diagram.png)
 
 ## Prerequisites
 
-Minimum requirements:
+### Getting your `sysdig_aws_account_id` and `sysdig_external_id`
+In order to establish the cross-account IAM role that Sysdig Monitor uses to connect with your AWS Metric Stream, it is necessary to fetch the `sysdig_external_id` and `sysdig_aws_account_id` associated with your Sysdig instance. This is the Sysdig AWS account ID **NOT** your AWS account ID. An API has been developed to make this process easier. You will need to use the correct API endpoint depending on your [sysdig_monitor_url](https://docs.sysdig.com/en/docs/administration/saas-regions-and-ip-ranges). For example, the following example uses the **US East** endpoint.
 
-1. Configure [Terraform **AWS** Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
-2. Monitor requirements, as input variable value
-    ```
-    sysdig_monitor_api_token=<Sysdig API Key>
-    sysdig_aws_account_id=<Sysdig AWS accountId>
-    sysdig_external_id=<Sysdig external ID>
-    ```
 
+```bash
+curl --location 'https://app.sysdigcloud.com/api/v2/providers/info/awsCloudInformation' \
+--header 'Content-Type: application/json' \
+--header "Authorization: Bearer $SYSDIG_MONITOR_API_TOKEN"
+{"apiToken":"11111111-1111-1111-1111-111111111111",
+"externalId":"11111111-2222-3333-4444-555555555555",
+"awsSystemAccountId":"123456789123"}
+```
 
-## Usage
+The `sysdig_aws_account_id`, and `sysdig_external_id` are all needed to configure the AWS Cloudwatch integration with Sysdig Monitor when using role delegation(`create_new_role = true`).
 
-For quick testing, use this snippet on your terraform files
+## Usage
 
 ### One region with role delegation authentication
 
@@ -51,7 +50,7 @@ module "cloudwatch_metrics_stream_single_account" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
    sysdig_aws_account_id = "xxxx-xxxx-xxxx"
    monitoring_role_name = "TerraformSysdigMonitoringRole"
    create_new_role = true
@@ -89,7 +88,7 @@ module "cloudwatch_metrics_stream_single_account" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
    secret_key = "Xxx5XX2xXx/Xxxx+xxXxXXxXxXxxXXxxxXXxXxXx"
    access_key_id = "XXXXX33XXXX3XX3XXX7X"
    exclude_filters = [ 
@@ -126,7 +125,7 @@ module "cloudwatch_metrics_stream_single_account_eu_west_1" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
    sysdig_aws_account_id = "xxxx-xxxx-xxxx"
    monitoring_role_name = "TerraformSysdigMonitoringRole"
    create_new_role = true
@@ -152,7 +151,7 @@ module "cloudwatch_metrics_stream_single_account_eu_central_1" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
 
    providers = {
       aws = aws.eu-central-1
@@ -185,7 +184,7 @@ module "cloudwatch_metrics_stream_single_account_eu_west_1" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
    secret_key = "Xxx5XX2xXx/Xxxx+xxXxXXxXxXxxXXxxxXXxXxXx"
    access_key_id = "XXXXX33XXXX3XX3XXX7X"
    exclude_filters = [ 
@@ -209,7 +208,7 @@ module "cloudwatch_metrics_stream_single_account_eu_central_1" {
    source = "sysdiglabs/monitor-for-cloud/aws//modules/cloud-watch-metrics-stream"
 
    sysdig_monitor_api_token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-   sysdig_site = "https://<sysdig-endpoint>"
+   sysdig_monitor_url = "https://<sysdig-endpoint>"
 
    providers = {
       aws = aws.eu-central-1
@@ -248,7 +247,7 @@ $ terraform apply
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 |<a name="sysdig_monitor_api_token"></a> [sysdig\_monitor\_api\_token](#input\_sysdig\_monitor\_api\_token) | Your Sysdig API Key | `string` | n/a | yes |
-|<a name="sysdig_site"></a> [sysdig\_site](#input\_sysdig\_site) | Sysdig input endpoint | `string` | n/a | yes |
+|<a name="sysdig_monitor_url"></a> [sysdig\_site](#input\_sysdig\_site) | Sysdig input endpoint | `string` | n/a | yes |
 |<a name="sysdig_aws_account_id"> </a> [sysdig\_aws\_account\_id](#input\_sysdig\_aws\_account\_id) | Sysdig AWS accountId that will assume MonitoringRole to check status of CloudWatch metric stream | `string` | `""` | no |
 |<a name="monitoring_role_name"></a> [monitoring\_role\_name](#input\_monitoring\_role\_name) | The role name used for delegation over the customer resources towards the Sysdig AWS account. Only for AWS when the authentication mode is role delegation instead of secret key | `string` | `"SysdigCloudwatchIntegrationMonitoringRole"`| no |
 |<a name="create_new_role"></a> [create\_new\_role](#input\_create\_new\_role) | Whether the role above already exists or should be created from scratch | `bool` | false | no |

examples/cloudwatch-metrics-stream-single-account/main.tf

@@ -5,7 +5,7 @@ module "cloudwatch_metric_stream" {
     source = "../../modules/cloud-watch-metrics-stream"
 
     sysdig_monitor_api_token = var.sysdig_monitor_api_token
-    sysdig_site = var.sysdig_site
+    sysdig_monitor_url = var.sysdig_monitor_url
     sysdig_aws_account_id = var.sysdig_aws_account_id
     monitoring_role_name = var.monitoring_role_name
     create_new_role = var.create_new_role

examples/cloudwatch-metrics-stream-single-account/variables.tf

@@ -8,11 +8,11 @@ variable "sysdig_monitor_api_token" {
     }
 }
 
-variable "sysdig_site" {
+variable "sysdig_monitor_url" {
     description = "Sysdig input endpoint"
     type        = string
     validation {
-        condition     = length(var.sysdig_site) > 1
+        condition     = length(var.sysdig_monitor_url) > 1
         error_message = "Sysdig input endpoint is required."
     }
 }

modules/cloud-watch-metrics-stream/README.md

@@ -46,7 +46,7 @@ No modules.
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 |<a name="sysdig_monitor_api_token"></a> [sysdig\_monitor\_api\_token](#input\_sysdig\_monitor\_api\_token) | Your Sysdig API Key | `string` | n/a | yes |
-|<a name="sysdig_site"></a> [sysdig\_site](#input\_sysdig\_site) | Sysdig input endpoint | `string` | n/a | yes |
+|<a name="sysdig_monitor_url"></a> [sysdig\_monitor\_url](#input\_sysdig\_site) | Sysdig input endpoint | `string` | n/a | yes |
 |<a name="sysdig_aws_account_id"> </a> [sysdig\_aws\_account\_id](#input\_sysdig\_aws\_account\_id) | Sysdig AWS accountId that will assume MonitoringRole to check status of CloudWatch metric stream | `string` | n/a | yes |
 |<a name="monitoring_role_name"></a> [monitoring\_role\_name](#input\_monitoring\_role\_name) | The role name used for delegation over the customer resources towards the Sysdig AWS account. Only for AWS when the authentication mode is role delegation instead of secret key | `string` | `"SysdigCloudwatchIntegrationMonitoringRole"`| no |
 |<a name="create_new_role"></a> [create\_new\_role](#input\_create\_new\_role) | Whether the role above already exists or should be created from scratch | `bool` | n/a | no |

modules/cloud-watch-metrics-stream/main.tf

@@ -23,7 +23,7 @@ resource "aws_kinesis_firehose_delivery_stream" "sysdig_metric_kinesis_firehose"
     destination = "http_endpoint"
 
     http_endpoint_configuration {
-        url               = "${var.sysdig_site}/api/awsmetrics/v1/input"
+        url               = "${var.sysdig_monitor_url}/api/awsmetrics/v1/input"
         name              = "Event intake"
         access_key        = var.sysdig_monitor_api_token
         role_arn          = aws_iam_role.service_role.arn

modules/cloud-watch-metrics-stream/variables.tf

@@ -8,11 +8,11 @@ variable "sysdig_monitor_api_token" {
     }
 }
 
-variable "sysdig_site" {
+variable "sysdig_monitor_url" {
     description = "Sysdig input endpoint"
     type        = string
     validation {
-        condition     = length(var.sysdig_site) > 1
+        condition     = length(var.sysdig_monitor_url) > 1
         error_message = "Sysdig input endpoint is required."
     }
 }