Part 1a: Run Adobe Target NodeJS SDK for Experimentation and Personalization on Edge Platforms (Akamai Edge Workers)

[#1]

Author: Artur Ciocanu, Jaemi Bremner

Adobe Target always provided best-in-class experimentation and personalization. Our edge network is geographically distributed and we have points of presence in different parts of the world. This allows us to be closer to our customers' users, but sometimes this is not enough, since fundamentally Target always required a network call to retrieve personalized content.

We always knew that this is could be problematic for some of our customers who are looking for near-zero latency for experimentation and personalization. In November 2020 Adobe Target launched NodeJS SDK and Java SDK with On-Device Decisioning capabilities. In a nutshell, On-Device Decisioning allows you to evaluate Target activities on-device avoiding a network roundtrip. For more details please check the official documentation here.

Adobe Target On-Device Decisioning, while great for server-side use cases where you can use one of our SDKs like NodeJS, Java, and soon Python and .NET, can also be used in a serverless setup.

Java and C# are awesome languages, but usually, in a serverless setup, we prefer something a little bit more lightweight like NodeJS or Python. We already mentioned that Adobe Target has an edge network, but it is incomparable to Edge Computing Platforms aka CDNs like AKamai, AWS Cloudfront, or Cloudflare.

This blog is Part 1 In this three-part series that will cover how anyone could use Adobe Target NodeJS SDK to run experimentation and personalization on an edge compute platform. The parts are:

• Part 1a: Akamai Edge Workers and Adobe Target NodeJS SDK
• Part 1b: Akamai Edge Workers and Adobe Target NodeJS SDK
• Part 2: AWS Lambd@Edge and Adobe Target NodeJS SDK
• Part 3: Cloudflare Workers and Adobe Target NodeJS SDK

Step by Step Guide: Akamai Edge Workers and Adobe Target NodeJS SDK

At Adobe Target we are strong proponents of automation and Infrastructure as Code, that's why we love Hashicorp Terraform. For us Terraform provides the right amount of declarative vs imperative code and it has enough escape hatches in case something is missing.

Recently Akamai launched Akamai EdgeWorkers. This is a new offering from Akamai that allows us to create small pieces of logic that can be distributed worldwide and executed in more than 2000+ locations. While we can use. always Akamai Control Center to set up everything, we will be leveraging Terraform and Akamai CLI to ensure we have all the steps codified in Terraform scripts or Akamai CLI commands.

Before we begin there are a few prerequisites:

• Akamai Access: You will need to have access to Akamai and a product that supports EdgeWorkers such as Ion. Also, you should have access to be able to create an API Client. Terraform relies on API Client to be able to authenticate all the API calls during resource provisioning.
• Akamai CLI with EdgeWorkers Package: You will use it to create EdgeWorkers required configurations.
• Terraform: You will use it to create all the required Akamai resources. Please check the official Hashicorp documentation on how to install Terraform on your particular OS. In this article, we will be showing examples using Mac OS X.
• NodeJS: You will use NodeJS to get the Adobe Target NodeJS SDK dependency as well as using NPM to package JavaScript code and prepare it for Akamai EdgeWorkers.

Most of the resources that we will provision in Akamai require:

• group ID
• contract ID
• product ID
• product name

Note: It is recommended that you copy these values somewhere so you have them handy. If you can't find these values, please talk to your Akamai account representative.

Creating Akamai EdgeWorker ID

There are a couple of resources required in order to use Akamai EdgeWorkers and expose it via an HTTP endpoint. Here is the list:

• Akamai EdgeWorker ID
• Akamai property

To create an Akamai EdgeWorker ID we will use Akamai CLI. Here is the command to create an EdgeWorker ID:

$ akamai ew create-id <group ID> <EdgeWorker Name>

Note: Depending on your Akamai setup you might get a menu where you’ll have to select the contract you want to use. Also you might have to select the resource tier for EdgeWorkers, just follow the Akamai CLI instructions it is pretty self-explanatory.

Once everything has been executed successfully you should see the EdgeWorker ID being displayed in a table similar to this one:

---------------------------------------------------------------
--- Created new EdgeWorker Identifier: ------------------------
---------------------------------------------------------------
edgeWorkerId  name              groupId      resourceTierId
------------  ----------------  -------      ------------------
5628          <EdgWorker Name>  <group ID>   <resource tier ID>

NOTE: You’ll have to save the EdgeWorker ID since it will be used later in the Terraform scripts.

Creating EdgeWorker debug secret

While developing with Akamai EdgeWorkers it is extremely important to be able to troubleshoot what is happening behind the scenes. For this, we will need to generate a debug secret. Here is the Akamai CLI command to generate an EdgeWorker debug secret:

$ akamai ew secret

Once the secret is generated we will have to copy it to Terraform variables file. So we could reference the secret in Akamai Property rules.

The Terraform script to create a CP code looks like this:

Creating Content Provider Code

Once we have the EdgeWorker ID setup, the next step is to create a Content Provider code aka CP code. This resource is required to be able to create an Akamai Property.

The Terraform script to create a CP code looks like this:

resource "akamai_cp_code" "cp_code" {
  name        = var.cp_code_name
  contract_id = var.contract_id
  group_id    = var.group_id
  product_id  = var.product_id
}

As you can see, here we are using Terraform variables. This allows us to externalize all the values that might vary between different environments like staging vs production.

Creating Edge Hostname

The next resource that is required for an Akamai Property is the edge hostname. Here is the Terraform script to create an edge hostname.

resource "akamai_edge_hostname" "hostname" {
  product_id    = var.product_id
  contract_id   = var.contract_id
  group_id      = var.group_id
  edge_hostname = var.edge_hostname
  ip_behavior   = "IPV6_COMPLIANCE"
  certificate   = var.certificate_enrollment_id
}

Here we use the same list of required IDs like product, contract, and group. Besides this, we also need a certificate enrollment ID. EdgeWorkers can be invoked ONLY via HTTPS, hence we need a certificate enrollment ID.

Creating Property Rules

An Akamai Property can not be created without property rules. Property rules contain details like caching configurations, origin address, and different behaviours.

Terraform Akamai provider has a helper data element named akamai_property_rules_template that allows us to customize property rules via templates and variables. Here is the Terraform script for our property that references the EdgeWorker ID and EdgeWorker debug secret described earlier:

data "akamai_property_rules_template" "rules" {
  template_file = abspath("${path.root}/property-snippets/rules.json")
  variables {
    name  = "edge_worker_id"
    type  = "string"
    value = var.edge_worker_id
  }
  variables {
    name  = "edge_worker_debug_secret"
    type  = "string"
    value = var.edge_worker_debug_secret
  }
  variables {
    name  = "cp_code_id"
    type  = "number"
    value = replace(akamai_cp_code.cp_code.id, "cpc_", "")
  }
  variables {
    name  = "cp_code_name"
    type  = "string"
    value = var.cp_code_name
  }
  variables {
    name  = "origin_hostname"
    type  = "string"
    value = var.origin_hostname
  }
  variables {
    name  = "product_name"
    type  = "string"
    value = var.product_name
  }
}

As we can see we have a couple of variables that are required in property rules. We already mentioned we need EdgeWorker ID and EdgeWorker debug secret, we also need to add origin hostname, product name, CP code name and CP code ID. CP code ID has to be adjusted a little bit, since by default the IDs returned by Akamai have prefixes. For CP code ID it is cpc_, hence we leverage Terraform replace to get rid of cpc_ and get the real CP code ID.

Creating Property

Finally, when we have EdgeWorker details, CP code, edge hostname and property rules we can create an Akamai property. Here is the Terraform script to create it:

resource "akamai_property" "property" {
  name        = var.property_name
  product_id  = var.product_id
  contract_id = var.contract_id
  group_id    = var.group_id
  hostnames {
    cname_from             = var.external_hostname
    cname_to               = var.edge_hostname
    cert_provisioning_type = "DEFAULT"
  }
  rule_format = "v2020-03-04"
  rules       = data.akamai_property_rules_template.rules.json
}

Nothing extraordinary here, we are using the same required IDs like group, contract, product, and we also reference the property rules template resource to get the final rules JSON value for this property.

Creating and Activating EdgeWorker Bundle

Now that we have all the resources provisioned, we can look into how we can create an Akamai EdgeWorker bundle.

From bundling perspective Akamai EdgeWorkers requires the following:

• main.js: This is the EdgeWorker entry point.
• bundle.json:This contains metadata related to EdgeWorker like version and description. For every code change, we will have to update the version. Otherwise, we won't be able to upload the code.
• tgz archive: This the actual bundle that contains main.js and bundle.json and is uploaded to Akamai network.

To automate the bundling process we will be using NPM and Rollup bundler. NPM will allow us to get all the required dependencies and Rollup will make sure that we bundle everything into a single main.js file. We will use NPM scripts to automate all of the builds and bundling steps. To build the final Akamai EdgeWorker bundle we will execute:

$ npm run build

This will create a tgz archive under dist folder.

To upload the newly created bundle we will use Akamai CLI and run the following command:

$ akamai ew upload --bundle=<path to tgz archive> <edge worker ID>

Once a new version of the bundle has been uploaded we can activate it using Akamai CLI and running this command:

$ akamai ew activate <edge worker iD> <network> <version>

Note: It is important to first activate the new version on a staging environment and ensure that everything is looking good and then activate it on the production network.

Originally published: May 6, 2021