Add a custom cache layer

Provide your customers with a more consistent user experience by implementing a custom caching layer that optimizes the connection between your cloud infrastructure and the Akamai platform.

What you'll do

Create and activate a Cloud Wrapper configuration and link it to a property.

Currently, you can use Cloud Wrapper with these Akamai products:

• Media delivery: Adaptive Media Delivery, Download Delivery, and Object Delivery.
• Website delivery: Dynamic Site Accelerator and Ion.

📘

Support for Cloud Wrapper with Dynamic Site Accelerator and Ion is currently in limited-availability. To request access to these products, talk to your account representative.

What you need

To use a Cloud Wrapper configuration, you need a property from the Property Manager (PAPI) API, which is actively delivering your media or website content for at least 37 days. This helps ​Akamai​ determine your capacity needs.

Cloud Wrapper has a default object limit of 10,000 objects/GB.

1. Create a new wrapper configuration

Get your contract's property IDs and traffic locations and their storage capacity to create a new Cloud Wrapper configuration.

🚧

The properties you want to use Cloud Wrapper with must be activated on the production network.

1. Determine which properties to use with your new configuration by running Get-CloudWrapperProperty. Optionally add the -Unused switch parameter to return only properties that aren't in use.

   CommandOutput

   Get-CloudWrapperProperty -ContractIds 'C-0N7RAC7'

    propertyId   : 12345
    propertyName : my-property-1
    contractId   : C-0N7RAC7
    groupId      : 23456
    type         : MEDIA
   
    propertyId   : 98765
    propertyName : my-property-2
    contractId   : C-0N7RAC7
    groupId      : 23456
    type         : WEB

   You need to provide property IDs when you create your Cloud Wrapper configuration.

2. Get your contract's traffic location with Get-CloudWrapperLocation.

   CommandOutput

   Get-CloudWrapperLocation | Format-List

    locationId         : 1
    locationName       : US East
    trafficTypes       : {@{trafficTypeId=50; trafficType=WEB_STANDARD_TLS; mapName=cw-s-use}, @{trafficTypeId=1; 
                        trafficType=LIVE; mapName=cw-s-use-live}, @{trafficTypeId=2; trafficType=LIVE_VOD; mapName=cw-s-use}, 
                        @{trafficTypeId=100; trafficType=WEB_OPTIMIZED; mapName=cw-s-use-web}}
    multiCdnLocationId : 018
   
    locationId         : 2
    locationName       : US West
    trafficTypes       : {@{trafficTypeId=51; trafficType=WEB_STANDARD_TLS; mapName=cw-s-usw}, @{trafficTypeId=3; 
                        trafficType=LIVE_VOD; mapName=cw-s-usw}, @{trafficTypeId=4; trafficType=LIVE; mapName=cw-s-usw-live}, 
                        @{trafficTypeId=101; trafficType=WEB_OPTIMIZED; mapName=cw-s-usw-web}}
    multiCdnLocationId : 020

   The output returns an Akamai created trafficTypeId that represents a location and its traffic type combination. Use the values of this ID when creating the configuration.

3. Find your location's capacity with Get-CloudWrapperCapacity.

   CommandOutput

   Get-CloudWrapperCapacity -ContractIds 'C-0N7RAC7'

    locationId         : 1
    locationName       : US East
    contractId         : C-0N7RAC7
    type               : MEDIA
    approvedCapacity   : @{value=100; unit=GB}
    assignedCapacity   : @{value=80; unit=GB}
    unassignedCapacity : @{value=20; unit=GB}
   
    locationId         : 3
    locationName       : Europe
    contractId         : C-0N7RAC7
    type               : WEB_STANDARD_TLS
    approvedCapacity   : @{value=1; unit=GB}
    assignedCapacity   : @{value=1; unit=GB}
    unassignedCapacity : @{value=0; unit=GB}

   The output returns a unit of measurement, either GB or TB.

   You also get the value for the unassignedCapacity. This value represents the difference between the approvedCapacity and assignedCapacity, giving you the total space you have left for a location.

   You need both the unit and a value within the limits of your approved capacity to create the wrapper configuration.

