Update Cloud trust policy for Lambda deployments (#417)

* Update Cloud trust policy for Lambda deployments * Add CDK role example and link from CDK doc page * Remove sid for brevity
restatedev · Jun 14, 2024 · a407ca3 · a407ca3
1 parent c78c3ac
commit a407ca3
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 15 deletions.
diff --git a/docs/deploy/cloud.md b/docs/deploy/cloud.md
@@ -64,28 +64,79 @@ restate deployments register tunnel://example:9081
 
 To invoke services running on AWS Lambda, Restate Cloud needs to assume an AWS
 identity in the same account that the Lambda is deployed to. Create a new role
-that has permission to invoke your Lambdas and give it the following trust policy:
+that has permission to invoke your Lambda handlers, and give it the following
+trust policy.
+
+<Tabs>
+<TabItem value="json" label="IAM JSON Policy" default>
 
 ```json
 {
-  "Sid": "AllowRestateCloudToAssumeRole",
-  "Effect": "Allow",
-  "Principal": {
-    "AWS": "arn:aws:iam::654654156625:role/RestateCloud"
-  },
-  "Action": ["sts:AssumeRole", "sts:TagSession"],
-  "Condition": {
-    "StringEquals": {
-      "sts:ExternalId": "$ENVIRONMENT_ID"
-    }
-  }
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::654654156625:root"
+            },
+            "Action": "sts:AssumeRole",
+            "Condition": {
+                "StringEquals": {
+                    "aws:PrincipalArn": "arn:aws:iam::654654156625:role/RestateCloud",
+                    "sts:ExternalId": "${ENVIRONMENT_ID}"
+                }
+            }
+        },
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::654654156625:root"
+            },
+            "Action": "sts:TagSession"
+        }
+    ]
 }
 ```
 
-<Admonition type="info" title="Trust policy">
-This trust policy allows the Restate Cloud `us.restate.cloud` region principal to assume your role, as long as it is using an ExternalId that matches your environment ID. The environment ID can be found in the UI and in the output of `restate whoami`.
+<Admonition type="info" title="Environment Identifier">
+Replace the `${ENVIRONMENT_ID}` placeholder with the environment ID can be found in the UI and in the output of `restate whoami`.
+This trust policy allows the Restate Cloud `us.restate.cloud` region principal to assume the role, but only on behalf of the specified environment ID.
 </Admonition>
 
+</TabItem>
+<TabItem value="cdk" label="AWS CDK">
+
+```ts
+const invokerRole = new iam.Role(this, "InvokerRole", {
+  assumedBy: new iam.AccountPrincipal("654654156625")
+    .withConditions({
+      "StringEquals": {
+        "sts:ExternalId": environmentId,
+        "aws:PrincipalArn": "arn:aws:iam::654654156625:role/RestateCloud",
+      },
+    }),
+});
+invokerRole.assumeRolePolicy!.addStatements(
+  new iam.PolicyStatement({
+    principals: [new iam.AccountPrincipal("654654156625")],
+    actions: ["sts:TagSession"],
+  }),
+);
+```
+
+When you use the [Restate CDK construct library](/deploy/lambda/cdk) to deploy
+Lambda handlers, the provided invoker role will automatically be granted access
+to invoke the corresponding functions. Alternatively, you will need to do so
+explicitly.
+
+<Admonition type="info" title="Environment Identifier">
+Use the `environmentId` variable to pass the environment ID can be found in the UI and in the output of `restate whoami`.
+This trust policy allows the Restate Cloud `us.restate.cloud` region principal to assume the role, but only on behalf of the specified environment ID.
+</Admonition>
+
+</TabItem>
+</Tabs>
+
 You can now register your Lambda through the new role:
 
 ```shell

diff --git a/docs/deploy/lambda/cdk.mdx b/docs/deploy/lambda/cdk.mdx
@@ -39,6 +39,9 @@ Define one or more Lambda functions in your CDK stack to model the service handl
 on the SDK and programming language, you may need an additional build process such as Gradle, to bundle your business
 logic in a Lambda-deployable artifact. To deploy Restate services we use the standard CDK Lambda constructs.
 
+For more information about setting up an IAM role that works with Restate Cloud, please see the section on
+[AWS Lambda services](/deploy/cloud#aws-lambda-services).
+
 <Tabs groupId="sdk" queryString>
 <TabItem value="typescript" label="TypeScript" default>
 
@@ -125,7 +128,7 @@ deployer.deployService("RestateService", serviceHandler.currentVersion, restateE
 ```
 
 </TabItem>
-<TabItem value="custom" label="Custom environment" default>
+<TabItem value="custom" label="Custom environment">
 
 You can specify the target Restate environment explicitly: