From 67b285c95e14e1a56294ca055f4dc5ca6228e5cb Mon Sep 17 00:00:00 2001 From: forestmvey Date: Fri, 27 Oct 2023 09:16:57 -0700 Subject: [PATCH] Update documentation refining IAM deployment and execution permissions and clarifying IAM action limitations. Signed-off-by: forestmvey Formatting revisions. Signed-off-by: forestmvey Fix mismatched headers for policies and roles. Signed-off-by: forestmvey --- serverless/DEVELOPER_README.md | 142 +++++++++++++++++++++++++++++---- 1 file changed, 128 insertions(+), 14 deletions(-) diff --git a/serverless/DEVELOPER_README.md b/serverless/DEVELOPER_README.md index 78c474b..bed494c 100644 --- a/serverless/DEVELOPER_README.md +++ b/serverless/DEVELOPER_README.md @@ -244,9 +244,13 @@ See [Troubleshooting](#troubleshooting) section for more details. ### Deployment Permissions -The user **deploying** this project **must** have the following permission allowing the template to perform specific actions: +The user **deploying** this project **must** have the following permissions listed below. Ensure the values of `account-id` and `region` in the resources section are updated before using this template directly. + +> **Note** - All permissions have limited resources except actions that cannot be limited to a specific resource. APIGateway actions cannot limit resources as the resource name is auto generated by the template. See the following documentation for cloudformation, sns, and iam limitations on actions: +[cloudformation](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awscloudformation.html#awscloudformation-actions-as-permissions) +[sns](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonsns.html#amazonsns-actions-as-permissions) +[iam](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) -A policy template with the required deployment permissions listed below; ensure the values of `account-id` and `region` in the resources section are updated before using this template directly: ```json { @@ -256,11 +260,6 @@ A policy template with the required deployment permissions listed below; ensure "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ - "serverlessrepo:CreateCloudFormationTemplate", - "serverlessrepo:GetCloudFormationTemplate", - "serverlessrepo:CreateCloudFormationChangeSet", - "cloudformation:CreateChangeSet", - "cloudformation:DescribeStacks", "cloudformation:ListStacks", "cloudformation:GetTemplateSummary", "iam:ListRoles", @@ -285,12 +284,13 @@ A policy template with the required deployment permissions listed below; ensure "iam:GetRolePolicy" ], "Resource": "arn:aws:iam:::role/PrometheusTimestreamConnector-IAMLambdaRole-*" - "Resource": "arn:aws:iam:::role/PrometheusTimestreamConnector-IAMLambdaRole-*" }, { "Sid": "VisualEditor2", "Effect": "Allow", "Action": [ + "cloudformation:CreateChangeSet", + "cloudformation:DescribeStacks", "cloudformation:DescribeStackEvents", "cloudformation:DescribeChangeSet", "cloudformation:ExecuteChangeSet", @@ -300,7 +300,8 @@ A policy template with the required deployment permissions listed below; ensure ], "Resource": [ "arn:aws:cloudformation:::stack/PrometheusTimestreamConnector/*", - "arn:aws:cloudformation:::stack/aws-sam-cli-managed-default/*" + "arn:aws:cloudformation:::stack/aws-sam-cli-managed-default/*", + "arn:aws:cloudformation::aws:transform/Serverless-2016-10-31" ] }, { @@ -344,14 +345,32 @@ A policy template with the required deployment permissions listed below; ensure "s3:ListAllMyBuckets" ], "Resource": "arn:aws:s3:::aws-sam-cli-managed-default*" + }, + { + "Sid": "VisualEditor6", + "Effect": "Allow", + "Action": [ + "cloudformation:GetTemplateSummary" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "cloudformation:TemplateUrl": [ + // TODO: Update with public s3 bucket with template and connector + "https://.s3.amazonaws.com/template.yml" + ] + } + } } ] } ``` -The user **executing** this project **must** have the following permission allowing the template to perform specific actions: +### Execution Permissions + +The user **executing** this project **must** have the following permissions listed below. Ensure the values of `account-id` and `region` in the resource section are updated before using this template directly. If the name of the database and table differ from the policy resource, be sure to update their values. -A policy template with the required execution permissions listed below; ensure the values of `account-id`, `region`, `exampleDatabase`, and `exampleTable` in the resources section are updated before using this template directly: +> **Note** - Timestream:DescribeEndpoints resource must be `*` as specified under [security_iam_service-with-iam](https://docs.aws.amazon.com/timestream/latest/developerguide/security_iam_service-with-iam.html). ```json { @@ -363,7 +382,7 @@ A policy template with the required execution permissions listed below; ensure t "timestream:WriteRecords", "timestream:Select" ], - "Resource": "arn:aws:timestream:::database//table/" + "Resource": "arn:aws:timestream:::database/exampleDatabase/table/exampleTable" }, { "Effect": "Allow", @@ -376,15 +395,110 @@ A policy template with the required execution permissions listed below; ensure t } ``` +### Create Deployment and Execution Policies + +#### Create Deployment Policy + +1. Open the [AWS management console](https://console.aws.amazon.com/iam/) for AWS IAM. +2. Click `Policies`. +3. Click `Create policy`. +4. Click `JSON`. +5. Remove default policy and paste the Deployment policy into the Policy Editor. +6. Update values for `` and `` for your AWS account. +7. Click `Next`. +8. Enter `TimestreamPrometheusDeploymentPolicy` in the `Policy name` dialog box. +9. Click `Create policy`. + +#### Create Execution Policy + +1. Open the [AWS management console](https://console.aws.amazon.com/iam/) for AWS IAM. +2. Click `Policies`. +3. Click `Create policy`. +4. Click `JSON`. +5. Remove default policy and paste the Execution policy into the Policy Editor. +6. Update values for `` and `` for your AWS account. +7. Click `Next`. +8. Enter `TimestreamPrometheusExecutionPolicy` in the `Policy name` dialog box. +9. Click `Create policy`. + +### Create and Configure Users + +#### Create Deployment User + +1. Open the [AWS management console](https://console.aws.amazon.com/iam) for AWS IAM. +2. Click `Users`. +3. Click `Create User`. +4. Enter `TimestreamPrometheusDeployment` in the `User name` dialog box. +5. Click `Next`. +6. Click `Attach policies directly`. +7. Search for the policy `TimestreamPrometheusDeploymentPolicy` and select the box next to the policy. +8. Click `Next`. +9. Click `Create user`. + +#### Configure Deployment User Credentials + +> **Note**: This portion is only needed if the deploying method for the Prometheus Connector is using one-click deployment. + +1. Open the [AWS management console](https://console.aws.amazon.com/iam) for AWS IAM. +2. Click `Users`. +3. Search for `TimestreamPrometheusDeployment` and select the user. +4. Click `Security credentials`. +6. Click `Enable console access`. +7. Click `Enable` and `Apply`. +8. Save the password to login the user when deploying using the one-click deployment method. + +> **Note**: This portion is only needed if the deploying method for the Prometheus Connector is using the AWS SAM CLI. + +1. Open the [AWS management console](https://console.aws.amazon.com/iam) for AWS IAM. +2. Click `Users`. +3. Search for `TimestreamPrometheusDeployment` and select the user. +4. Click `Create access key` in the Summary box. +6. Click `Application running outside AWS`. +7. Click `Next`. +8. Click `Create access key`. + +Store the `Access key` and `Secret access key` in your `~/.aws/credentials` file with the following format: + +``` +[default] +aws_access_key_id = +aws_secret_access_key = +``` + +#### Create Execution User + +1. Open the [AWS management console](https://console.aws.amazon.com/iam) for AWS IAM. +2. Click `Users`. +3. Click `Create User`. +4. Enter `TimestreamPrometheusExecution` in the `User name` dialog box. +5. Click `Next`. +6. Click `Attach policies directly`. +7. Search for the policy `TimestreamPrometheusExecutionPolicy` and select the box next to the policy. +8. Click `Next`. +9. Click `Create user`. + +#### Configure Execution User Credentials + +1. Open the [AWS management console](https://console.aws.amazon.com/iam) for AWS IAM. +2. Click `Users`. +3. Search for `TimestreamPrometheusExecution` and select the user. +4. Click `Create access key` in the Summary box. +6. Click `Application running outside AWS`. +7. Click `Next`. +8. Click `Create access key`. + +Store the `Access key` and `Secret access key` for later to configure Prometheus for execution. + + ## Template IAM Permissions Running the Prometheus Connector on AWS Lambda allows for a serverless workflow. This section details the [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) permissions created by the template to integrate the Prometheus Connector with Amazon API Gateway and AWS Lambda. -### Template Role +### Execution Policy The `LambdaExecutionPolicy` created by the template allows the lambda function to output logs to cloudwatch. See [README#IAM Role and Policy Configuration](../README.md#iam-role-and-policy-configuration) for the json policy. -### Execution Policy +### Template Role The `TimestreamLambdaRole` is the role used by the template in order to permit AWS lambda and APIGateway deployment. See [README#IAM Role and Policy Configuration](../README.md#iam-role-and-policy-configuration) for the json role used.