Skip to content

Commit

Permalink
Merge pull request #31 from forestmvey/template-documentation-improve…
Browse files Browse the repository at this point in the history 
…ments

Documentation Improvements for Serverless Deployment
  • Loading branch information
@sethusrinivasan
sethusrinivasan authored Nov 4, 2023
2 parents aed018c + 67b285c commit 54fbfa6
Showing 1 changed file with 128 additions and 14 deletions.
142 changes: 128 additions & 14 deletions serverless/DEVELOPER_README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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",
Expand All @@ -285,12 +284,13 @@ A policy template with the required deployment permissions listed below; ensure
"iam:GetRolePolicy"
],
"Resource": "arn:aws:iam::<account-id>:role/PrometheusTimestreamConnector-IAMLambdaRole-*"
"Resource": "arn:aws:iam::<account-id>:role/PrometheusTimestreamConnector-IAMLambdaRole-*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"cloudformation:CreateChangeSet",
"cloudformation:DescribeStacks",
"cloudformation:DescribeStackEvents",
"cloudformation:DescribeChangeSet",
"cloudformation:ExecuteChangeSet",
Expand All @@ -300,7 +300,8 @@ A policy template with the required deployment permissions listed below; ensure
],
"Resource": [
"arn:aws:cloudformation:<region>:<account-id>:stack/PrometheusTimestreamConnector/*",
"arn:aws:cloudformation:<region>:<account-id>:stack/aws-sam-cli-managed-default/*"
"arn:aws:cloudformation:<region>:<account-id>:stack/aws-sam-cli-managed-default/*",
"arn:aws:cloudformation:<region>:aws:transform/Serverless-2016-10-31"
]
},
{
Expand Down Expand Up @@ -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-bucket>.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
{
Expand All @@ -363,7 +382,7 @@ A policy template with the required execution permissions listed below; ensure t
"timestream:WriteRecords",
"timestream:Select"
],
"Resource": "arn:aws:timestream:<region>:<account-id>:database/<exampleDatabase>/table/<exampleTable>"
"Resource": "arn:aws:timestream:<region>:<account-id>:database/exampleDatabase/table/exampleTable"
},
{
"Effect": "Allow",
Expand All @@ -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 `<account-id>` and `<region>` 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 `<account-id>` and `<region>` 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 = <access key>
aws_secret_access_key = <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.

Expand Down

0 comments on commit 54fbfa6

Please sign in to comment.