To ensure your usage of EdgeKV is successful, it's worth spending some time considering the design of your data model. Let's start by reviewing a logical diagram of the EdgeKV data model.

Item

The root element of the data model is a key-value pair which provides:

• A key (string) that is a pointer to a value
• A value (can be string or JSON format)

Each key-value pair is called an Item. You can organize Items into a collection called a Group.

Group

Groups are logical containers for Items, and you can create an unlimited number of groups in EdgeKV. Groups are typically created by individual developers or development teams to:

• Organize similar data within a namespace
• Ensure that a set of related keys can be retrieved together
• Avoid key potential name collision

👍

In EdgeKV a group is a container for the items stored in your database.

This is different from Akamai Control Center permission groups. Every Akamai​ contract includes at least one permission group to help you organize your objects and resources. Permission groups are also the primary mechanism for allowing or blocking access to those objects. To learn more about Akamai Control Center permission groups, refer to the About the access control model in the Identity and Access Management documentation.

Groups cannot be manually created and deleted. They are automatically created or destroyed on demand when items are added and deleted from the group.

Groups subsequently roll up to a Namespace object.

Namespace

Namespaces, while also a logical container of data, are a scarce resource in EdgeKV, and should be used for groupings that are more durable over time. A good example of a namespace is “all the KV data for the EMEA business unit.” Namespaces provide:

• Logical separation of data within an organization.
• The ability to reuse group/item key names between different projects or divisions without having to worry about potential name collisions.
• The ability to specify the storage location for data within the namespace using the geoLocation parameter.
• Lets administrators define user access and permissions to namespaces using Akamai Control Center group membership. For more information see, Manage access to EdgeKV.

The geoLocation parameter helps to optimize performance by storing data where most or all of your users are located. By default, the geoLocation is set to US (United States). The available geoLocations on the production network also include EU (Europe), JP (Japan), and GLOBAL. The GLOBAL location automatically replicates data to US, EU, and JP storage locations. If you use the GLOBAL location, reads are faster but write operations are slightly slower.

👍

The geoLocation parameter defaults to US on the staging network. Setting it to a different geoLocation on the staging network is not supported.

To change the geoLocation on the production network you need to create a new namespace with the new geoLocation and copy the data to the new namespace. Once complete, you can delete the old namespace. Use caution when deleting a namespace. When you delete a namespace all of the content within the namespace is also deleted. At the moment you can only use the EdgeKV API to specify the geoLocation.

Data written to the namespace is replicated across several key locations within the specified geoLocation. For example, if US is the specified geoLocation, data is replicated across locations in the Eastern U.S., Western U.S., and other locations. When data is requested, and it's not available on the edge server making the request (a cold hit), it is requested from the closest replicated location within the specified namespace geoLocation.

Account

Finally, the Account layer is the connection to your company’s existing account in ​Akamai Control Center​. In order to use EdgeKV, you must be a registered user under your Akamai corporate account. Once EdgeKV is provisioned on contract, you may freely access the product as a registered user within the account. You can find detailed instructions for managing users, roles, and permissions at Akamai in the Identity and Access Management online help.

Eventual consistency

EdgeKV uses what is known in distributed computing as an eventual consistency model to perform writes and updates. This model achieves high availability with low read latency by propagating data writes globally. The period of time it takes the system to distribute data globally is called the “inconsistency window.”

Inconsistency window

During the inconsistency window, if a read operation is attempted immediately after a write operation, it can return stale data until all nodes are updated. If you perform a read operation after the inconsistency window expires, the response will return the latest data. This should occur within 10 seconds, but can vary depending on network conditions.

The inconsistency window also applies to an EdgeWorker that writes data into EdgeKV. For example, a read operation after a write from EdgeKV is not guaranteed to return the written value until the inconsistency window expires.

👍

Ensure that you take the inconsistency window into account when writing JavaScript code that uses EdgeKV.

EdgeKV API

EdgeKV data is accessible directly from EdgeWorkers or via administrative APIs. To access data from within an EdgeWorker, you must use the JavaScript helper library provided by Akamai. This library uses an EdgeWorkers HTTP “sub-request” within an EdgeWorkers event handler to access EdgeKV data.

For more information see the Helper library.

🚧

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.