🚧

Warning!

EdgeKV is a distributed key-value store that enables JavaScript developers to build data-driven EdgeWorkers applications for latency-sensitive use cases. The current release of EdgeKV is not designed for handling personal, confidential, proprietary data, or any other type of data where unauthorized access to or disclosure of such data would result in loss, legal or regulatory liability, or other harm to Customers or their end users (“Sensitive Data”). EdgeKV should not, therefore, be used to store Sensitive Data. In addition, do not use data returned from EdgeKV to influence workflows that are in scope for compliance frameworks which mandate specific requirements for the handling of Sensitive Data without conducting an appropriate impact review. Customers of EdgeKV are responsible for maintaining control over the data loaded into EdgeKV and for review of applicable information security, privacy, and compliance requirements to determine the appropriateness of their use of this service.

Roles and permissions

The permissions granted to an API client are identical to those of the user creating it. If a user's permissions change after the API client is created, the API client permissions are not automatically updated.

We recommend that you create a new API client to use with EdgeKV during this availability phase. You should do this even if you already have a working API client for EdgeKV for a previous phase. You should also create a new API client whenever a user’s permissions are modified, as described above. You can also deactivate the API clients that you are no longer using at any time.

To use EdgeKV management APIs or the Edge KV CLI, the API credentials need to be created using the Admin role. You can also use a custom role based on the Publisher or Editor roles. For more information refer to the Assign roles and permissions section.

CDN support

EdgeKV is not supported on ​Akamai​ CDNs created to accommodate unique regional or governmental requirements. This limitation currently includes China.

Caching behavior in onClientRequest

EdgeKV data cannot be used to calculate a cacheKey in an EdgeWorkers function. The EdgeWorkers onClientRequest event handler may succeed, but the data purging may fail or result in incorrect behavior.

Timeout during initialization of a namespace using the CLI

A timeout may occur when trying to initialize a namespace through the CLI, and you may receive this error:

ERROR: Error while creating namespace. The EdgeKV service was unable to respond in time. Please retry the request later. [TraceId: undefined]

We recommend that you retry the initialization using a larger timeout value directive with each CLI command, such as, --timeout 2000000. We are actively working to resolve this problem.

Initialization failure

First, make sure you have API credentials for a user at the top level group under your account. If you still get a failure, you can try calling the Initialize EdgeKV API endpoint or CLI command again.

If initialization continues to fail, capture the API response or CLI command output. You'll also need the response from the GET /edgekv/v1/initialize API or the output of the edgekv show status CLI command to help debug the problem. Once you have this information please contact ​Akamai​ support at edgeworkers@akamai.com.

Error message when attempting to initialize a database

If you receive an error indicating that, “The client does not have the grant needed for the request,” your API client is missing the required READ-WRITE access level. For instructions on how to add it, refer to the Get started section in the EdgeKV API documentation.

Issue with option for token create and download CLI commands

The EdgeKV CLI --overwrite option for the token create and download commands does not work when you change the token name associated with a namespace.

As a workaround, you can manually delete the token in question from the edgekv_tokens.js file before using the --save_path option. You can then use the token create and download CLI commands with the --save_path option to update the edgekv_tokens.js file.

"Unexpected Identifier" error when upgrading the EdgeKV CLI

If you receive an error when attempting to upgrade to the latest version of the EdgeKV CLI please check which version of node you have installed on your machine. To do this use the node --version command. As of May 2022, you will need version 14 or higher to use the EdgeKV CLI.

For the latest technical requirements please refer to the EdgeKV CLI documentation.

EdgeKV CP codes and group access

Users within a role need at least Read Access in the group that the EdgeKV CP code belongs to.
Your Akamai account representative can help you move the EdgeKV CP code to a different group if you don't want your EdgeKV user accounts to have access to the current one.

👍

As a best practice, keep your EdgeWorkers and EdgeKV entitlements in the same group to prevent permission errors.

If an API user does not meet these permissions requirements, the following error may appear indicating that the EdgeKV database is not initialized: ERROR: Unable to retrieve EdgeKV token. The EdgeKV database is not initialized.

To resolve this error another user with the required permissions can perform an API or CLI action.

For more information about how to grant access to groups refer to the API user credentials documentation.

📘

EdgeKV also has its own set of Akamai Control Center group membership permissions that apply to namespaces. These permissions let administrators define user access and permissions to namespaces using by tying a namespace to a Control Center access group. For more information see, Manage access to EdgeKV.

Sandbox limitations

The following are known issues that apply to both the EdgeKV CLI and the EdgeKV API when listing and accessing EdgeKV data in Sandbox.

Fixed data retention

All Sandbox data has a fixed retention period of two days regardless of the namespace configuration. This retention period cannot be modified. Sandbox data is intended for short-term testing. If you require data with a longer retention period you can store and access it from the common staging environment instead.

List groups within a namespace is not supported

The sandboxId query string parameter is not currently supported when listing groups within a namespace.

A “400 Bad Request” error is returned if you include the sandboxId parameter. For example, GET /edgekv/v1/networks/staging/namespaces/{namespaceId}/groups?sandboxId={sandboxid} returns the following response.

{
    "additionalDetail": {
        "requestId": "0d0b8c6c96f2acee"
    },
    "detail": "This endpoint does not support Sandbox.",
    "errorCode": "EKV_2000",
    "instance": "/edgeKV/error-instances/0e7da3bd-788e-4312-a226-85457972ade8",
    "status": 400,
    "title": "Bad Request",
    "type": "https://learn.akamai.com"
}

List groups in staging may return some sandbox groups

Calling GET /edgekv/v1/networks/staging/namespaces/{namespaceId}/groups may return some sandbox groups in the form of <groupId>_<sandboxid>. These group names should not be used in the API, CLI, or from an EdgeWorkers function. Instead, for the API or CLI you need to use the <groupId> and specify the sandboxId parameter to access sandbox data. You can also use the appropriate JavaScript object and invoke an access method using only the <groupId>.

http --auth-type edgegrid -a default: GET :/edgekv/v1/networks/staging/namespaces/geotest/groups 

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 73
Content-Type: application/json;charset=utf-8
...

[
	"group1",
	"group2",
	"group2_4d91057d-xxxx-xxxx-xxxx-3a4472699df4"
]

In this example "group2_4d91057d-xxxx-xxxx-xxxx-3a4472699df4" represents the internal sandbox copy of “group2” for sandboxid “4d91057d-xxxx-xxxx-xxxx-3a4472699df4”.