You can use Sandbox to create an isolated development environment to test your EdgeKV-enabled EdgeWorkers functions locally before deploying to production. The sandbox environment is restricted to operating only on Akamai staging. Production data is not accessible in a sandbox environment.

Review the EdgeWorkers documentation for instructions on how to install Sandbox and deploy an EdgeWorkers function to a sandbox.

Before you start

Before using Sandbox, you should consider where to create your test data and who will be using that data in your organization. Test data is often shared among developers, but can also be inadvertently overwritten by individual developers. Below are details that may be helpful in determining your approach to using test data when using EdgeKV and Sandbox:

• You cannot create sandbox-specific EdgeKV namespaces. ALL namespaces in your staging environment are accessible in the sandbox environment. Any namespace management operations and attributes, such as access permissions and geolocation, will apply to both the staging and sandbox environments.
• There are no sandbox-specific access tokens. Access tokens that include permissions to access namespaces on staging also allow access to those namespaces in the sandbox environment. This allows the same EdgeWorkers code bundle to be used in both the staging and sandbox environments.
• There are no permissions specific to accessing sandbox via the management API and CLI. Staging permissions allow access to both staging and sandbox environments.
• Sandbox data does not share the same retention period as that of the staging namespace in which it resides. Instead, sandbox data has a fixed retention period of TWO DAYS that cannot be changed. Sandbox data is meant to be ephemeral.
• There is no protection to prevent developer X from accessing the sandbox data of developer Y within your account if they use each other's sandbox ids intentionally or accidentally. Please bear this in mind when using Sandbox.
• Sandbox data should not be considered confidential and should only contain test or “dummy” data.

Advantages of using Sandbox

Although you can collaborate with your peers on read-only EdgeKV data in a staging environment, there is a risk you could overwrite each other's data while building. This can occur if you write, update, or delete shared staging data using either the management APIs, or if an EdgeWorkers function performs these operations. Sandbox allows you to choose whether you want to use the common shared staging data, or your own copy of that data in your sandbox environment.

Collaborating in staging by using different groups and items also presents a challenge of coordination. This coordination can become tricky as the volume of data in your staging environment grows. More importantly, it makes it difficult to collaborate on EdgeWorkers code that accesses the same namespace, group, and item, as it is usually best practice to test the code “as is” without each developer being forced to modify the data being accessed by EdgeWorkers code.

How Sandbox data is stored and accessed

Sandbox items are stored in the staging namespace using special groups augmented with a sandboxId value, such as <groupId>_<sandboxId>. The sandbox management and JavaScript library APIs abstracts this by automatically appending the sandboxId to the specified groupId. When using the management API or CLI, you need to specify the sandboxId explicitly as a parameter to the API endpoint or CLI command.

👍

You should not directly access data using the <groupId>_<sandboxId> format since it may change without notice.

List sandboxes

To retrieve a list of sandboxIds available from your property, you can run the “sandbox list” CLI command. For example:

% akamai sandbox list

Here's an example response:

Local sandboxes:

current  name    	sandbox_id
-------  ----------  ------------------------------------
YES  	    my_sandbox  1f4c7d5b-xxxx-xxxx-xxxx-979320b99cee

You can also use the Sandbox API endpoint to get a list of sandboxes.

JavaScript library support

The EdgeKV Helper library supports access to test data in Sandbox from your EdgeWorkers function. The EdgeKV constructor call accepts two optional parameters ew_request and sandbox_fallback.

You can optionally set ew_request to the EdgeWorkers request object that was passed as a parameter in the event handler call. Combined with the sandbox_fallback parameter, this allows you to specify whether your EdgeWorkers function, running in a sandbox environment, should access:

• data from sandbox exclusively
• data from staging exclusively
• data from sandbox but fall back to staging data if the requested data does not exist in the sandbox environment in which your EdgeWorkers function is executing (fallback behavior only applies to read operations).

When the EdgeWorkers function is not running in a sandbox environment, data access occurs to and from staging or production depending on the environment in which the EdgeWorkers function is executing. This allows you to use the same code, unmodified, in all three environments.

