feat(amplify): add compute role support for Amplify branches

packages/@aws-cdk/aws-amplify-alpha/README.md

@@ -268,6 +268,15 @@ const amplifyApp = new amplify.App(this, 'MyApp', {
 });
 ```
 
+It is also possible to override the compute role for a specific branch by setting `computeRole` in `Branch`:
+
+```ts
+declare const computeRole: iam.Role;
+declare const amplifyApp: amplify.App
+
+const branch = amplifyApp.addBranch("dev", { computeRole });
+```
+
 ## Cache Config
 
 Amplify uses Amazon CloudFront to manage the caching configuration for your hosted applications. A cache configuration is applied to each app to optimize for the best performance.

packages/@aws-cdk/aws-amplify-alpha/lib/app.ts

@@ -6,7 +6,7 @@ import { CfnApp } from 'aws-cdk-lib/aws-amplify';
 import { BasicAuth } from './basic-auth';
 import { Branch, BranchOptions } from './branch';
 import { Domain, DomainOptions } from './domain';
-import { renderEnvironmentVariables } from './utils';
+import { renderEnvironmentVariables, isServerSideRendered } from './utils';
 import { addConstructMetadata, MethodMetadata } from 'aws-cdk-lib/core/lib/metadata-resource';
 import { propertyInjectable } from 'aws-cdk-lib/core/lib/prop-injectable';
 
@@ -237,6 +237,11 @@ export class App extends Resource implements IApp, iam.IGrantable {
    */
   public readonly computeRole?: iam.IRole;
 
+  /**
+   * The platform of the app
+   */
+  public readonly platform?: Platform;
+
   private readonly customRules: CustomRule[];
   private readonly environmentVariables: { [name: string]: string };
   private readonly autoBranchEnvironmentVariables: { [name: string]: string };
@@ -256,7 +261,8 @@ export class App extends Resource implements IApp, iam.IGrantable {
     this.grantPrincipal = role;
 
     let computedRole: iam.IRole | undefined;
-    const isSSR = props.platform === Platform.WEB_COMPUTE || props.platform === Platform.WEB_DYNAMIC;
+    const appPlatform = props.platform || Platform.WEB;
+    const isSSR = isServerSideRendered(appPlatform);
 
     if (props.computeRole) {
       if (!isSSR) {
@@ -272,6 +278,8 @@ export class App extends Resource implements IApp, iam.IGrantable {
 
     const sourceCodeProviderOptions = props.sourceCodeProvider?.bind(this);
 
+    this.platform = appPlatform;
+
     const app = new CfnApp(this, 'Resource', {
       accessToken: sourceCodeProviderOptions?.accessToken?.unsafeUnwrap(), // Safe usage
       autoBranchCreationConfig: props.autoBranchCreation && {
@@ -302,7 +310,7 @@ export class App extends Resource implements IApp, iam.IGrantable {
       oauthToken: sourceCodeProviderOptions?.oauthToken?.unsafeUnwrap(), // Safe usage
       repository: sourceCodeProviderOptions?.repository,
       customHeaders: props.customResponseHeaders ? renderCustomResponseHeaders(props.customResponseHeaders) : undefined,
-      platform: props.platform || Platform.WEB,
+      platform: appPlatform,
     });
 
     this.appId = app.attrAppId;

packages/@aws-cdk/aws-amplify-alpha/lib/branch.ts

@@ -9,13 +9,14 @@ import {
   Duration,
   NestedStack,
   Stack,
+  ValidationError,
 } from 'aws-cdk-lib/core';
 import { Provider } from 'aws-cdk-lib/custom-resources';
 import { Construct } from 'constructs';
 import { CfnBranch } from 'aws-cdk-lib/aws-amplify';
-import { IApp } from './app';
+import { App, IApp } from './app';
 import { BasicAuth } from './basic-auth';
-import { renderEnvironmentVariables } from './utils';
+import { renderEnvironmentVariables, isServerSideRendered } from './utils';
 import { AssetDeploymentIsCompleteFunction, AssetDeploymentOnEventFunction } from '../custom-resource-handlers/dist/aws-amplify-alpha/asset-deployment-provider.generated';
 import { addConstructMetadata, MethodMetadata } from 'aws-cdk-lib/core/lib/metadata-resource';
 import { propertyInjectable } from 'aws-cdk-lib/core/lib/prop-injectable';
@@ -137,6 +138,16 @@ export interface BranchOptions {
    * @default None - Default setting is no skew protection.
    */
   readonly skewProtection?: boolean;
+
+  /**
+   * The IAM role to assign to a branch of an SSR app.
+   * The SSR Compute role allows the Amplify Hosting compute service to securely access specific AWS resources based on the role's permissions.
+   *
+   * This role overrides the app-level compute role.
+   *
+   * @default undefined - No specific role for the branch. If the app has a compute role, it will be inherited.
+   */
+  readonly computeRole?: iam.IRole;
 }
 
 /**
@@ -183,6 +194,15 @@ export class Branch extends Resource implements IBranch {
     // Enhanced CDK Analytics Telemetry
     addConstructMetadata(this, props);
 
+    if (props.app instanceof App) {
+      const platform = props.app.platform;
+      const isSSR = isServerSideRendered(platform);
+
+      if (props.computeRole && !isSSR) {
+        throw new ValidationError('`computeRole` can only be specified for branches of apps with `Platform.WEB_COMPUTE` or `Platform.WEB_DYNAMIC`.', this);
+      }
+    }
+
     this.environmentVariables = props.environmentVariables || {};
 
     const branchName = props.branchName || id;
@@ -199,6 +219,7 @@ export class Branch extends Resource implements IBranch {
       stage: props.stage,
       enablePerformanceMode: props.performanceMode,
       enableSkewProtection: props.skewProtection,
+      computeRoleArn: props.computeRole?.roleArn,
     });
 
     this.arn = branch.attrArn;

packages/@aws-cdk/aws-amplify-alpha/lib/utils.ts

@@ -1,3 +1,12 @@
+import { Platform } from './app';
+
 export function renderEnvironmentVariables(vars: { [name: string]: string }) {
   return Object.entries(vars).map(([name, value]) => ({ name, value }));
 }
+
+/**
+ * Utility function to check if the platform is a server-side rendering platform
+ */
+export function isServerSideRendered(platform?: Platform): boolean {
+  return platform === Platform.WEB_COMPUTE || platform === Platform.WEB_DYNAMIC;
+}

packages/@aws-cdk/aws-amplify-alpha/test/branch.test.ts

@@ -3,6 +3,7 @@ import { Template } from 'aws-cdk-lib/assertions';
 import { Asset } from 'aws-cdk-lib/aws-s3-assets';
 import { SecretValue, Stack } from 'aws-cdk-lib';
 import * as amplify from '../lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
 
 let stack: Stack;
 let app: amplify.App;
@@ -154,3 +155,37 @@ test('with skew protection', () => {
     EnableSkewProtection: true,
   });
 });
+
+test('with compute role', () => {
+  // WHEN
+  const computeRole = new iam.Role(stack, 'ComputeRole', {
+    assumedBy: new iam.ServicePrincipal('amplify.amazonaws.com'),
+  });
+
+  const ssrApp = new amplify.App(stack, 'SsrApp', {
+    platform: amplify.Platform.WEB_COMPUTE,
+  });
+
+  ssrApp.addBranch('main', { computeRole });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::Amplify::Branch', {
+    ComputeRoleArn: stack.resolve(computeRole.roleArn),
+  });
+});
+
+test('throws error when compute role provided for WEB platform', () => {
+  // WHEN
+  const computeRole = new iam.Role(stack, 'ComputeRoleWeb', {
+    assumedBy: new iam.ServicePrincipal('amplify.amazonaws.com'),
+  });
+
+  const webApp = new amplify.App(stack, 'WebApp', {
+    platform: amplify.Platform.WEB,
+  });
+
+  // THEN
+  expect(() => {
+    webApp.addBranch('main', { computeRole });
+  }).toThrow(/`computeRole` can only be specified for branches of apps with `Platform.WEB_COMPUTE` or `Platform.WEB_DYNAMIC`./);
+});

packages/@aws-cdk/aws-amplify-alpha/test/integ.branch-compute-role.js.snapshot/cdk-amplify-branch-compute-role.template.json

@@ -0,0 +1,134 @@
+{
+ "Resources": {
+  "ComputeRole65BDBE3E": {
+   "Type": "AWS::IAM::Role",
+   "Properties": {
+    "AssumeRolePolicyDocument": {
+     "Statement": [
+      {
+       "Action": "sts:AssumeRole",
+       "Effect": "Allow",
+       "Principal": {
+        "Service": "amplify.amazonaws.com"
+       }
+      }
+     ],
+     "Version": "2012-10-17"
+    }
+   }
+  },
+  "AppRole1AF9B530": {
+   "Type": "AWS::IAM::Role",
+   "Properties": {
+    "AssumeRolePolicyDocument": {
+     "Statement": [
+      {
+       "Action": "sts:AssumeRole",
+       "Effect": "Allow",
+       "Principal": {
+        "Service": "amplify.amazonaws.com"
+       }
+      }
+     ],
+     "Version": "2012-10-17"
+    }
+   }
+  },
+  "AppComputeRole426920E4": {
+   "Type": "AWS::IAM::Role",
+   "Properties": {
+    "AssumeRolePolicyDocument": {
+     "Statement": [
+      {
+       "Action": "sts:AssumeRole",
+       "Effect": "Allow",
+       "Principal": {
+        "Service": "amplify.amazonaws.com"
+       }
+      }
+     ],
+     "Version": "2012-10-17"
+    }
+   }
+  },
+  "AppF1B96344": {
+   "Type": "AWS::Amplify::App",
+   "Properties": {
+    "BasicAuthConfig": {
+     "EnableBasicAuth": false
+    },
+    "CacheConfig": {
+     "Type": "AMPLIFY_MANAGED_NO_COOKIES"
+    },
+    "ComputeRoleArn": {
+     "Fn::GetAtt": [
+      "AppComputeRole426920E4",
+      "Arn"
+     ]
+    },
+    "IAMServiceRole": {
+     "Fn::GetAtt": [
+      "AppRole1AF9B530",
+      "Arn"
+     ]
+    },
+    "Name": "App",
+    "Platform": "WEB_COMPUTE"
+   }
+  },
+  "AppmainF505BAED": {
+   "Type": "AWS::Amplify::Branch",
+   "Properties": {
+    "AppId": {
+     "Fn::GetAtt": [
+      "AppF1B96344",
+      "AppId"
+     ]
+    },
+    "BranchName": "main",
+    "ComputeRoleArn": {
+     "Fn::GetAtt": [
+      "ComputeRole65BDBE3E",
+      "Arn"
+     ]
+    },
+    "EnableAutoBuild": true,
+    "EnablePullRequestPreview": true
+   }
+  }
+ },
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}