Before you serve traffic through the Akamai production network, it's recommended that you test your configuration on the staging network.

This procedure applies to environments with the testing and production profiles. Your service hostnames reach them through a host-based route, the same way your production traffic does, so testing doesn't require any tokens or environment headers. Development environments are isolated and use a different method. See Test a development environment.

How testing on staging works

Once an environment version and its service hostname set are activated on the staging network, the same configuration your production traffic would get is available on staging edge servers.

You redirect your requests to a staging edge server while keeping your service hostname in the URL, so the Host header and the TLS SNI still carry it. The edge matches the correct service hostname and edge certificate, and the host-based route selects the environment — exactly as it does in production.

You can redirect requests two ways:

🚧

Akamai's staging network is a subset of servers you use for testing configuration changes rather than performance. As the individual servers in the staging network can change over time, resolve the staging edge hostname again before you start a new round of testing. Don't reuse an IP address you resolved previously, and don't use the same IP address for an extended period of time.

Before you begin

Before testing on staging, make sure you meet these prerequisites:

• Your environment version and the service hostname set you want to test with are both activated on the staging network. Environments and service hostname sets activate on independent tracks, and they need to be active on the same network to interact.
• Domain ownership and certificates for the service hostnames in the set are validated. Until certificate validation completes, HTTPS requests to those service hostnames fail.
• HTTPS custom certificates only. Push the edge certificate to staging. If you're going to use a custom certificate for the client to edge server connection, you need to push it to the staging network before you test your HTTPS delivery. By default, when you create a CPS-managed certificate, it's automatically deployed to the production network. To test the certificate, you need to manually push it to the staging network. See Certificate Provisioning System for detailed instructions.
• You have a way to redirect requests to a staging edge server, either per request from the command line or through your local hosts file. Editing the hosts file needs administrator privileges on most systems.

1. Find your staging edge hostname

1. From the Control Center menu, click Content delivery > CDN > Delivery Manager.
2. In the Workspaces page, click the workspace that contains the set you want to edit.
3. Open service hostnames:
   • Workspace level: Go to the Service hostnames tab within a workspace to view all of its service hostnames and sets.
   • Environment level: Go to the Environments tab within a workspace and click the environment that contains the set you want to test. Next, go to the Service hostnames tab to view only the sets routed to that environment.
4. In the Service hostnames tab, find and make note of your edge hostname.
5. Append -staging before the final .net. For example, www.example.com.edgekey.net becomes www.example.com.edgekey-staging.net.

This is the staging network target for your service hostname.

2. Point your requests to staging

Choose one of these methods to reach the staging network. Both keep your service hostname in the URL, which is what lets the edge match the right service hostname and certificate.

Per request

Point the connection at your staging edge hostname without resolving it yourself and without changing anything on your system:

curl -v https://www.example.com/ --connect-to ::www.example.com.edgekey-staging.net:

--connect-to opens the connection to the staging edge hostname while leaving the URL untouched. This needs curl 7.49 or later.

📘

Per-request redirection resolves the staging edge hostname fresh on every request, so you never hold a stale IP address. It also works in use cases where modifying a hosts file isn't possible.

If your tool accepts an explicit hostname-to-IP mapping instead, resolve the IP address first:

• Windows: Open a new command prompt and perform an nslookup of the staging edge hostname:

  nslookup www.example.com.edgekey-staging.net

• macOS, Linux, or Unix: Open a new terminal and perform a dig of the staging edge hostname:

  dig +short www.example.com.edgekey-staging.net

Copy an IP address from the response and supply it to your tool. Resolve it again at the start of each testing round.

Through your hosts file

Use this for browsers and for tools with no per-request redirection of their own.

1. Resolve the IP address of your staging edge hostname, using the nslookup or dig command above, and copy it from the response.

2. Open your local hosts file in a text editor. See your operating system's user documentation for the default location. Typically, you can find it in these directories:

   • Windows: C:\Windows\System32\drivers\etc\hosts. The directory above \system32\ might vary in your environment.
   • macOS: /private/etc/hosts.
   • Linux or Unix: /etc/hosts.

3. At the end of the hosts file, add an entry that pairs the IP address you copied with your service hostname. For example:

   12.34.56.78  www.example.com

   Add one line per service hostname you want to test.

4. Save and close the hosts file.

5. Flush your local DNS cache:

   • Windows: Open a new command prompt and run this command:

     ipconfig /flushdns

   • macOS: Open a new terminal and run this command:

     sudo killall -HUP mDNSResponder

All requests from your local system to that service hostname now go to the staging edge server. The change applies only to your local system and doesn't affect anyone else.

3. Confirm you reached the staging network

Verify connectivity with a command-line tool before you test anything else.

• If you're using the recommended Enhanced Debug behavior, generate an auth token and pass it in the Akamai-Debug header:

  curl -vvvv "https://www.example.com/" -H "Akamai-Debug: exp=1762...700b cache"

• If you're using Pragma debugging, specify the Pragma header:

  curl -vvvv "https://www.example.com/" -H "Pragma: akamai-x-cache-on, akamai-x-cache-remote-on"

A successful response looks like this:

HTTP/1.1 200 OK
...
X-Akamai-Staging: ESSL
X-Cache: TCP_MISS from ...

Making a request to Akamai staging edge servers adds the X-Akamai-Staging response header. The value is X-Akamai-Staging: ESSL for requests using an Enhanced TLS edge hostname, or X-Akamai-Staging: EdgeSuite for requests using a Standard TLS edge hostname.

Then check for the X-Cache response header and interpret the result:

4. Test your configuration

Test your site just as you would if you were testing against your origin. Edge testing doesn't depend on how you deployed the configuration, so you can use whatever tools and test suites you already have.

🚧

When testing, use your actual service hostname for requests. Don't use its edge hostname or its staging edge hostname. Both bypass the hostname matching that this method depends on.

1. Check your site's key functionality, such as logging in, using the shopping cart, playback, and any flow that spans more than one request.

2. Verify the behavior your version actually changes. Depending on the configuration, that can include:

   • Response status codes and response headers.
   • Caching behavior, including Cache-Control and whether objects are cached at all.
   • Redirect logic, including the destination and status code of each redirect.
   • Origin routing, if paths in this version resolve to different origins.

3. Test each service hostname in the set, if the version behaves differently per hostname.

5. Integrate checks into your pipeline

Edge behavior is verifiable with ordinary HTTP assertions, so you can run these checks from the same framework and pipeline you already use for your application, ahead of a production activation.

1. Express each check as an assertion on the response, such as a status code, a specific header, a cache result, or a redirect target, rather than on whether the request succeeded.
2. Point the assertions at your service hostname, with requests redirected to staging by whichever method in step 2 suits your runner.
3. Run the suite as a gate before activating on the production network, and fail the build when an assertion fails.
4. Re-resolve the staging edge hostname at the start of each run rather than storing an IP address in your configuration.

6. Clean up

1. If you added a hosts file entry, remove it, save the file, and flush your local DNS cache again. Nothing to undo if you redirected per request.
2. If the testing was successful, activate the configuration on the Akamai production network, along with the associated custom edge certificate if you use one.

Troubleshooting