Blog

Introducing Akamai CLI Onboard

November 19, 2020 · by Andrew Tsai, Vreddhi Bhat, and Karthic Chinnannasamy ·
Categories:

If you’re familiar with creating an Akamai Property Manager configuration, you might be used to the manual process through the Akamai Control Center.  You usually have to navigate to create the initial product property, add any additional rules, configure the hostname and SSL certificate, activate it on the Akamai network, and integrate with the appropriate Akamai security configuration.

With CLI Onboard, creating a new Akamai property is more simple, can be automated, and allows you improved flexibility around:

  1. Any User-Defined Property Manager Template

  2. Any SSL Certificate Type Template and Hostname

  3. Using an existing Akamai Security Configuration (optional)

The CLI Onboard package simplifies some of the basic requirements needed, adds proper validation, and onboards an initial property in minutes - not hours or days.

Get started

Here are the steps below to get started:

Step 0: Ensure you meet the pre-requisites

Make sure you have the Akamai CLI installed.

Use our guide to get started with the Akamai CLI. For credentials, either allow access to All APIs, or use the Advanced button and grant your API client access to the following APIs:

  • Property Manager (/papi)

  • Edge Hostnames (/hapi)

  • Certificate Provisioning System (/cps)

  • Application Security (/appsec) 

Tip: You can store the API credentials with access to the above APIs in the [onboard] section of your .edgerc file, and place that file on the user’s home directory to use the CLI onboard defaults. Otherwise, you will have to use --edgerc and --section parameters to indicate the file location and section name

To install the CLI-Property-Manager, run:

akamai install property-manager

Step 1: Install Akamai CLI-Onboard

Once you have the base Akamai CLI and the CLI-Property manager installed, run:

akamai install onboard

Step 2: Determine Property Manager Template

Often, you may know the type of Akamai template you would like to use in order to create a new property configuration, whether that is a vanilla Akamai product template, a copy of an existing property, or a brand new template you’d like to start with.  

See here for a sample Akamai product Ion template.

For your own user defined template, create a Property Manager template in the UI (it’s ok to have empty or placeholder values), click the View Rule JSON button and then the Download Rule JSON button.

default rulesDefault Rules

For an existing property, you can also download the rule json using the Property Manager User Interface, or use akamai property-manager show-ruletree --property <property_name> (from Property-Manager CLI) to download it as well.

For the placeholder empty values or values that need to be updated in your template during property creation, proceed with these steps:


1) In the template json, find the value and define a variable using ${env.<variable_name>} to represent that placeholder that will be substituted later. As an example below, we have used ${env.origin_default} to represent the placeholder origin value:

template_file.json :

           "name": "origin",

           "options": {

               "cacheKeyHostname": "REQUEST_HOST_HEADER",

               "compress": true,

               "enableTrueClientIp": true,

               "forwardHostHeader": "REQUEST_HOST_HEADER",

               "httpPort": 80,

               "httpsPort": 443,

               "originCertificate": "",

               "originSni": true,

               "originType": "CUSTOMER",

               "ports": "",

               "trueClientIpClientSetting": false,

               "trueClientIpHeader": "True-Client-IP",

               "verificationMode": "PLATFORM_SETTINGS",

               "hostname": "${env.origin_default}"

           }


2. Define the values you want to use in a separate file.  As you can see here, the value we will use for the origin_default variable is origin-www.example.com

Variable_values.json:

 

{

   "origin_default": "origin-www.dummy.com",

   "cpcode_default": 12345

}

Finish defining your template placeholder variables and variable values and save off the template_file.json and the variable_values.json file to use in step 4.

Step 3: Determine hostname and SSL certificate

