Blog

Automating your Edge Compute workflows with EdgeWorkers and GitHub Actions

October 12, 2020 · by Dale Lenard and Javier Garza ·

EdgeWorkers is an Akamai edge computing technology that enables developers to customize web traffic by  running JavaScript at the Edge instead of using browser clients or origin servers. See this overview  for more information. 

In this blog, we are going to focus on how developers can leverage continuous deployment automation tools like GitHub actions to simplify deploying EdgeWorkers code within the Akamai Network.

Some of the technologies that we are going to use are:

  • GitHub Actions: a set of software workflows to build, test, and deploy your code right from GitHub

  • Docker Images: A docker container that has most of the Akamai development tools

  • JavaScript: a very popular programming language.

  • YAML: a human-readable data-serialization language commonly used for configuration files.

  • JSON: an open standard file, and data interchange format to store and transmit data objects.

  • Git: distributed version-control system for tracking changes in source code 

  • GitHub: A cloud service that provides hosting for software development and version control using Git

EdgeCompute Development Workflow

In order to run EdgeWorkers code at the edge you first need to run a one-time workflow to setup things which consists on:

1. Create an EdgeWorker ID (for example using the EdgeWorkers API / EdgeWorkers CLI). See the EdgeWorkers Getting Started Guide for detailed steps. For our example we will run the following command using the EdgeWorkers CLI (included in the Akamai Docker Developer Environment):

$ akamai edgeworkers register 12345 edgeworker-hello-world 

 

------------------------------------------

--- Created new EdgeWorker Identifier: ---

------------------------------------------

edgeWorkerId  name                    groupId

------------  ----------------------  -------

4521          edgeworker-hello-world  12345

Note: This step is optional since the GitHub action we are using will register new EdgeWorkers automatically.

2. Attach the EdgeWorker to an Akamai property, and activate the property. For example, using the Property Manager API / Property Manager CLI you would add code similar to this:

