Blog

Update Your Cloudlets with Powershell

April 27, 2020 · by Stuart Macleod ·
Categories:

There are a few ways to interact with Akamai products. Akamai APIs provide a great selection of tools for managing Akamai programmatically. If you prefer to interact via the command line, you can use Akamai’s CLI - however, not all of Akamai’s APIs are accessible via CLI. 

For this reason, we produced a Powershell module for any Powershell-savvy users who wish to complete API-based tasks without worrying about compilation or the more intricate parts of Akamai API authentication. This module covers many more of the APIs than are currently supported by the CLI.  

In this post, I’ll use the Cloudlets API as an example as we walk through how to use Powershell to update your cloudlets.   

Before we begin, cloudlets are small snippets of configuration which can be edited independently of properties and crucially activate in just a few seconds. 

For our example, we are going to change the split percentage in a Phased Release Cloudlet policy, something which is regularly done by teams using a blue/green deployment method, as is common in most microservice deployments. 

Let’s Get Started

First, you will need to install the Akamai Powershell module from the Powershell Gallery by typing Install-Module AkamaiPowershell and import it into your Powershell session using the Import-Module command. It is also assumed you have an Akamai API client with read/write rights to the Cloudlets API, and that your credentials are stored in a .edgerc file stored in the root of your user folder. This link has details on this part, skip the Python script and just create the file manually with a text editor. 

Once that is complete we need to get a list of the Cloudlet policies and store them in a variable. For that use the following command: 

$Policies = List-CloudletPolicies -Section default

The Section parameter defines the section in your .edgerc file in which your API credentials are stored.

Cloudlets commands in the module look for the [cloudlets] section in the .edgerc file, so you must override that in order to use the [default] section.

Note: If your account has more than 25 Cloudlet policies, use the -PageSize (max of 999) and -Offset parameters to get more results.

Now, you can filter the response to find your policy. Note the policyId in the output. You'll need it later.

$MyPolicy = $Policies | where {$_.name -eq "my_policy_name"}

$MyPolicy

Great, now we need to list the versions of this policy and see their status. Use the PolicyId you just copied.

$Versions = List-CloudletPolicyVersions -PolicyID 121435 -IncludeRules -Section default

$Versions[0]

1st element
I've selected the 1st element of the resulting array here ($Versions[0]) as it is most likely to be the latest version, but feel free to check through the response manually.

you'll see that this version (v10) is active on staging, so we will need a new one, so you'll enter

New-CloudletPolicyVersion -PolicyID 121435 -Description "Updating with Powershell" -CloneVersion 10 -Section default

You should see something like this: 

output

Now, you'll need to update the matchRules in the policy to change your percentage. Let's list the rules to find the ID we want. To do this, enter the following:

$Rules = Get-CloudletPolicyVersion -PolicyID 121435 -Version 11 -Section default

$Rules.matchRules

In the output (below), you can see the rule you want at the bottom of the list, as it is the lowest rule in the Cloudlets UI.

rules

Extract that into a new variable and update it to the desired percentage. In this case you'll want to make it 80% to the Green slice (which is Conditional Origin smacleod_demo_green) rather than 50.

$NewRule = $Rules.matchRules[2]

$NewRule.forwardSettings.percent = 80

$NewRule

Because of the way the Cloudlets API schema was written, you'll need to remove the 'location' member from the $NewRule variable. If you don't remove this the command will fail.

Remove the 'location' member by entering the following command. 

$NewRule.PsObject.Members.Remove('location')

$NewRule

You'll see something like this:

location member output.

Now, let's update the policy. You'll need the policyId, the version and the akaRuleId from the previous outputs.

Set-CloudletPolicyVersionRule -PolicyID 121435 -Version 11 -AkaRuleID 8cd248cf81593a26 -Body ($NewRule | ConvertTo-Json -Depth 100) -Section default

output

Finally, let's activate this in staging so we can test it.

Activate-CloudletPolicyVersion -PolicyID 121435 -Version 11 -Network Staging -Section default

You should see something like this:

output

Now, if you check in the UI, you'll see that the percentage is now 80 and the policy is active in staging.

UI

Putting It All Together

All these steps might seem a bit complicated to do on a regular basis until you put them altogether into a simple script such as this one:

Param(

           [Parameter(Mandatory=$true)]  [string] $PolicyName,

           Parameter(Mandatory=$true)]  [int] $TargetPercentage,

           [Parameter(Mandatory=$true)]  [string] $Description,

           [Parameter(Mandatory=$false)] [string] $EdgeRCFile = "~\.edgerc",

           [Parameter(Mandatory=$false)] [string] $Section = 'papi'

)

 

$Policies = List-CloudletPolicies -Section $Section -Pagesize 999

$MyPolicy = $Policies | where {$_.name -eq $PolicyName}

$Versions = List-CloudletPolicyVersions -PolicyID $MyPolicy.policyId -IncludeRules -Section $Section

 

$NewVersion = New-CloudletPolicyVersion -PolicyID $MyPolicy.policyId -Description $Description -CloneVersion $Versions[0].version -Section $Section

 

$Rules = Get-CloudletPolicyVersion -PolicyID $MyPolicy.policyId -Version $NewVersion.version -Section $Section

$NewRule = $Rules.matchRules[2]

$NewRule.forwardSettings.percent = $TargetPercentage

$NewRule.PsObject.Members.Remove('location')

$UpdateResult = Set-CloudletPolicyVersionRule -PolicyID $MyPolicy.policyId -Version $NewVersion.version -AkaRuleID $NewRule.akaRuleId -Body ($NewRule | ConvertTo-Json -Depth 100) -Section $Section

$ActivateResult = Activate-CloudletPolicyVersion -PolicyID $MyPolicy.policyId -Version $NewVersion.version -Network Staging -Section $Section

return "Process complete"

The script is pretty simple (it would typically have more error-handling and comments and such) and you can execute it with a command like this

.\update-cloudletpercentage.ps1 -PolicyName "smacleod_demo_phasedrelease1" -TargetPercentage 10 -Description "Testing my script" -Section default

outputUI

Now, you can see that with a fairly small amount of scripting you can apply this to a CI/CD pipeline or just run the script when you need to make a manual change.

The Cloudlets API covers all Cloudlets, and while this script is clearly very specific to my example, with very little tweaking you can use it for any of the other Cloudlets or expand it to multiple policies, each with multiple rule changes.

Let us know how this works for you!