4. Create a Cloud Wrapper configuration with New-CloudWrapperConfiguration. Provide each location in the locations array.

   Optionally, add the -Activate switch parameter to activate your configuration upon creation. Otherwise, you can activate it separately.

   For a full list of settings you need to pass in the operation, see Cloud Wrapper configuration.

   Command: HashtableCommand: JSON stringOutput

   $MyConfig = @{
       locations = @(
           @{
               capacity = @{
                   unit = "GB"
                   value = 1
               }
               comments = "Real traffic"
               trafficTypeId = 3
           },
       ),
       capacityAlertsThreshold = 50
       comments = "Real traffic"
       configName = "my-config"
       contractId = "C-0N7RAC7"
       propertyIds = @(
           "12345"
       )
       notificationEmails = @(
           "jsmith@example.com"
       )
   }
   
   $MyConfig | New-CloudWrapperConfiguration

   $MyConfig = '{
       "locations": [
           {
               "capacity": {
                   "unit": "GB",
                   "value": 1
               },
               "comments": "Real traffic",
               "trafficTypeId": 2
           },
       ],
       "capacityAlertsThreshold": 80,
       "comments": "Real traffic",
       "configName": "my-config",
       "contractId": "C-0N7RAC7",
       "propertyIds": [
           "12345"
       ],
       "notificationEmails": [
           "jsmith@example.com"
       ]
   }'
   
   $MyConfig | New-CloudWrapperConfiguration

   configId                : 54321
   configName              : my-config
   contractId              : C-0N7RAC7
   propertyIds             : {12345}
   comments                : Real traffic
   status                  : IN_PROGRESS
   retainIdleObjects       : False
   locations               : {@{trafficTypeId=3; comments=Real traffic; capacity=; mapName=cw-s-usw}}
   multiCdnSettings        : 
   capacityAlertsThreshold : 50
   notificationEmails      : {jsmith@example.com}
   lastUpdatedDate         : 3/31/2026 9:39:33 AM
   lastUpdatedBy           : jsmith
   lastActivatedDate       : 
   lastActivatedBy         : 

Manage a configuration

Update a configuration

For a full list of settings you need to pass in the update operation, see Cloud Wrapper configuration.

You can update your Cloud Wrapper configuration using one of these ways:

Method 1

Save the results of the Get-CloudWrapperConfiguration command in a variable and update specific attributes of your configuration. Then pipe the entire object back to the Set-CloudWrapperConfiguration command to make your changes effective.

$MyConfig = Get-CloudWrapperConfiguration -ConfigID 54321

$MyConfig.locations[0].trafficTypeId = 1
$MyConfig.locations[0].capacity.value = 3
$MyConfig.propertyIds += "98765"
$MyConfig.notificationEmails = @("jsmith@example.com", "jasmith@example.com")
$MyConfig.capacityAlertsThreshold = 80

$MyConfig | Set-CloudWrapperConfiguration -ConfigID 54321

configId                : 54321
configName              : my-config
contractId              : C-0N7RAC7
propertyIds             : {12345, 98765}
comments                : Real traffic
status                  : SAVED
retainIdleObjects       : False
locations               : {@{trafficTypeId=1; comments=Real traffic; capacity=; mapName=cw-s-use}}
multiCdnSettings        : 
capacityAlertsThreshold : 80
notificationEmails      : {jsmith@example.com, jasmith@example.com}
lastUpdatedDate         : 3/31/2026 10:09:33 AM
lastUpdatedBy           : jsmith
lastActivatedDate       : 
lastActivatedBy         : 

Method 2

Retrieve your configuration with Get-CloudWrapperConfiguration, save its output locally, and edit it as needed.

Get-CloudWrapperConfiguration -ConfigID 54321 | ConvertTo-Json -Depth 100 | Out-File -FilePath ./myConfig.json

{
  "configId": 54321,
  "configName": "my-config",
  "contractId": "C-0N7RAC7",
  "propertyIds": [
    "12345"
  ],
  "comments": "Real traffic",
  "status": "SAVED",
  "retainIdleObjects": false,
  "locations": [
    {
      "trafficTypeId": 3,
      "comments": "Real traffic",
      "capacity": {
        "value": 1,
        "unit": "GB"
      },
      "mapName": "cw-s-usw"
    }
  ],
  "multiCdnSettings": null,
  "capacityAlertsThreshold": 50,
  "notificationEmails": [
    "jsmith@example.com"
  ],
  "lastUpdatedDate": "2026-03-31T10:09:33.474Z",
  "lastUpdatedBy": "jsmith",
  "lastActivatedDate": null,
  "lastActivatedBy": null
}

Then pipe the updated content to the Set-CloudWrapperConfiguration command along with the required ID.

$MyConfig = Get-Content ./myConfig.json -Raw

$MyConfig | Set-CloudWrapperConfiguration -ConfigID 54321

When updating the configuration with Set-CloudWrapperConfiguration, optionally add the -Activate switch parameter to activate it.

Delete a configuration

Before deleting a configuration, ensure that all the properties that use it have the Cloud Wrapper behavior disabled. To do that, run the Set-CloudWrapperConfiguration operation with the -Deactivate switch to deactivate it.

Once you disable the Cloud Wrapper, run Remove-CloudWrapperConfiguration to proceed with the delete.