The following table can help you decide how to use these new parameters to specify your desired sandbox and staging EdgeKV data access, based on your needs.

👍

Production data can only be accessed from an EdgeWorkers function deployed to the production network.

Use sandbox-specific data

In this scenario, you use EdgeKV data from an EdgeWorkers function deployed to a sandbox in read and write mode. This is only allowed in the staging environment using the namespace you specify in your JavaScript code.

The EdgeKV JavaScript object must be constructed with the EdgeWorkers request object as a parameter. The EdgeKV object must be instantiated within an EdgeWorkers event handler’s body to have access to the request object. In this case, all read, write, and delete data accesses using that EdgeKV JavaScript object from within an EdgeWorkers event handler executing in a sandbox environment will be to the EdgeKV sandbox data. In case of read, if the requested item does not exist in the sandbox environment, null (or the specified default item value in the getText or getJson method invocation) is returned.

When EdgeWorkers code using an EdgeKV object constructed with the request object executes in a staging environment, staging data is accessed. Similarly, when code using an EdgeKV object constructed with the request object executes in a production environment, only production data is accessed

Write to sandbox

export async function responseProvider(request) {
    ...
    const edgeKV = new EdgeKV({ namespace: "default", group: "greeting", ew_request: request });
    let resp = await edgeKV.putText({ item: "item1", value: "Sandbox value" });
    ...
}

Example: Read from sandbox

export async function responseProvider(request) {
    ...
    const edgeKV = new EdgeKV({ namespace: "default", group: "greeting", ew_request: request });
    let resp = await edgeKV.getText({ item: "item1" });
    ...
}

Use data from a namespace in staging

This scenario lets you use the common staging data from an EdgeWorkers function in read and write mode. It is the default behavior for backwards compatibility with existing EdgeWorkers JavaScript code and behavior in a staging environment. When using this option developers need to take precautions to avoid overwriting each other's staging data.

In this scenario you don't need to make any modifications to your existing EdgeWorkers code if you created it before the introduction of Sandbox support for EdgeKV. As long as the EdgeKV JavaScript object is constructed without the EdgeWorkers request as a parameter, all EdgeKV read, write, and delete data accesses from an EdgeWorkers function running in a sandbox environment will be made to the staging data.

Example: Write to staging

export async function responseProvider(request) {
    ...
    const edgeKV = new EdgeKV({ namespace: "default", group: "greeting" });
    let resp = await edgeKV.putText({ item: "item1", value: "Staging value" });
    ...
}

Example: Read from staging

export async function responseProvider(request) {
    ...
    const edgeKV = new EdgeKV({ namespace: "default", group: "greeting" });
    let resp = await edgeKV.getText({ item: "item1" });
    ...
}

Use the sandbox data but fallback to staging

In this option you can use sandbox specific data, but fallback to the staging data if the data is not contained in the sandbox. As a result, you can run the same code in both staging and sandbox even if you do not have any sandbox specific data. This is allowed exclusively for read operations. Write and delete operations will continue to use sandbox only when running in a sandbox environment.

Use this scenario as a failsafe when the requested item may not already exist in the sandbox environment. To create an item, the EdgeKV JavaScript object must be constructed with the EdgeWorkers request as well as the sandbox_fallback flag set to true. The EdgeKV object must be instantiated within an EdgeWorkers event handler’s body. All EdgeKV reads from an EdgeWorkers function running in a sandbox environment will attempt to fetch the item from the sandbox data, but will fall back to fetching the item from staging data if the sandbox item is not present.

In this scenario, write and delete requests from an EdgeWorkers function running in a sandbox environment will only access sandbox data, as mentioned above.

👍

If an EdgeKV item is deleted from a sandbox, a subsequent read might return the staging data instead of an empty result if the same item also exists in staging.

Example: Read from sandbox with a fallback to staging

export async function responseProvider(request) {
    ...
    const edgeKV = new EdgeKV({ namespace: "default", group: "greeting", ew_request: request, sandbox_fallback: true });
    let resp = await edgeKV.getText({ item: "item1" });
    ...
}