For a new property hostname, you will need to decide which SSL certificate to use for that hostname.  Often, you can tie your hostname to an existing Akamai SSL certificate on the platform (ex: wildcard certificate) or start the process to modify an existing SSL certificate or create an entirely new SSL certificate.

  1. If using an existing SSL certificate, note the existing edge hostname you want to reuse for use in Step 4
     

  2. If modifying an existing SSL certificate, start the modification of the SSL certificate either in the Control Center UI or via the Akamai CLI for CPS
     

  3. If creating a new SSL certificate, use the appropriate SSL certificate type template and values located here that will be needed to provision a new SSL certificate.

    1. For example, to start a new DV SAN SNI cert, download the dv_san_sni_template.json and fill in the appropriate values for those placeholders in the dv_san_sni_values.json file

If modifying or creating a new SSL certificate, depending on the certificate type (which each has its own validation process), complete the validation independently of the onboarding process.   

Step 4: Put it all together

Now, we have all the info we need to create a new Akamai Property and can use CLI-Onboard to do all the heavy lifting:

1. Download or create a copy of this sample setup.json file


2. Fill out the basic property information such as:

  1. property_name, contract, group, product

  2. name of the new cp code

  3. public_hostnames

{

   "property_info": {

       "property_name": "",

       "secure_network": "ENHANCED_TLS",

       "contract_id": "ctr_",

       "group_id": "grp_",

       "product_id": "prd_",

       "rule_format": "latest",

       "default_cpcode": {

           "create_new_cpcode": true,

           "new_cpcode_name": ""

 

       },


3. Under file_info: update the source_template_file and source_values_file to the full path value of the files you defined in Step 2

       "file_info": {

           "use_file": false,

           "source_template_file": "",

           "source_values_file": ""

       },


4. For the hostname and SSL certificate information, determine if you are using an existing edge hostname or creating a new edge hostname as discussed in Step 3.

  • If using an existing edge hostname that already exists, use the use_existing_edgehostname mode and supply the edge_hostname value as shown:

   "edge_hostname": {

       "mode": "use_existing_edgehostname",

       "use_existing_edgehostname": {

           "edge_hostname": ""

       },

  • If wanting to create a new edge hostname use new_enhanced_tls_edgehostname mode and either the existing certificate or new certificate details:

Use Existing Cert Example:

  • mode is new_standard_tls_edgehostname

  • use_existing_enrollment_id is true

  • existing_enrollment_id and existing_slot_number are available in the Control Center UI

   "edge_hostname": {

       "mode": "new_enhanced_tls_edgehostname",

       "use_existing_edgehostname": {

           "edge_hostname": ""

       },

       "new_standard_tls_edgehostname": {},

       "new_enhanced_tls_edgehostname": {

           "ssl_cert_info": {

               "use_existing_enrollment_id": true,

               "existing_enrollment_id": "12345",

               "existing_slot_number": "67890",

               "create_new_ssl_cert": false,

               "ssl_cert_template_file": "",

               "ssl_cert_template_values": "",

               "temp_existing_edge_hostname": ""

 

           }

       }

   },

Provision New SSL Certificate Example:

  • mode is new_standard_tls_edgehostname

  • create_new_ssl_cert is true

  • ssl_cert_template_file and ssl_cert_template_values files were defined in Step 3

  • temp_existing_edge_hostname can be a placeholder value (this will not really be used but allow for property creation to not be blocked by the SSL certificate provisioning process)

   "edge_hostname": {

       "mode": "new_enhanced_tls_edgehostname",

       "use_existing_edgehostname": {

           "edge_hostname": ""

       },

       "new_standard_tls_edgehostname": {},

       "new_enhanced_tls_edgehostname": {

           "ssl_cert_info": {

               "use_existing_enrollment_id": false,

               "existing_enrollment_id": "",

               "existing_slot_number": "",

               "create_new_ssl_cert": true,

               "ssl_cert_template_file": "~/onboard/ssl_template_file.json",

               "ssl_cert_template_values": "~/onboard/ssl_values.json",

               "temp_existing_edge_hostname": "www.sample.com.edgekey.net"

 

           }

       }

   },


5. Finally, update your activation settings, waf_ security settings (optional), and notification email, and you should be all set to run the onboard CLI command:

akamai onboard create --file <path_to_setup.json file> 

You might also like

For more information on other values in the setup.json file, see the repository and README for more details.