CloudFront Deployment

Introduction

Darwinium can be configured to publish workers to Amazon CloudFront. This enables you to perform decisioning at the edge using your CloudFront infrastructure. 

Configuring CloudFront requires an administrator with access to the AWS CloudFront dashboard and the ability to:

• create a Cloudfront Distribution (if there isn't one already)

• create cross-account AWS IAM roles. 

This guide assumes familiarity with your organization's Cloudfront configuration and the setup of IAM roles.

Overview

Darwinium uses the following configuration elements:

• CloudFront Distribution ID

• AWS role ARNs to configure deployments to the distribution and workers to AWS Lambda
  
  A typical Cloudfront deployment on a one-edge deployment device takes approximately 1 hour to setup and validate under a standard configuration. Manual configuration involving Terraform will take longer.
  

  Summary of IAM roles & Policies Needed

   

  Type	Name	Description
  Role	Lambda@Edge Execution role	Role assumed by Darwinium Lambdas on your AWS account when they are running at the edge. Depending on your configuration, this execution role will be setup to write to your events S3 bucket (if bringing your own storage)
  Role	Cloudfront Builder IAM role	Role assumed by Darwinium’s Cloudfront builder tool.
  Policy	Cloudfront builder IAM Policy	Policy associated with the Cloudfront builder IAM role. This is used when you publish changes to your journey. It enables our tool to deploy new lambdas to your infrastructure, create function associations between lambdas and routes on your Cloudfront distribution, and remove these as necessary when there are changes to your Darwinium journey configuration.

   

Deployment Setup

Step 1 - Get External ID from the  Darwinium Portal

1. In the Darwinium portal, navigate to Admin > Nodes

2. Select the node you wish to configure and click

3. A dialog will appear. Select Cloud Deployment in the top tabs, then CloudFront from the left-pill menu

4. A system generated External ID will appear. Copy this to your clipboard - it will be used to configure cross account roles in AWS.

Step 2 - Note your AWS customer details

Login to the AWS administrator console and click on your username to the top right. Note your AWS Account ID:

Step 3 - Create a CloudFront distribution (if needed)

1. Login to the AWS console and navigate to the CloudFront dashboard. Select Distributions from the navigation menu, then Create Distribution.

2. Set the origin domain - this is essentially the domain that exists behind your AWS private network. This typically points to another AWS resource such as an EC2 instance, load balancer or S3 bucket.

3. Additional settings for accessing your origin are configured below. This is contingent upon your origin's configuration and company communication policies. Darwinium recommends using HTTPS only or Match viewer

   

4. Your Origin path should likely be left blank (however this may differ from implementation to implementation)

5. Give your origin a name: eg

   my-service

6. No custom headers are needed by Darwinium, but may be configured as needed by your organization

7. Enable Origin Shield should be set to No

8.  Additional Settings should be left at the AWS defaults:

   • Connection attempts:3

   • Connection timeout:10

   • Response timeout:30

   • Keep-alive timeout:5

Default cache behavior:

The following settings should be set:

•  Path Pattern:  Default (*)

•  Compress objects automatically:  Yes

•  Viewer protocol policy:  Redirect HTTP to HTTPS (this will vary upon your organizations security policies and configuration. Please consult an administrator)

•  Allowed HTTP Methods:  GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE

•  Restrict Viewer Access:  No (this will vary upon your organizations security policies and configuration) 

Cache key and origin requests

Set this to Cache policy and origin request policy: 

•  Cache Policy: CachingOptimized

• Origin Request Policy AllViewer

•  Response Headers Policy: : SimpleCORS (this may vary depending on your organizations security policy 

Additional Settings

Additional settings can be configured as part of the organizations policy. Darwinium recommends creating a Real-time log configuration for troubleshooting the operation of the Darwinium Edge workers

Function associations

These are configured automatically by darwinium and left as  No association 

Settings

Settings Contingent upon your configuration - we recommend selecting Use all edge locations (best performance) and configuring an SSL certificate using the AWS certificate manager. This is also where you will input alternate domain name (CNAME) settings for your edge workers.

Take note of your domains and Distribution ID

Step 4 - Create Lambda@Edge Execution Roles

BYO S3 Event Storage outlines the process for optionally setting up Darwinium with your own S3 bucket to store event details. 

This IAM role will be used by the Darwinium Lambda functions during execution. When you are using a Customer Hosted S3 bucket, the Darwinium Lambda@Edge functions will write encrypted PII data directly to your S3 bucket on your infrastructure, with no part of this write process involving Darwinium infrastructure for maximum security and performance.

In the AWS console:

1. Go to IAM > Roles > Create Role

2. Specify a custom trust policy with the following contents:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Service": [
                       "edgelambda.amazonaws.com",
                       "lambda.amazonaws.com"
                   ]
               },
               "Action": "sts:AssumeRole"
           }
       ]
   }