{

    "name": "hello world",

    "children": [],

    "behaviors": [

        {

            "name": "edgeWorker",

            "options": {

                "enabled": true,

                "createEdgeWorker": "",

                "edgeWorkerId": "4521"

            }

        }

    ],

    "criteria": [

        {

            "name": "path",

            "options": {

                "matchOperator": "MATCHES_ONE_OF",

                "values": [

                    "/hello-world"

                ],

                "matchCaseSensitive": false,

                "normalize": false

            }

        }

    ],

    "criteriaMustSatisfy": "all"

Note: The above code causes the EdgeWorker ID 4521 to be executed at the edge when a client requests “/hello-world”. You will need to update the EdgeWorker ID and the URL, or use a different way to activate the EdgeWorker as Akamai offers hundreds of different ways to do that by using any information that is present at the request like: HTTP headers, URL path or query-strings, characteristics of the device (like mobile device, using a cellular connection), GEO-location (i.e. city, country) and many more.

After this initial setup, developers will focus on setting up a Development workflow which consists of:

  1. Creating the JavaScript code to run certain application logic using a text editor, or an IDE like Visual Studio Code

  2. Commiting the code into a Version Control system like Git

  3. Packaging the EdgeWorkers code: basically creating a JSON manifest that describes the EdgeWorker name/version number, and packaging into a tarball with the JavaScript code

  4. Deploying the EdgeWorker package to the Akamai platform

  5. Testing the functionality 

Automating Code Deployment using GitHub Actions

GitHub Actions can help us automate the steps 3-5 described above (plus registering the EdgeWorker if it doesn’t exist already, and adding the property manager code), letting developers focus on writing code.

Please note that you can achieve the same results using tools like Jenkins, TravisCI, or CircleCI. However getting started with GitHub workflows is pretty simple thanks to the 5000+ actions available in the GitHub Marketplace.

On this post we will be using the Deploy Akamai EdgeWorkers action which you can download on the Akamai Marketplace (see screenshot below).

chart

Here are the steps we will be following to create our deployment workflow:

  1. Create a GitHub repository to hold our JavaScript code, EdgeWorkers manifest file

  2. Create a GitHub workflow 

  3. Commit new EdgeWorkers code in our local machine and ensure the workflow deploys it to the Akamai platform

Create a GitHub Repository

Go to https://github.com/new and create a repository (a private repository is fine). It is always good to use a short and descriptive name. In our example we will use edgeworker-hello-world, we will add a short description and will click the “Create Repository” Button.

Create a GitHub Repository

 Create a GitHub Workflow

Click on the Actions tab, and then on the “setup a workflow yourself” link.

github actions

Give the workflow YML file a name like for example deploy.yml, on the right side you can search for the Deploy Akamai Edgeworkers Action.

chart

 Copy the action code, and paste it inside your deploy.yml file, and click Start Commit.

chart

The next step is to follow the action instructions, to store the API credentials that have access to the EdgeWorkers API within your repository secrets (https://github.com/[github-username]/[repository-name]/settings/secrets); and indicate the environment parameters within the YML file: 

  • EdgeWorkers name: you can either indicate a string within single quotes or use your repository name by indicating the GitHub variable ${{ github.event.repository.name }}

  • Network: Either staging or production (you could have separate workflows to deploy to staging and production)

  • Group ID: An integer indicating group ID where the EdgeWorker resides. You can get this number using the EdgeWorkers CLI like this:
    akamai edgeworkers list-groups

Here is an example of the final deploy.yml file we are going to use in our workflow:

# This is a basic workflow to help you get started with Actions

 

name: CI

 

# Controls when the action will run. Triggers the workflow on push or pull request

# events but only for the master branch

on:

  push:

    branches: [ master ]

  pull_request:

    branches: [ master ]

 

# A workflow run is made up of one or more jobs that can run sequentially or in parallel

jobs:

  # This workflow contains a single job called "build"

  build:

    # The type of runner that the job will run on

    runs-on: ubuntu-latest

 

    # Steps represent a sequence of tasks that will be executed as part of the job

    steps:

        - uses: actions/checkout@v1

        - name: Deploy Edgeworkers

          uses: jdmevo123/akamai-edgeworker-action@1.0

          env:

            EDGERC: ${{ secrets.EDGERC }}

          with:

            edgeworkersName: ${{ github.event.repository.name }}

            network: 'staging'

            groupid: '12345' 

Edit and commit your EdgeWorkers Code

You can find a lot of EdgeWorkers code samples in GitHub. For our “Hello World” example, the code can be found at: https://github.com/akamai/edgeworkers-examples/tree/master/hello-world 

Download main.js and bundle.json from the examples repository into your GitHub repository, and commit the files.

This should trigger the workflow below:

workflow

If we take a look at the build logs, you should see all the steps completed in around 1 minute (you can expand some of the steps to see more details). 

Note: If you see failures, you will need to check the logs to understand what the issue is. One of the most common issues we have seen is not adding valid API credentials to the Repository Secrets EDGERC variable, which causes API calls to fail.

build

Verify EdgeWorker Deployment

You can verify the workflow works as expected and the new version has been activated in staging by running the “status” command followed by the EdgeWorkerID in a terminal using the EdgeWorkers CLI (included in the Akamai Docker Developer Environment):

$ akamai edgeworkers status 4521

You may also like

Here are great resources you can read to learn more:

About the authors

Dale

 

Dale Lenard is a Senior Principal Technical Solutions Architect at Akamai based in Sydney, Australia where he works with customers in understanding and defining the digital transformation and DevOps strategies. Dale has written a number of blogs on DevOps and Developer relations, and has spoken at a number of key conferences.

In his spare time he enjoys developing home automation, challenging his thought process for that next big idea and tinkering/developing innovative platforms that bridge gaps in solutions/processes he has identified.

Javier

 

Javier Garza is a developer advocate at Akamai Technologies where he helps the largest companies on the internet run fast and secure apps by leveraging web performance, security, and DevOps best practices. Javier has written many articles on HTTP/2 and web performance, and is the co-author of the O’Reilly Book, Learning HTTP/2. In 2018, Javier spoke at more than 20 developer-related events around the world, including well-known conferences like Velocity, AWS Re:Invent, and PerfMatters. His life’s motto is: share what you learn, and learn what you don’t. In his free time he enjoys challenging workouts and volunteering for non-profits that support children and education.