The delete can take up to three hours to complete.

Remove-CloudWrapperConfiguration -ConfigID 54321

The operation doesn't return any output.

Pass your configuration's ID in the Get-CloudWrapperConfiguration operation to review its deletion status.

Get-CloudWrapperConfiguration -ConfigID 54321

configId                : 54321
configName              : my-config
contractId              : C-0N7RAC7
propertyIds             : {12345, 98765}
comments                : Real traffic
status                  : DELETE_IN_PROGRESS
retainIdleObjects       : False
locations               : {@{trafficTypeId=1; comments=; capacity=; mapName=cw-s-use}}
multiCdnSettings        : 
capacityAlertsThreshold : 80
notificationEmails      : {jsmith@example.com, jasmith@example.com}
lastUpdatedDate         : 3/31/2026 5:50:26 PM
lastUpdatedBy           : jsmith
lastActivatedDate       : 
lastActivatedBy         : 

2. Activate a wrapper configuration

If you haven't activated your configuration upon creation, you can activate it separately with New-CloudWrapperConfigurationActivation by passing your Cloud Wrapper's configuration ID. Activating the configuration makes it available for your property.

📘

Activation processing takes 3–4 hours.

New-CloudWrapperConfigurationActivation -ConfigurationIDs 54321

The operation doesn't return any output.

You can use your configuration's ID to run the Get-CloudWrapperConfiguration operation and review its status.

Get-CloudWrapperConfiguration -ConfigID 54321

configId                : 54321
configName              : my-config
contractId              : C-0N7RAC7
propertyIds             : {12345}
comments                : Real traffic
status                  : ACTIVE
retainIdleObjects       : False
locations               : {@{trafficTypeId=3; comments=; capacity=; mapName=cw-s-usw}}
multiCdnSettings        : 
capacityAlertsThreshold : 50
notificationEmails      : {jsmith@example.com}
lastUpdatedDate         : 3/31/2026 4:59:46 PM
lastUpdatedBy           : jsmith
lastActivatedDate       : 4/01/2026 6:14:37 PM
lastActivatedBy         : jsmith

You can make changes to your configuration while its activation is in progress. However, those changes won’t be included automatically. To apply them, run the activation again.

3. Configure property rules

Once your configuration is active, link it to your property.

1. Get your property's rule tree as JSON snippets. The output is a directory at your current location containing your rule's configurations.

   Command

   Get-PropertyRules -PropertyName 'my-property' -PropertyVersion 'latest' -OutputSnippets -OutputDirectory './my-property-rules'

2. Add a cloudWrapper behavior to your property's rule trees, selecting a location you've set in your Cloud Wrapper configuration to use its cache space. Additionally, set the trigger criteria.

   Notes:

   • You can't use the cloudWrapper behavior in conjunction with the sure​Route, tiered​Distribution, or siteShield behavior.
   • cloudWrapper isn't compatible with the originTimeout criterion and can't be used within a rule using this criterion.
   • Cloud Wrapper doesn't work with Enhanced TLS hosts.

   JSON

   {
       "name": "Cloud Wrapper",
       "children": [],
       "behaviors": [
           {
               "name": "cloudWrapper",
               "options": {
                   "enabled": true,
                   "location": "cw-s-usw"
               }
           }
       ],
       "criteria": [
           {
               "name": "requestHeader",
               "options": {
                   "matchOperator": "IS_ONE_OF",
                   "matchWildcardName": false,
                   "matchWildcardValue": false,
                   "matchCaseSensitiveValue": true,
                   "headerName": "enable-cw",
                   "values": [
                       "true"
                   ]
               }
           }
       ],
       "criteriaMustSatisfy": "all",
       "comments": ""
   }

3. Add your updated rules to your property, pointing to the appropriate directory.

   Send your entire rule tree back. Rules not returned are removed from your property.

   Command

   Set-PropertyRules -PropertyName 'my-property' -PropertyVersion 'latest' -InputDirectory './my-property-rules' -VersionNotes 'Adding a Cloud Wrapper setting'

   The output returns your rule tree along with any errors or warnings upon upload.

4. Activate a property

Reactivate your property to enable your Cloud Wrapper configuration on the production network using the New-PropertyActivation command or its alias Deploy-Property.

Deploy-Property -PropertyName 'my-property' -PropertyVersion 'latest' -Network 'PRODUCTION' -NotifyEmails 'jsmith@email.com'

activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

Cloud Wrapper configuration

This provides you with a full list of parameters you need to pass in the New-CloudWrapperConfiguration and Set-CloudWrapperConfiguration operations.

Advanced settings for Multi CDN

These settings are available only to Akamai Global Services Support.