3. On the Add Permissions menu add the following Policy

   AWSLambdaBasicExecutionRole

4.  If you are using a BYO S3 bucket, add the S3 write-only policy that was created when you setup BYO storage.

5. Choose an appropriate name for the role, and note down the role's ARN once created. It will look like

   arn:aws:iam::123456789:role/lambdarole

Step 5 : Create Darwinium CloudFront builder IAM policy

This IAM policy will be used by Darwinium to create Lambda functions and attach them to a CloudFront distribution

1. Go to IAM > Policies > Create Policy

2. Edit the policy template provided below as follows:

   • For

     arn:aws:lambda:*:AWSACCOUNTID:function:dwn*

     and

     arn:aws:cloudfront::AWSACCOUNTID:function/*

     replace

     AWSACCOUNTID

     with your AWS account ID from step 2. For example:

     arn:aws:lambda:*:123456789:function:dwn*

     and

     arn:aws:cloudfront::123456789:function/*

   • For

     arn:aws:cloudfront::AWSACCOUNTID:distribution/DISTRIBUTION

     replace

     AWSACCOUNTID

     as above, and

     DISTRIBUTION

     with your CloudFront DistributionID. For example:

     arn:aws:cloudfront::123456789:distribution/ABCDEFGHIJKL

   • For

     EXECUTIONROLEARN

     replace the whole string with the execution role ARN you created above. For example:

     arn:aws:iam::123456789:role/lambdarole

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "lambda:CreateFunction",
              "lambda:UpdateFunctionCode",
              "lambda:UpdateFunctionConfiguration",
              "iam:GetRole",
              "iam:PassRole",
              "lambda:GetFunction",
              "lambda:DeleteFunction",
              "lambda:PublishVersion",
              "cloudfront:GetDistribution",
              "cloudfront:UpdateDistribution",
              "cloudfront:GetDistributionConfig",
              "cloudfront:GetFunction",
              "cloudfront:DeleteFunction",
              "cloudfront:DescribeFunction",
              "cloudfront:CreateFunction",
              "cloudfront:UpdateFunction",
              "cloudfront:PublishFunction",
              "lambda:EnableReplication*"
          ],
          "Resource": [
              "arn:aws:lambda:*:AWSACCOUNTID:function:dwn*",
              "arn:aws:cloudfront::AWSACCOUNTID:distribution/DISTRIBUTION",
              "arn:aws:cloudfront::AWSACCOUNTID:function/*",
              "EXECUTIONROLEARN"
          ]
      },
      {
          "Effect": "Allow",
          "Action": [
              "cloudfront:ListResponseHeadersPolicies",
              "lambda:ListFunctions",
              "cloudfront:ListFunctions",
              "cloudfront:ListOriginRequestPolicies",
              "cloudfront:ListCachePolicies",
              "cloudfront:ListDistributions",
              "iam:CreateServiceLinkedRole"
          ],
          "Resource": "*"
      }
  ]
}

3. Save the edited result as the JSON Policy for your new IAM policy

Step 6: Create Darwinium CloudFront builder IAM Role

This IAM Role will be assumed by Darwinium to create Lambda functions and attach them to a CloudFront distribution

1. Go to IAM > Roles > Create Role

2. Edit the policy template provided below, replacing

   EXTERNALID

   EXTERNALID = The ExternalID that you obtained in step 1

   DWNACCOUNTID

   DWNACCOUNTID = Will be supplied directly by Darwinium on install

3. Use the edited result as the custom trust policy for your new IAM Role

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::DWNACCOUNTID:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "EXTERNALID"
                },
                "ArnLike": {
                    "aws:PrincipalArn": "arn:aws:iam::DWNACCOUNTID:role/crossaccountassumers/*"
                }
            }
        }
    ]
}

3. Next, on the Add Permissions menu, select the Darwinium CloudFront builder policy that you created above

4. Choose an appropriate name for the role, and note down the role's ARN once created. It will look like

   arn:aws:iam::123456789:role/cloudfrontbuilderrole

Step 7: Apply CloudFront fields in Darwinium Portal

1. Navigate to the Darwinium portal and login as a user who has sufficient privileges to edit node settings.

2. Select Node settings from the side menu: 

3. Select the node you wish to configure, and select settings

4. Navigate to the CloudFront Deploymentsection, and enter details for

   Distribution ID

   (from step 3),

   Lambda@Edge execution role ARN

   (from step 4) ,

   Deployment Role ARN

   (from step 6).

Publish your first Journey

In order to complete your first deployment, you will need to publish a journey.

see: Editing Overview