Add and maintain policy rules
Deliver a smooth, efficient, and visually engaging customer experience. Use our customization features to manage, optimize, and modify your images and short-form videos.
Prep
When working with the Image and Video Manager API, your contract should include images, videos, or both depending on the media type you want to work with. You also need to have READ-WRITE access to the Property Manager API.
Create policy sets and policies
A policy set serves as a collection of policies with optimization and transformation configuration settings for your images and videos. You can create these policy set types:
- An image policy set contains only image policies.
- A video policy set contains only video policies.
Things to keep in mind about policy sets and policies:
- A policy set belongs to a single contract and can be used across multiple properties.
- A policy belongs to a single policy set.
- A property can have multiple policy sets.
New policy set
When creating a new policy set, define the following in the akamai_imaging_policy_set resource:
- Policy name.
- Region for which it applies.
- Policy type (image or video).
- Your contract ID.
resource "akamai_imaging_policy_set" "my-policy-set" {
contract_id = "12345"
name = "my-image-policy-set"
region = "US"
type = "IMAGE"
}
The policy set is automatically activated on both staging and production networks after creating it. Also, it applies a default .auto policy with baseline settings for derivative images and videos. Nothing happens to the policy set until you link it to a property.
Instead of using the baseline settings, you can adjust the .auto policy to your needs. To do that, create a new policy and add appropriate settings to it. Make sure that the policy has the policy ID set to .auto.
You can create as many policy sets and policies as you need on a single contract.
For an existing policy set, you can update its name and region.
- Altering the
regionvalue on an existing policy set voids previously cached images and videos and requires their transformation again.- Changing the
typevalue forces a replacement. It destroys your current policy set and creates a new one.
New policy
Depending on whether you want to create a new image or video policy within your policy set, specify its settings in the akamai_imaging_policy_image or akamai_imaging_policy_video resource. This includes:
- Contract ID.
- Policy ID.
- Policy set ID.
- JSON file for your policy rules or a full definition of your policy rules.
- Network of policy activation.
resource "akamai_imaging_policy_image" "my-image-policy" {
activate_on_production = false
contract_id = "12345"
policy_id = "my-image-policy"
policyset_id = akamai_imaging_policy_set.my-policy-set.id
json = file("${path.module}/image_policy.json")
}
resource "akamai_imaging_policy_image" "my-image-policy" {
activate_on_production = false
contract_id = "12345"
policy_id = "my-image-policy-1"
policyset_id = akamai_imaging_policy_set.my-policy-set.id
json = jsonencode(
{
"rolloutDuration" : 3602,
"breakpoints" : {
"widths" : [
300,
451,
2039,
5000
]
},
"output" : {
"quality" : 94,
"adaptiveQuality" : 70
},
"transformations" : [
{
"transformation" : "Contrast",
"brightness" : 0.5,
"contrast" : 0.2
},
{
"gravity" : "SouthWest",
"image" : {
"url" : "www.example.com/image.png"
},
"transformation" : "Composite",
"xPosition" : 0,
"yPosition" : 0
}
],
"postBreakpointTransformations" : [
{
"color" : "#ffffff",
"transformation" : "BackgroundColor"
},
{
"transformation" : "Blur",
"sigma" : 5
}
],
}
)
}
The created policy is automatically activated on staging. To activate it on production, set the activate_on_production argument to true in either the the akamai_imaging_policy_image or akamai_imaging_policy_video resource.
Add a separate resource for each policy you're adding.
Alternatively, you can use the akamai_imaging_policy_image or akamai_imaging_policy_video data source to define your policy settings, and then reference that data source in the corresponding akamai_imaging_policy_image or akamai_imaging_policy_video resource.
data "akamai_imaging_policy_image" "my-image-policy-definition" {
policy {
rollout_duration = 3602
breakpoints {
widths = [
300,
451,
2039,
5000
]
}
output {
quality = 94
adaptive_quality = 70
}
transformations {
contrast {
brightness = 0.5
contrast = 0.2
}
}
transformations {
composite {
gravity = "SouthWest"
image {
url_image {
url = "www.example.com/image.png"
}
}
x_position = 0
y_position = 0
}
}
post_breakpoint_transformations {
background_color {
color = "#ffffff"
}
}
post_breakpoint_transformations {
blur {
sigma = 5
}
}
}
}
resource "akamai_imaging_policy_image" "my-image-policy" {
activate_on_production = false
contract_id = "12345"
policy_id = "my-image-policy-1"
policyset_id = akamai_imaging_policy_set.my-policy-set.id
json = data.akamai_imaging_policy_image.my-image-policy-definition.json
}
To set up variables in a policy resource or data source, see the Use variables section.
If you're modifying an existing policy resource that's been activated on the production network, set activate_on_production to false. Changing this value doesn't remove the policy from the production network, but lets you safely make changes to the policy on staging.
Updating the
policy_idvalue forces a replacement. It destroys your current policy and creates a new one.
Import a policy set and its policies
When working with an existing policy set, you can import it with its related policies.
-
If you don't know your policy set ID, run the List policy sets operation from the Image and Video Manager API. This returns a list of policy sets available to you.
-
Then export an existing policy set with its policies by passing your contract and policy set IDs in the export command.
Optionally, add the
--policy-as-hclcommand flag to export your imaging policy with rules in HCL format.akamai terraform --edgerc {location-of-your-edgerc-file} --section {section-of-edgerc-to-use} export-imaging --policy-as-hcl {"your-contract-id"} {"your-policy-set-id"} -
Run the included import script to populate your Terraform state and prevent Terraform from attempting to recreate your assets.
Use variables
Many Image and Video Manager arguments let you specify a variable object instead of a string, number, or boolean value.
Variables can be of these types:
boolnumberurlcolorgravityplacementscaleDimension
grayscaleTypeaspectresizeTypedimensionperceptualQualitystringfocus
When using variables in the akamai_imaging_policy_image or akamai_imaging_policy_video resource, define the variable name in the var argument. For example, if you want a variable for the gravity argument in a transformation, you'd use the var argument inside it. Then, provide the variable name as a value to reference your variable defined in the variables block. This is instead of providing a direct value for the gravity argument.
resource "akamai_imaging_policy_image" "my-image-policy" {
activate_on_production = false
contract_id = "12345"
policy_id = "my-image-policy-1"
policyset_id = akamai_imaging_policy_set.my-policy-set.id
json = jsonencode(
{
"rolloutInfo" : {
"startTime" : 1740163087,
"endTime" : 1740163088,
"rolloutDuration" : 1,
"serveStaleEndTime" : 1740163087
},
"breakpoints" : {
"widths" : [
300,
451,
2039,
5000
]
},
"output" : {
"quality" : 94,
"adaptiveQuality" : 70
},
"transformations" : [
{
"transformation" : "Contrast",
"brightness" : 0.5,
"contrast" : 0.2
},
{
"gravity" : {
"var" : "centerGravity"
},
"image" : {
"url" : "www.example.com/image.png"
},
"transformation" : "Composite",
"xPosition" : 0,
"yPosition" : 0
},
{
"default" : {
"aspect" : "fit",
"height" : {
"var" : "ResizeDim"
},
"transformation" : "Resize",
"type" : "normal",
"width" : {
"var" : "ResizeDim"
}
},
"dimension" : "height",
"lessThan" : {
"allowExpansion" : true,
"gravity" : {
"var" : "centerGravity"
},
"height" : {
"var" : "ResizeDim"
},
"transformation" : "Crop",
"width" : {
"var" : "ResizeDim"
},
"xPosition" : 0,
"yPosition" : 0
},
"transformation" : "IfDimension",
"value" : {
"var" : "MinDim"
}
}
],
"postBreakpointTransformations" : [
{
"color" : "#ffffff",
"transformation" : "BackgroundColor"
},
{
"transformation" : "Blur",
"sigma" : 5
}
],
"variables" : [
{
"defaultValue" : "280",
"name" : "ResizeDim",
"type" : "number"
},
{
"defaultValue" : "10",
"name" : "MinDim",
"type" : "number"
},
{
"defaultValue" : "Center",
"name" : "centerGravity",
"type" : "gravity"
}
]
}
)
}
When using variables in the akamai_imaging_policy_image or akamai_imaging_policy_video data source, define the variable name in an argument that ends in _var. For example, if you want to have a variable for the gravity argument in a transformation, you’d use the gravity_var argument, not the gravity one. Then, in the gravity_var argument, provide the variable name as a value to reference your variable defined in the variables block.
data "akamai_imaging_policy_image" "my-image-policy-definition" {
policy {
breakpoints {
widths = [280, 1080]
}
hosts = ["www.example-1.com", "www.example-2.com"]
output {
adaptive_quality = 50
perceptual_quality = "mediumHigh"
}
transformations {
region_of_interest_crop {
gravity_var = "centerGravity"
height = 8
region_of_interest {
rectangle_shape {
anchor {
x = 4
y = 5
}
height = 9
width = 8
}
}
style = "fill"
width = 7
}
}
transformations {
append {
gravity_var = "centerGravity"
gravity_priority = "horizontal"
image {
text_image {
fill = "#000000"
size = 72
stroke = "#FFFFFF"
stroke_size = 0
text = "test"
}
}
preserve_minor_dimension = true
}
}
transformations {
trim {
fuzz = 0.08
padding = 0
}
}
transformations {
if_dimension {
default {
resize {
aspect = "fit"
height_var = "ResizeDim"
type = "normal"
width_var = "ResizeDim"
}
}
dimension = "height"
less_than {
crop {
allow_expansion = true
gravity_var = "centerGravity"
height_var = "ResizeDim"
width_var = "ResizeDim"
x_position = 0
y_position = 0
}
}
value_var = "MinDim"
}
}
variables {
default_value = "Center"
name = "centerGravity"
type = "gravity"
}
variables {
default_value = "280"
name = "ResizeDim"
type = "number"
}
variables {
default_value = "1000"
name = "MinDim"
type = "number"
}
}
}
Update a property rule tree
You need to add one or more imaging policy behaviors to the JSON rule tree file for each property you're adding image policies to.
-
Depending on the policy set type you're adding, add appropriate behaviors to your property rules'
main.json. Make sure to use the correct policy set ID when adding these behaviors.{ "name": "Image and Video Manager (Images)", "children": [], "behaviors": [ { "name": "caching", "options": { "behavior": "MAX_AGE", "mustRevalidate": false, "ttl": "30d" } }, { "name": "imageManager", "options": { "apiReferenceTitle": "", "applyBestFileType": true, "enabled": true, "resize": false, "settingsTitle": "", "useExistingPolicySet": true, "trafficTitle": "", "cpCodeOriginal": { "id": 12345 }, "cpCodeTransformed": { "id": 98765 }, "policySet": "ivm_12345" } } ], "criteria": [ { "name": "fileExtension", "options": { "matchCaseSensitive": false, "matchOperator": "IS_ONE_OF", "values": [ "jpg", "gif", "jpeg", "png", "imviewer" ] } } ], "criteriaMustSatisfy": "all", "comments": "" }data "akamai_property_rules_builder" "my-image-rules" { rules_v2023_05_30 { name = "Image and Video Manager (Images)" comments = "" criteria_must_satisfy = "all" behavior { caching { behavior = "MAX_AGE" must_revalidate = false ttl = "30d" } } behavior { image_manager { api_reference_title = "" apply_best_file_type = true cp_code_original { id = 12345 } cp_code_transformed { id = 98765 } enabled = true policy_set = "ivm_12345" resize = false settings_title = "" traffic_title = "" use_existing_policy_set = true } } criterion { file_extension { match_case_sensitive = false match_operator = "IS_ONE_OF" values = ["jpg", "gif", "jpeg", "png", "imviewer", ] } } } }{ "name": "Image and Video Manager (Videos)", "children": [], "behaviors": [ { "name": "caching", "options": { "behavior": "MAX_AGE", "mustRevalidate": false, "ttl": "30d" } }, { "name": "imageManagerVideo", "options": { "apiReferenceTitle": "", "applyBestFileType": true, "enabled": true, "resize": false, "settingsTitle": "", "useExistingPolicySet": false, "trafficTitle": "", "cpCodeOriginal": { "id": 12345 }, "cpCodeTransformed": { "id": 98765 }, "superCacheRegion": "US", "advanced": false, "policyTokenDefault": "my-default-policy" } } ], "criteria": [ { "name": "fileExtension", "options": { "matchCaseSensitive": false, "matchOperator": "IS_ONE_OF", "values": [ "mp4" ] } } ], "criteriaMustSatisfy": "all", "comments": "" }data "akamai_property_rules_builder" "my-video-rules" { rules_v2023_05_30 { name = "Image and Video Manager (Videos)" comments = "" criteria_must_satisfy = "all" behavior { caching { behavior = "MAX_AGE" must_revalidate = false ttl = "30d" } } behavior { image_manager_video { advanced = false api_reference_title = "" apply_best_file_type = true cp_code_original { id = 12345 } cp_code_transformed { id = 98765 } enabled = true policy_token_default = "my-default-policy" resize = false settings_title = "" super_cache_region = "US" traffic_title = "" use_existing_policy_set = false } } criterion { file_extension { match_case_sensitive = false match_operator = "IS_ONE_OF" values = ["mp4", ] } } } }Additional considerations:
- To apply these behaviors, you also need to add the file_extension match criteria and the caching behavior.
- The
imageManagerbehavior includes its own CP code settings. Make sure not to include it in the same rule with the cp_code behavior. - Place the
image_managerorimage_manager_videobehavior at the end of your property rules to ensure it works correctly.
-
Add your updated rules to your property:
-
If you store your rules in the
akamai_property_rules_builderdata source, point to that data source in your property.resource "akamai_property" "my_property" { name = "MyProperty" product_id = "prd_Object_Delivery" contract_id = "C-0N7RAC7" group_id = "12345" rule_format = "v2023-05-30" rules = data.akamai_property_rules_builder.my-image-rules.json depends_on = akamai_property_include_activation.id hostnames { cname_from = "example.com" cname_to = "example.com.edgekey.net" cert_provisioning_type = "DEFAULT" } } -
If you store your rules in JSON format, point to the rules in the
akamai_property_rules_templatedata source and reference it in your property.data "akamai_property_rules_template" "rules" { template_file = abspath("${path.module}/property-snippets/main.json") } resource "akamai_property" "my_property" { name = "MyProperty" product_id = "prd_Object_Delivery" contract_id = "C-0N7RAC7" group_id = "12345" rule_format = "v2023-05-30" rules = data.akamai_property_rules_template.rules.json depends_on = akamai_property_include_activation.id hostnames { cname_from = "example.com" cname_to = "example.com.edgekey.net" cert_provisioning_type = "DEFAULT" } }
-
Activate a property
To activate the property containing your newly added imaging or video policies, provide a value for the network, staging or production, and activate your property.
resource "akamai_property_activation" "my_staging_activation" {
property_id = "prp_12345"
contact = ["jsmith@example.com"]
version = akamai_property.my_property.latest_version
network = "STAGING"
note = "Activating my property on staging"
auto_acknowledge_rule_warnings = false
}
Delete policy sets and policies
If needed, run terraform destroy to remove a policy set and its related policies. This deletes all policies within a given set including the .auto policy.
You can also remove individual policies from a policy set. The exception is the .auto policy, which you can remove only if you delete the policy set.
Updated about 19 hours ago