Configuring Akamai CDN: where traffic delivery breaks down
Delivery breaks not at the CDN connection stage, but in operations, when the configuration becomes overgrown with exceptions. In Akamai, rules live in Property Manager and are published in versions: first to a test environment, then to production.
Version drift between regions is the most common reason why cache behaves differently for some users than for others.
The first bottleneck in content delivery is cache behavior under peak load.
If response TTL is set as an afterthought, and the cache key includes headers that change from request to request — session ID, campaign tags, language — the hit ratio drops, and peak load on the origin grows many times over.
An origin sized for average traffic begins returning 502 and 504 exactly when delivery matters most.
Second — diverging caching rules between geographic zones and environments.
A rule added only to the production version disappears at the next publication from the configuration management system; an exception for the account area, forgotten in one of the regional sets, causes personalized responses to go into the shared cache.
Availability monitoring does not catch such divergences — they show up as "sometimes fast, sometimes slow."
Third — routing to the origin: without explicitly defined acceleration zones and alternative paths, traffic takes an arbitrary route, and time to first byte grows severalfold for no apparent reason.
Below, we break down how this is addressed: from rule structure and cache key to configuration management as code.
The effect of configuration: delivery speed, cache hits, resilience
The effect of configuration is measured by three numbers: the share of requests served by cache nodes without hitting the origin, response time for the end user, and headroom for peak load.
We move content delivery to the Akamai edge — below is how each metric changes and which failures stop reaching the user.
Cache hit ratio
We define rules by content type: static assets, media, application responses — each with its own cache TTL, handling of query parameters and headers. Most requests are served at the nearest node; only misses and revalidations go to the origin.
For static assets, the hit ratio reaches 90% and above — previously these requests fell entirely on the origin.
Response time for the end user
Content is served from the nearest node rather than across a continent: the network leg and connection setup time are reduced.
For dynamic content, optimized routes between nodes and persistent connections to the origin are used — response no longer depends on distance to the server. The median response time drops severalfold, and variation between regions shrinks.
Resilience to peaks and reduced origin load
Traffic spikes are absorbed by cache nodes, and the origin receives a steady stream of misses instead of a peak. A class of failures related to overload disappears: timeouts, delivery degradation, cascading errors on dependent services. Campaign launches and mass content updates no longer require pre-scaling the infrastructure.
We capture metrics before and after: hit ratio, response time by region, volume of traffic reaching the origin. We use them to tune caching and cache purge rules so the effect holds rather than being achieved once.
CDN content delivery schemes: when each fits
Content delivery schemes are chosen not by traffic volume, but by response profile and acceptable latency. In a single Akamai configuration, these modes are combined: some paths are served directly from servers, some from cache at the edge, some from an intermediate tier.
We separate the options by four criteria — cacheability, geography, object size, and origin requirements.
| Scheme | When it fits | Limitations |
|---|---|---|
| Direct delivery from servers | Personalized responses, restricted sections, content with a short lifespan | No cache — all load and latency fall on the origin server |
| Classic delivery network | Static assets, media, catalog, pages with a long retention period | On a cache miss, the request goes to the origin from every node |
| Multi-tier delivery | Heavy files, many regions, expensive cache fill | Requires an intermediate tier and rules for its population |
| Edge compute at nodes | Validation, data substitution, response assembly close to the user | Logic at the edge is maintained and tested separately |
Practice: we start with classic delivery and enable multi-tier when the origin can no longer keep up with cache fill. Switching schemes is a rule change in the property, without rebuilding the site structure or a new release. Modes are mixed by path: media and static assets go through cache, checkout goes direct.
Work stages: traffic audit, caching scheme, validation
Akamai CDN configuration starts not from editing configuration, but from data: we capture a traffic map, design the caching scheme, and only then enable rules on live traffic.
Skipping the audit produces cache "by eye": static assets and personalized responses fall under one rule, and rollback is done blindly.
- Traffic map audit: we analyze logs and request parameters — which paths are static, which depend on the session, where large bodies are, how requests are distributed by region. The output is content groups with TTL and criteria for classifying a request.
- Caching scheme alignment: for each group, we decide what is stored at the network edge and what goes to the origin server, which headers and cookies are passed through and which are stripped so as not to multiply unique copies.
- Rule design in Property Manager: we assemble them by priority — routing, cache miss behavior, origin error handling, stale object delivery. We establish which condition fires first when they overlap.
- Assembly in an intermediate environment: test domain, verification of response headers, cache hit ratio, and behavior when the origin is unavailable. We catch configuration errors here, not on live traffic.
- Validation on production traffic: we enable rules in stages, monitor hit ratio, response time by region, and error rate. If there is a deviation — rollback to the previous version without stopping delivery.
- Handover of control: we provide the traffic map, caching scheme, rule descriptions, and procedure for typical edits so the customer's team can change settings themselves and understand the consequences.
Property configurations, caching rules, and procedures
A property configuration in Akamai is not a set of checkboxes in a web interface, but a versioned artifact that can be compared, rolled back, and handed to another team.
We leave the customer a complete set: after launch, edits to cache behavior and routing are made by their own team, without contacting us for every change.
- Property configurations — exported descriptions in a readable format, organized by environment: test, pre-production, production. A change is validated in the lower environment before being deployed to production.
- Caching rules — TTL for each content type, cache keys, handling of query parameters, cache purge order after release. Addresses that must not be cached are described separately.
- Route schemes — where traffic goes from and to, which origins are primary and backup, how health checks and failover are configured.
- Access policies — content protection, region and request rate restrictions, rules for search and service agents, and role separation within the team.
- Change procedure — who prepares the edit, who approves it, what checks are mandatory before production, and how rollback to the previous version is performed.
- Incident response procedure — cache purge and warm-up, origin diagnostics, escalation points, and boundaries of responsibility between the parties.
The set is completed by a document describing the entire scheme and configured monitoring of key nodes. With it, a new engineer on the team can understand the configuration in one workday rather than reconstructing the logic from chat history.
Case study: stable delivery during a sharp traffic increase
The customer is an online store with seasonal sales: during peak periods, traffic grew 6–8 times over several hours, and against that backdrop the site began returning errors.
The origins were sized for average load, and the delivery network operated almost in passthrough mode — edge nodes passed requests further to avoid risking a stale response.
Bottlenecks before the work
- Static cache worked partially: the key included advertising campaign tags, so each click on a link created a separate object.
- TTLs for images, scripts, and service responses were identical and minimal.
- On a cache miss, all requests went to the origin in a single stream, without limiting or background revalidation.
Result
We rewrote edge processing rules: removed unnecessary parameters from the cache key, separated policies by content type, added background revalidation of popular objects, and protected the origin from concurrent requests.
Routing to the nearest node and cache purge were tied to the release so deployment would not reset the entire edge — we worked on Akamai.
| Metric | Before | After |
|---|---|---|
| Edge responses | 46% | 91% |
| Peak response time | up to 5 s | 0.4-0.6 s |
| Peak error rate | 7% | less than 0.3% |
Origin overload stopped being a seasonal risk: on a cache miss, load is distributed rather than falling in a burst. Rule rollback takes minutes — the configuration is versioned.
How does management through the panel differ from configuration as code?
Both approaches manage the same Akamai rule model — a set of behaviors and conditions by which traffic is delivered. The difference is where the source of truth is stored: in the account or in a repository, and how visibly it can be changed.
In the panel, settings live as the state of a specific configuration version. There is version history, but it is not linked to a repository: the log shows that a rule was changed, not which lines in it changed.
Reproducing an environment from scratch is possible only by manually repeating the steps — and every divergence surfaces already on production traffic.
Configuration as code moves the same rules into files. Then familiar mechanics apply: branch, review, automated deployment, version comparison before activation.
Rollback is the main divergence. In the panel, it is activation of the previous version as a whole, with everything that has made it into it. In code, rollback is a reverse commit: you can see which rule returned to its previous value, and the rest is untouched.
Technical concerns: cache, invalidation, access
Objections about cache usually come down to three things: how quickly an edit reaches users, whether the cache will start serving someone else's content, and who can change the configuration at all.
All three are solved at the rule level, not by disabling caching "just in case" — without it, the edge loses its purpose, and load goes to the origin.
We break cache behavior into layers: what exactly is stored at the edge, by which key (URL, query parameters, cookie, headers), what content TTL is set for each object type, and what happens on a miss.
Cache invalidation is a separate workflow: targeted by URL or tag immediately after release, plus a reasonable TTL as insurance if the purge did not reach somewhere.
How quickly will an update reach users?
Tag-based invalidation removes all related objects from the edge in a single call, instead of iterating over URLs. The purge propagates in a wave across regions, so we first verify the result in the test environment and only then run it in production.
For static assets with a hash in the filename, purging is not needed at all — the URL itself changes.
Will the cache start serving personalized pages to others?
For authenticated and personal responses, the rule prohibits storage, and the cache key is extended with a cookie or header — then different users physically do not intersect on the same object.
We separately check scenarios with the cart and session tokens: they go to the origin bypassing the cache.
How should access to configuration management be separated?
We assign rights by role: an engineer edits and activates, a release engineer confirms deployment, an observer only views. Edits go through separate configuration copies with version history, so an unsuccessful change is rolled back by restoring the previous version. API access is closed with separate keys restricted by address and expiration.
Let's discuss the task: traffic, geography, delivery requirements
For the estimate to be accurate and the plan workable, we need not a list of wishes but facts about your traffic. They determine which caching and routing rules we will put in place and what share of requests will even reach the origin.
What is worth preparing for the discussion:
- Traffic profile: share of static and dynamic content, daily volumes, peaks from promotions and seasonal spikes.
- User geography: regions and countries for which delivery latency is critical.
- Delivery requirements: target response time, acceptable cache miss rate, behavior when the origin is unavailable.
- Current scheme: what is already in front of the service, what redirect and caching rules are configured.
- Constraints: data storage and processing regulations, requirements for specific regions, access roles.
- Timeline guidelines: what is needed for launch and what can be moved to the next stage.
This is enough for us to come back with an estimate and a plan: a delivery scheme by region, caching and cache purge rules, Akamai CDN configuration for your load profile, a security policy, and a change introduction procedure with rollback capability.
Describe the delivery task — come with what you have already gathered; we will clarify the rest as we go.