Add a variable so people can reset the edge lambda

This could be necessary in the future, so I want to lay the groundwork
now. Also, it's a potentially common need in development.

Author: amazon-meaisiah

BUILDING.md

@@ -146,6 +146,16 @@ AWS SAM CLI profile option: optional specific profile from your AWS credential f
 
 Set this to `true` if you want to enable development mode. It's `false` by default, and unless you're actively developing on the developer portal itself locally, you should generally leave it unset as it disables most protections, including CORS.
 
+### `edgeLambdaRebuildToken: string`
+
+*Default: `'defaultRebuildToken'`*
+
+Change this value if you want to update the edge lambda or its replicator lambda in the next deployment. In general, you shouldn't need to set it unless either 1. you're developing against the project and need to make changes to it, or 2. the project updated that part of the code and you just pulled its changes in preparation to update your deployment.
+
+> Why is this not handled internally? At the time of writing, edge lambdas are difficult to delete due to how long it takes for all their replicas to delete, and you can't delete lambdas with active replicas. This process could take anywhere from a couple hours to several days (well past the largest timeout supported by Lambda), and neither CloudFront nor Lambda currently offer any hooks to know when all the replicas are gone. So edge lambda versions are only created, never deleted, by the template.
+>
+> For this reason, it's better to require the user to explicitly choose when to update the lambda, so that during development, you're not flooded with versions, and during production, you can be better aware of when things change (it's on your account, after all).
+
 ### `samTemplate: string`
 
 *Default: `cloudformation/template.yaml` relative to the repo's root*

cloudformation/template.yaml

@@ -79,6 +79,11 @@ Parameters:
     Description: Provide a token different from the last deployment's token to re-upload the dev portal site's static assets. You can provide a timestamp or GUID on each deployment to always re-upload the assets.
     Default: 'defaultRebuildToken'
 
+  EdgeLambdaRebuildToken:
+    Type: String
+    Description: Provide a token different from the last deployment's token to update the edge lambda. You can provide a timestamp or GUID on each deployment to always update it.
+    Default: 'defaultRebuildToken'
+
   StaticAssetRebuildMode:
     Type: String
     Description: By default, a static asset rebuild doesn't overwrite custom-content. Provide the value `overwrite-content` to replace the custom-content with your local version. Don't do this unless you know what you're doing -- all custom changes in your s3 bucket will be lost. 
@@ -1755,8 +1760,7 @@ Resources:
       ServiceToken: !GetAtt CloudFrontSecurityHeadersLambda.Arn
       Name: !Ref CloudFrontSecurityHeadersLambda
       RoleArn: !GetAtt LambdaEdgeFunctionRole.Arn
-      # To force update this any time the lambda changes
-      RebuildToken: !Ref CloudFrontSecurityHeadersLambda.Version
+      RebuildToken: !Ref EdgeLambdaRebuildToken
 
   CloudFrontEdgeReplicatorRole:
     Type: AWS::IAM::Role

dev-portal/example-deployer.config.js

@@ -32,4 +32,8 @@ module.exports = {
   // cognitoDomainAcmCertArn: 'arn:aws:acm:us-east-1:123456789012:certificate/98765432-9876-9876-9876-987654321098',
   // useRoute53Nameservers: true,
   // feedbackEmail: '[email protected]',
+
+  // Toggle this any time the edge lambda or its replicator lambda need updated. You will be told in
+  // the migration instructions to do so if you need to.
+  // edgeLambdaResetToken: 'reset',
 }

dev-portal/example-dev-deployer.config.js

@@ -31,4 +31,9 @@ module.exports = {
 
   // Set development mode for local use.
   developmentMode: true,
+
+  // Toggle this any time the edge lambda or its replicator lambda are updated. In general, unless
+  // either you're modifying them yourself or they were changed upstream and you just pulled those
+  // changes, you shouldn't need to do anything about this value.
+  // edgeLambdaResetToken: 'reset',
 }

scripts/internal/deploy-template.js

@@ -30,6 +30,7 @@ module.exports = async () => {
     useRoute53Nameservers,
     staticAssetRebuildMode,
     developmentMode,
+    edgeLambdaRebuildToken,
     awsSamCliProfile
   } = deployerConfig
 
@@ -64,6 +65,7 @@ module.exports = async () => {
     ...(customDomainName ? [`CustomDomainName=${customDomainName}`] : []),
     ...(customDomainNameAcmCertArn ? [`CustomDomainNameAcmCertArn=${customDomainNameAcmCertArn}`] : []),
     ...(useRoute53Nameservers ? [`UseRoute53Nameservers=${useRoute53Nameservers}`] : []),
+    ...(edgeLambdaRebuildToken ? [`EdgeLambdaRebuildToken=${edgeLambdaRebuildToken}`] : []),
     '--s3-bucket', buildAssetsBucket,
     ...(awsSamCliProfile ? ['--profile', awsSamCliProfile] : [])
   ])

scripts/internal/get-deployer-config.js

@@ -58,6 +58,7 @@ exports.customDomainNameAcmCertArn = getOptional('customDomainNameAcmCertArn')
 exports.useRoute53Nameservers = getOptional('useRoute53Nameservers')
 exports.staticAssetRebuildMode = getOptional('staticAssetRebuildMode')
 exports.developmentMode = getOptional('developmentMode')
+exports.edgeLambdaRebuildToken = getOptional('edgeLambdaRebuildToken')
 
 // AWS SAM CLI configuration
 exports.awsSamCliProfile = getOptional('awsSamCliProfile')