Blog

Manage Edge DNS as Code: GitHub Actions

November 9, 2020 · by Javier Garza ·

This blog is part of a series on the various methods available to manage DNS as code. In this blog, I’ll walk you through managing DNS using the GitHub Actions

Akamai Edge DNS is a cloud-based solution that can be implemented as a primary or secondary DNS service that leverages a globally distributed network of servers to ensure the availability, performance, and security of your DNS infrastructure.

Managing DNS as Code increases developer productivity and makes it easier to manage your DNS infrastructure at scale. 

Methods to manage DNS as code

There are several different ways to manage Edge DNS as code:

  1. Leverage the Edge DNS API directly using the programming language of your choice
    This method is the most flexible but requires the most development work. This method is recommended for large projects that need a lot of customization.

  2. Leverage the DNS CLI package
    This method helps teams get started with automation quickly but offers fewer customization options.

  3. Use the "akamai_dns_record" and "akamai_dns_zone" resources within the Akamai Terraform provider
    Terraform is a 3rd-party tool to orchestrate infrastructure which is great if you already use it for managing other Infrastructure as code. The main drawback of using Terraform (or any other 3rd-party tool) is that you are constrained by the functionality that has been implemented within the tool and expanding that functionality may be difficult or require more work.

  4. Use CI/CD automations like the Deploy Akamai Edge DNS zone GitHub Action
    This is my favorite approach as you can use any of the previously mentioned methods and easily add automation around it, making it very flexible and efficient.

This post is part of a series of blog posts indicating different ways to manage Akamai Edge DNS as code. In this blog we are going to focus on using GitHub Actions to manage DNS records (the fourth item on the list above). 

DNS API credentials

Most command line tools that we are using on this post rely on having API credentials stored in a “dns” section with a text file called “.edgerc” located in the user’s home directory. See the Getting Started with APIs page on developer.akamai.com for more information.

You can use a command like “cat” to verify your credentials file looks like this:

$ cat ~/.edgerc

[dns]

client_secret = d7BhODpkXAPCqrCvAHae/4AqCQODfUI0oqjBbrjqQPM=

host = akab-co23auwltjdkswby-ogel7mtggepget6g.luna.akamaiapis.net

access_token = akab-ahsl64pyefoj23ob-f4nd2rcvpotwnffx

client_token = akab-kzcuqwrhxtdet73o-tfskx6y3r7hk7rqg

Note: Please replace the values above with valid API credentials that have access to the DNS API, as the ones shown above are non-working sample credentials for illustration purposes.

Docker Development Environment

Through this post we are going to be running terminal commands on our Akamai Docker Development Environment which you can identify with the prompt “Akamai DevOps [~] >>”

The command below describes how to define an alias called “akadev” that will start our Akamai Development Environment.

$ alias akadev="docker run --rm -it --name akamai -v $HOME/.edgerc:/root/.edgerc akamai/shell"

$ akadev

                ___    __                         _

               /   |  / /______ _____ ___  ____ _(_)

              / /| | / //_/ __ `/ __ `__ \/ __ `/ /

             / ___ |/ ,< / /_/ / / / / / / /_/ / /

            /_/  |_/_/|_|\__,_/_/ /_/ /_/\__,_/_/

===============================================================

=  Welcome to the Akamai Docker Image                         =

===============================================================

=  Project page:                                              =

=  https://github.com/akamai/akamai-docker                    =

===============================================================

Akamai DevOps [~] >>

DNS zone file automation using GitOps

If you prefer to do several changes at the same time, or are familiar with DNS zone files, you can use the Get Master Zone File, and Post Master Zone File API calls to get, and update the master zone file.

This approach is ideal to manage the DNS zone file using GitOps, where you can just store the text file containing the DNS zone file in a source control system like Git/GitHub and then use automation workflows to automatically deploy the new zone in the Akamai Edge DNS network whenever you commit new changes to the zone.

Another benefit of this approach is that you can use software development best practices, where the zone file is treated as code and people in your organization who need changes can create a pull request and then the person managing the zone can review, provide comments and merge the changes into the master branch to have them automatically deployed into production.

Here are the steps on how you can do that:

Store the DNS zone file in a source control repository

For my example I am going to use the domain “akamaideveloper.net”. The first step would be to create a GitHub repository to store the zone file. I am going to call the repository “akamaideveloper.net-dns-zone-file” and put the initial DNS zone file in a text file called “akamaideveloper.net.zone” (please note the GitHub action looks for a file named {domain-name}.zone, so the name you pick for this file is very important):

