Add role based auth to CloudWatch exporter doc

use-timescale/metrics-logging/integrations.md

@@ -40,6 +40,7 @@ Export telemetry data by:
 1.  In the Timescale console, navigate to `Integrations`.
 1.  Click `Create exporter`.
 1.  Choose the telemetry data type that you would like to send to a provider.
+    Datadog provider supports only metrics data type.
 1.  Under `Choose a provider`, choose `Datadog`.
 1.  Choose an AWS region for your exporter to live within Timescale. The
     exporter is only available to database services in the same AWS region.
@@ -79,15 +80,111 @@ alt="Screenshot of the menu for adding a Datadog exporter" />
     you're uncertain, use the default values. For more information on naming log
     groups and logs streams, see [the AWS CloudWatch
     docs][cloudwatch-log-naming].
+1.  Choose which authentication method you would like to use with your
+    exporter. We support CloudWatch credentials and IAM role. `CloudWatch
+    credentials` requires creating an IAM user in your AWS account and sharing
+    credentials of that user with Timescale. `IAM role` requires creating a
+    role with all necessary permissions and sharing only the role with
+    timescale.
+<! -- At this place another branching should begin depending on what user
+selected above. I'm not sure whether we need to represent this graphically by
+adding tabs inside the existing tabs or just keep the options flat and explain
+the alternatives in text. Writing it with text now and hope to get feedback on
+this -->
+<! -- Credentials case begin -- >
 1.  Enter your AWS credentials. To get your AWS keys, you need to create a new
     Identity and Access Management (IAM) user in your AWS console. Make sure
     your new user has restricted access to only Cloudwatch, and keep your keys
     secret. For instructions, see the [AWS documentation][aws-access-keys].
+<! -- Credentials case end -- >
+<! -- IAM role case begin -- >
+1.  We are using [IRSA][irsa] in order to manage access from our cloud to
+    various resources within AWS. In order to grant permissions to a service
+    running in our AWS account to perform actions in your AWS account, the role
+    needs to be setup accordingly. Please refer to this [AWS
+    blog][cross-account-iam-roles] to understand the configuration elements
+    involved into that.
+    The URL that should be used depends on the region where the exporter is being created, it can be taken from this list:
+
+
+ | Region           | Zone          | Location       | URL
+|------------------|---------------|----------------|--------------------|
+| `ap-southeast-1` | Asia Pacific  | Singapore      | `irsa-oidc-discovery-prod-ap-southeast-1.s3.ap-southeast-1.amazonaws.com`
+| `ap-southeast-2` | Asia Pacific  | Sydney         | `irsa-oidc-discovery-prod-ap-southeast-2.s3.ap-southeast-2.amazonaws.com`
+| `ap-northeast-1` | Asia Pacific  | Tokyo          | `irsa-oidc-discovery-prod-ap-northeast-1.s3.ap-northeast-1.amazonaws.com`
+| `ca-central-1`   | Canada        | Central        | `irsa-oidc-discovery-prod-ca-central-1.s3.ca-central-1.amazonaws.com`
+| `eu-central-1`   | Europe        | Frankfurt      | `irsa-oidc-discovery-prod-eu-central-1.s3.eu-central-1.amazonaws.com`
+| `eu-west-1`      | Europe        | Ireland        | `irsa-oidc-discovery-prod-eu-west-1.s3.eu-west-1.amazonaws.com`
+| `eu-west-2`      | Europe        | London         | `irsa-oidc-discovery-prod-eu-west-2.s3.eu-west-2.amazonaws.com`
+| `sa-east-1`      | South America | São Paulo      | `irsa-oidc-discovery-prod-sa-east-1.s3.sa-east-1.amazonaws.com`
+| `us-east-1`      | United States | North Virginia | `irsa-oidc-discovery-prod.s3.us-east-1.amazonaws.com`
+| `us-east-2`      | United States | Ohio           | `irsa-oidc-discovery-prod-us-east-2.s3.us-east-2.amazonaws.com`
+| `us-west-2`      | United States | Oregon         | `irsa-oidc-discovery-prod-us-west-2.s3.us-west-2.amazonaws.com`
+
+A Full example of a role called `my-exporter-role`, that has been configured following the [AWS
+    blog][cross-account-iam-roles] should look like:
+
+- Permission Policy:
+```json
+  {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Action": [
+                    "logs:PutLogEvents",
+                    "logs:CreateLogGroup",
+                    "logs:CreateLogStream",
+                    "logs:DescribeLogStreams",
+                    "logs:DescribeLogGroups",
+                    "logs:PutRetentionPolicy",
+                    "xray:PutTraceSegments",
+                    "xray:PutTelemetryRecords",
+                    "xray:GetSamplingRules",
+                    "xray:GetSamplingTargets",
+                    "xray:GetSamplingStatisticSummaries",
+                    "ssm:GetParameters"
+                ],
+                "Resource": "*"
+            }
+        ]
+    } 
+```
+
+Trust Policy:
+```json
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Principal": {
+                    "Federated": "arn:aws:iam::12345678910:oidc-provider/irsa-oidc-discovery-prod.s3.us-east-1.amazonaws.com"
+                },
+                "Action": "sts:AssumeRoleWithWebIdentity",
+                "Condition": {
+                    "StringEquals": {
+                        "irsa-oidc-discovery-prod.s3.us-east-1.amazonaws.com:aud": "sts.amazonaws.com"
+                    }
+                }
+            },
+            {
+                "Sid": "Statement1",
+                "Effect": "Allow",
+                "Principal": {
+                    "AWS": "arn:aws:iam::12345678910:role/my-exporter-role"
+                },
+                "Action": "sts:AssumeRole"
+            }
+        ]
+    }
+```
+**Note** It's important to not forget adding the role itself as a trusted entity as shown above.
+
+<! -- IAM role case end -- >
+
 1.  Select an AWS Region for your CloudWatch instance.
-1.  <Optional />Define an ARN role to use for uploading metrics or logs. Having a
-    dedicated role with only CloudWatch permissions is a recommended security
-    practice.
-1.  Click `Create exporter`.
+2.  Click `Create exporter`.
 
 <Highlight type="warning">
 AWS keys give access to your AWS services. To keep your AWS account secure,
@@ -199,6 +296,8 @@ Delete any data exporters that you no longer need.
 
 [attach-exporter]: #attach-a-data-exporter-to-a-service
 [aws-access-keys]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console
+[irsa]: https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/
+[cross-account-iam-roles]: https://aws.amazon.com/blogs/containers/cross-account-iam-roles-for-kubernetes-service-accounts/
 [cloudwatch]: https://aws.amazon.com/cloudwatch/
 [cloudwatch-docs]: https://docs.aws.amazon.com/cloudwatch/index.html
 [cloudwatch-log-naming]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html