|
| 1 | +--- |
| 2 | +title: AWS Lambda Development Environment |
| 3 | +description: How to configure AWS Lambda to send data to a development Sentry instance. |
| 4 | +sidebar_order: 200 |
| 5 | +--- |
| 6 | + |
| 7 | +This guide will explain how you can setup a development environment to work on the [AWS Lambda Integration](https://docs.sentry.io/product/integrations/cloud-monitoring/aws-lambda/). The setup includes running a local instance of `sentry` and configuring AWS so that both environments work together. |
| 8 | + |
| 9 | +<Alert level="warning" title="IMPORTANT"> |
| 10 | + |
| 11 | +**This guide is only if you want to send data from an AWS Lambda function to your local `sentry` instance.** |
| 12 | + |
| 13 | +When working on the Sentry AWS Lambda layer from one of the SDKs, the workflow is that you have your example Lambda function in a dev account on AWS and then deploy your local layer to the dev account and attach it to your example function. How do to this in Python is described in the [contribution guide](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md#contributing-to-sentry-aws-lambda-layer) of the Python SDK. |
| 14 | + |
| 15 | +</Alert> |
| 16 | + |
| 17 | +## Configuration of AWS |
| 18 | + |
| 19 | +To emulate a Sentry integration with a project base on AWS Lambda functions you need: |
| 20 | + |
| 21 | +- One AWS account representing Sentry having an IAM and a S3 Bucket containing a JSON config file. |
| 22 | +- One AWS account representing the user that has a example Lambda function. |
| 23 | + |
| 24 | +### Detailed Configuration Steps |
| 25 | + |
| 26 | +For the **“Sentry Account”** in AWS we assume the AWS Account ID is `1111 1111 1111` in this guide. This account can be the shared official dev AWS account of Sentry, or you can create a personal one (credit card required for this) |
| 27 | + |
| 28 | +- Create an **IAM user** in the **“Sentry account”** that can create S3 buckets, and has permission to assume roles. The policy that can be directly attached to the IAM user looks like this: |
| 29 | + |
| 30 | + {/* _TODO: check if we can restrict those permissions more_ */} |
| 31 | + |
| 32 | + ```json |
| 33 | + { |
| 34 | + "Version": "2012-10-17", |
| 35 | + "Statement": [ |
| 36 | + { |
| 37 | + "Sid": "VisualEditor0", |
| 38 | + "Effect": "Allow", |
| 39 | + "Action": "sts:AssumeRole", |
| 40 | + "Resource": "*" |
| 41 | + } |
| 42 | + ] |
| 43 | + } |
| 44 | + ``` |
| 45 | + |
| 46 | +- Create an **S3 Bucket in “Sentry Account”** that is accessible by the public to host the CloudFormation configuration file. (more on this later). The S3 Bucket Policy should look like this (in this example “sentry-dev-cloudformation” is the name of the S3 bucket): |
| 47 | + |
| 48 | + {/* _TODO: check if we can restrict those permissions more_ */} |
| 49 | + |
| 50 | + ```json |
| 51 | + { |
| 52 | + "Version": "2012-10-17", |
| 53 | + "Statement": [ |
| 54 | + { |
| 55 | + "Sid": "Statement1", |
| 56 | + "Effect": "Allow", |
| 57 | + "Principal": "*", |
| 58 | + "Action": "s3:*", |
| 59 | + "Resource": [ |
| 60 | + "arn:aws:s3:::sentry-dev-cloudformation", |
| 61 | + "arn:aws:s3:::sentry-dev-cloudformation/dev.json" |
| 62 | + ] |
| 63 | + } |
| 64 | + ] |
| 65 | + } |
| 66 | + ``` |
| 67 | + |
| 68 | +- Place a **CloudFormation configuration file** called `dev.json` in the S3 bucket of the “Sentry account” mentioned above. The `dev.json` file is a pointer to a “Sentry account” user. The file must be readable by the customer. |
| 69 | + The dev.json must look like this. You need to replace `arn:aws:iam::111111111111:user/sentry` with the ARN of your user: |
| 70 | + |
| 71 | + {/* *TODO: check if we can restrict those permissions more.* */} |
| 72 | + |
| 73 | + ```json |
| 74 | + { |
| 75 | + "Description": "This stack grants write access to your Lambda functions in order to add Sentry error and performance monitoring. After pressing create, wait for the stack to be created before copying your AWS account number and region into the Sentry installation modal.", |
| 76 | + "Resources": { |
| 77 | + "SentryRole": { |
| 78 | + "Type": "AWS::IAM::Role", |
| 79 | + "Properties": { |
| 80 | + "AssumeRolePolicyDocument": { |
| 81 | + "Version": "2012-10-17", |
| 82 | + "Statement": [ |
| 83 | + { |
| 84 | + "Effect": "Allow", |
| 85 | + "Principal": { |
| 86 | + "AWS": "arn:aws:iam::111111111111:user/sentry" |
| 87 | + }, |
| 88 | + "Action": [ |
| 89 | + "sts:AssumeRole" |
| 90 | + ], |
| 91 | + "Condition": { |
| 92 | + "StringEquals": { |
| 93 | + "sts:ExternalId": { |
| 94 | + "Ref": "ExternalId" |
| 95 | + } |
| 96 | + } |
| 97 | + } |
| 98 | + } |
| 99 | + ] |
| 100 | + }, |
| 101 | + "Path": "/", |
| 102 | + "RoleName": "SentryRole", |
| 103 | + "ManagedPolicyArns": [], |
| 104 | + "Policies": [ |
| 105 | + { |
| 106 | + "PolicyName": "sentry-policy", |
| 107 | + "PolicyDocument": { |
| 108 | + "Version": "2012-10-17", |
| 109 | + "Statement": [ |
| 110 | + { |
| 111 | + "Effect": "Allow", |
| 112 | + "Action": [ |
| 113 | + "lambda:UpdateFunctionConfiguration", |
| 114 | + "lambda:ListFunctions", |
| 115 | + "lambda:ListLayerVersions", |
| 116 | + "lambda:GetFunction", |
| 117 | + "lambda:GetLayerVersion", |
| 118 | + "organizations:DescribeAccount" |
| 119 | + ], |
| 120 | + "Resource": "*" |
| 121 | + } |
| 122 | + ] |
| 123 | + } |
| 124 | + } |
| 125 | + ] |
| 126 | + } |
| 127 | + } |
| 128 | + }, |
| 129 | + "Parameters": { |
| 130 | + "ExternalId": { |
| 131 | + "Description": "External ID for securing the role - Do not change", |
| 132 | + "Type": "String" |
| 133 | + } |
| 134 | + } |
| 135 | + } |
| 136 | + ``` |
| 137 | + |
| 138 | + This CloudFormation config file basically gives the user in the “Sentry account” access to assume a role in the “User account” to augment the Lambda functions (add the Sentry Lambda Layer) to instrument them for sending errors/metrics to Sentry |
| 139 | + |
| 140 | +- Create one **AWS** account representing the user and where the Lambda functions of the user live. This account we will call the **User account”**. |
| 141 | + The **“Sentry account”** and the **“User account”** can also be the same account. |
| 142 | + |
| 143 | +Ok, so now you have two AWS accounts and you have set up your CloudFormation config in a S3 bucket that is accessible to the world. Great! |
| 144 | + |
| 145 | +## Configuration of Local Sentry Instance |
| 146 | + |
| 147 | +You need just a default installation of `sentry` on your computer. Please install it following the [Development Environment Setup Guide](https://develop.sentry.dev/development-infrastructure/environment/). |
| 148 | + |
| 149 | +Now you have to tell your sentry installation what AWS account to use and where it can find the CloudFormation configuration. |
| 150 | + |
| 151 | +You can do this by adding the following parameter to your `~/.sentry/config.yml` file: |
| 152 | + |
| 153 | +```yaml |
| 154 | +aws-lambda.access-key-id: AKIXXXXXXXXXXXXXXXXX |
| 155 | +aws-lambda.secret-access-key: IuyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2Xoj |
| 156 | +aws-lambda.cloudformation-url: https://sentry-dev-cloudformation.s3.eu-central-1.amazonaws.com/dev.json |
| 157 | +aws-lambda.node.layer-version: "37" |
| 158 | +aws-lambda.python.layer-version: "142" |
| 159 | +``` |
| 160 | +
|
| 161 | +Explanation: |
| 162 | +
|
| 163 | +- `aws-lambda.access-key-id` AWS access key id of the IAM user created in the “Sentry Account”. |
| 164 | +- `aws-lambda.secret-access-key`AWS secret access key of the IAM user created in the “Sentry Account”. |
| 165 | +- `aws-lambda.cloudformation-url` public accessible URL of the CloudFormation config file that lives in a S3 bucket in the “Sentry Account”. |
| 166 | +- `aws-lambda.node.layer-version` the version of the Lambda layer that should be used for Node Lambda functions. This version number can be found here: [https://github.com/getsentry/sentry-release-registry/tree/master/aws-lambda-layers](https://github.com/getsentry/sentry-release-registry/tree/master/aws-lambda-layers) (Hint: every region can have another version of the Layer installed.) |
| 167 | +- `aws-lambda.python.layer-version` same as above but for Python based Lambda functions. |
| 168 | + |
| 169 | +## Configuration of Ngrok |
| 170 | + |
| 171 | +With [Ngrok](https://ngrok.com/) you get an URL that points to your local computer. So everyone on the internet can talk to your Sentry installation on your computer. |
| 172 | + |
| 173 | +This is needed so your AWS Lambda function can send its errors/tracing to your local Sentry installation. |
| 174 | + |
| 175 | +Follow the instructions on the [Ngrok documentation](https://develop.sentry.dev/development/ngrok/) page to install ngrok. |
| 176 | + |
| 177 | +Now start Ngrok like the following: |
| 178 | + |
| 179 | +```bash |
| 180 | +ngrok http 8000 |
| 181 | +``` |
| 182 | + |
| 183 | +If ngrok starts it outputs the URL that your computer is now available at. Copy the HTTP URL (it should look something like `http://xxxx-xxx-xxx-x-xxx.ngrok.io`). |
| 184 | + |
| 185 | +If you follow the guide in the ngrok page linked above you will get access to the Sentry Ngrok account and you can create a subdomain that is custom and not always changing when you restart ngrok. This is highly recommended. |
| 186 | + |
| 187 | +You now have to tell your sentry installation its new URL by adding the following line to your `~/.sentry/config.yml` : |
| 188 | + |
| 189 | +```yaml |
| 190 | +system.url-prefix: "http://xxxx-xxx-xxx-x-xxx.ngrok.io" |
| 191 | +``` |
| 192 | + |
| 193 | +Make sure to restart all the development environment, to make sure all services know about the new URL. (with `devservices down && devservices up`) |
| 194 | + |
| 195 | +## Start the Local Sentry Server |
| 196 | + |
| 197 | +If you now run your local Sentry with this command, it will have all the information it needs: |
| 198 | + |
| 199 | +```bash |
| 200 | +devservices serve |
| 201 | +``` |
| 202 | + |
| 203 | +You are now ready for serverless integration development. |
| 204 | + |
| 205 | +## Add Sentry to Your Lambda Functions |
| 206 | + |
| 207 | +Log into your local sentry environment at your ngrok URL and follow the [AWS Lambda Guide](https://docs.sentry.io/product/integrations/cloud-monitoring/aws-lambda/) in our documentation to add Sentry instrumentation to your demo AWS Lambda function. |
0 commit comments