akamaideveloper.net. 172800 IN NS a9-64.akam.net.

akamaideveloper.net. 172800 IN NS a1-49.akam.net.

akamaideveloper.net. 172800 IN NS a26-66.akam.net.

akamaideveloper.net. 172800 IN NS a7-67.akam.net.

akamaideveloper.net. 172800 IN NS a16-64.akam.net.

akamaideveloper.net. 172800 IN NS a22-65.akam.net.

akamaideveloper.net. 900 IN SOA akamaideveloper.net. hostmaster.akamaideveloper.net. 1601591288 900 300 604800 180

javier.akamaideveloper.net. 300 IN CNAME www.akamaideveloper.net.edgesuite-staging.net.

http2.akamaideveloper.net. 300 IN HTTPS 0 http2.akamai.com.

Note: it is very important to remember to increase the serial to a higher number (marked in red) each time you update the zone file to ensure the new zone file is accepted

As you can see the DNS zone file showcased above has 10 DNS records:

  • Six NS records defining the authoritative name servers

  • One SOA (Start of Authority) record, which indicates things like the serial, refresh interval, expiration, etc.

  • One CNAME record defining an alias

  • One HTTPS record defining a hostname to connect over HTTPS with priority 0 (please note this is a newer DNS record type which may not be supported by all the command line tools yet)

Add your DNS API credentials to the GitHub repository secrets

Add your Akamai DNS API Credentials to the GitHub repository Secrets as indicated on https://github.com/akamai-contrib/akamai-deploy-dns-zone-github-action#secrets. After storing your API credentials, your repository secrets should look like this:

secrets

Add your automation script

There are many ways to run GitOps automation workflows, some of the most popular tools are: Jenkins, CircleCI, TravisCI, and GitHub Actions. For this example we are going to use GitHub actions because I created and published an action to the GitHub Action marketplace that will make the setup process really easy for you.

The only thing you need to do is create a new YAML file inside a special directory called “.github/workflows/”. The name doesn’t really matter, but I am going to call my file “deploy-zone.yml”. Its contents should look like this:

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

 

name: CICD

 

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

# events but only for the main branch

on:

  push:

    branches: [ main ]

  pull_request:

    branches: [ main ]

 

# 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"

  Deploy DNS zone:

    # 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@v2

        - name: Deploy DNS zone file

          uses: akamai-contrib/akamai-deploy-dns-zone-github-action@1.3

          env:

            EDGERC: ${{ secrets.EDGERC }}

          with:

            zoneName: 'akamaideveloper.net' # replace with the name of your domain

Note: remember to change the contents of zoneName to match your domain

You can now commit this file to master using git add, git commit and git push (if you use the UI on github.com, you would click the “Start Commit” green button, enter a commit message and click the “Commit Changes” button). 

Since your action is configured to run on “push”, committing this file will trigger the action. Click the details to verify the execution succeeded. You should see a message like this within the “Deploy DNS zone file” section:

Zone file exists: akamaideveloper.net.zone

1. uploading zone file

Running: http --print=HhbB -A edgegrid -a dns: POST :/config-dns/v2/zones/akamaideveloper.net/zone-file Content-Type:text/dns < akamaideveloper.net.zone

Zone file accepted!

Zone version: 953a7c25-fd39-4bf1-811b-1c6a1d3b126b

 

2. Checking activation status

Running: http --print=HhbB -A edgegrid -a dns: GET :/config-dns/v2/zones/akamaideveloper.net/versions/953a7c25-fd39-4bf1-811b-1c6a1d3b126b

API response:

{

  "contractId": "C-1FRYVV3",

  "zone": "akamaideveloper.net",

  "category": "general",

  "type": "PRIMARY",

  "versionId": "953a7c25-fd39-4bf1-811b-1c6a1d3b126b",

  "lastModifiedDate": "2020-10-06T23:18:55.261091Z",

  "lastModifiedBy": "api-user-devrel",

  "activationState": "PENDING",

  "signAndServe": false

}

Zone is activating (most activations take less than 5 minutes to complete)

Wait a few minutes and use “dig” or “nslookup” to verify your DNS records have been updated.

Summary

In this post we saw working examples showing how you can manage your DNS domains with the Akamai Edge DNS API, by leveraging GitHub actions to deploy the new zone on the Akamai platform. I hope you find this information useful, and remember to “share what you know, and learn what you don’t”.

You might also like

Here are great resources you can read to learn more:

About the author

JavierJavier 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.