Working with KV stores

A KV store is a type of container that allows you to store data in the form of key-value pairs for use in high performance reads and writes at the edge. A single KV store can be associated with multiple Compute services in your account. Because KV stores are versionless, the data in them never expires and can be updated at any time after a KV store is created, without requiring you to increment a service's version. Also, because KV stores are stored at the edge, they allow you to offload that data from your origin and keep it closer to your end users.

You can also create and work with KV stores via the API.

Prerequisites

KV Store is only available for Fastly's Compute services, not for Deliver (VCL-based) services.

Limitations and considerations

When creating or making changes to KV stores, keep the following things in mind:

  • KV stores can only be used by Compute services, not Deliver (VCL-based) services.
  • The number of KV stores you can create is limited to your account’s available resources allotment.
  • KV stores support a maximum key size of 1024 bytes in UTF-8 format.
  • KV stores support values submitted using any file type and have a maximum size of 25MB. This maximum can be raised to 100MB upon request. Contact your account manager or sales@fastly.com for more information.
WARNING

Personal information, secrets, or sensitive data should not be included in KV stores or incorporated into edge logic. In addition, we do not maintain version histories of your KV stores. Our Compliance and Law FAQ describes in detail how Fastly handles personal data privacy.

Creating a KV store

Creating a KV store requires you to create at least one key-value pair before you associate it with a service. To create a new KV store and its key-value pairs, follow these steps:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click the KV stores tab.
  3. Click Create a KV store.
  4. In the Name of KV store field, enter a name for the KV store and then click Add.
  5. Click Key-value pairs.
  6. In the Name of key field, enter a name for the first set of key-value pairs associated with your KV store.
  7. Upload the values for your key, clicking Browse for file to navigate to the file on your system using the file picker. Alternatively, drag and drop your key file directly into the drag and drop area below these controls.
  8. Click Add to the right of the key controls.
  9. Click Add item to continue adding additional key-value pairs as necessary.
TIP

By default, the web interface displays only the first 1,000 keys in the store. To view more keys, click the Load more keys button.

Linking KV stores to a service

Once you've added at least one key-value pair to a KV store, you can link it to a service from the Resources tab or from the Service configuration tab for the service.

Linking KV stores from the Resources tab

To link a KV store to a service from the Resources tab:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click Link to services to the right of the store you want to link.

  3. Select the checkbox next to any services you want to link your KV store to and then click Next.

  4. Decide which version of the service to link to. By default, the system will assume you want to clone the most recently active version of your service. You can choose an existing draft version of the service instead by selecting it specifically from the Version menu.

  5. Select one of the following options for linking the store to your service:

    • Link only: links the store to the selected service versions but leaves any cloned or draft versions un-activated so you can activate them at a later time.
    • Link and activate: links the store to the selected service versions and activates those versions at the same time.

    A success message appears once the KV store is linked to the service.

  6. Finally, do one of the following:

    • Click Activate versions to activate any cloned or draft versions of services linked to the KV store.
    • Click Finish to leave the cloned or draft service versions un-activated so you can make additional configuration changes to them and activate them at a later time.

    You can immediately start referencing the KV store in your edge logic.

Linking KV stores from the Service configuration tab

To link a KV store to a service from the Service configuration tab:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain. You can also click Compute services or CDN services to access a list of services by type.
  3. From the Resources options in the sidebar, click KV stores.
  4. From the Link KV Store to service menu, select the KV store you want to link to the service. A success message appears indicating the store is linked to your service.

Once linked, you can immediately start referencing the KV store in your edge logic and activate the service when you’re ready.

Unlinking KV stores

You can unlink a KV store from a service from the Service configuration tab.

To unlink a KV store:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain. You can also click Compute services or CDN services to access a list of services by type.
  3. From the Resources options in the sidebar, click KV stores.
  4. Click Unlink from service next to the KV store you want to unlink from your service.
  5. Click Confirm and unlink. A new, draft version of the service is created.
  6. Activate the service to finalize unlinking the KV store.

Editing a KV store

You can edit the name of a KV store as well as the key-value pairs within the store.

To rename a KV store:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click the KV stores tab.
  3. Click the pencil to the right of the store you want to rename.
  4. Enter a new name for the KV store.
  5. Click Save and then Confirm and rename to continue.
TIP

Be sure to update any custom logic with the new name of the KV store.

To add new key-value pairs to an object store:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click the KV stores tab.
  3. Expand the Key-value pairs section.
  4. Under Key-value pairs, click Add item.
  5. Enter a key name and upload a key file that has the values and then click Add.
  6. Repeat for any additional key-value pairs.

To edit the key-value pairs within a KV store:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click the KV stores tab.
  3. Expand the Key-value pairs section.
  4. Hover your cursor over the entry you want to edit, then click Edit .
  5. Drag and drop your key file that has the values into the drag and drop area to upload your list of keys. Alternatively, click Browse for file to navigate to the file on your system using the file picker.
  6. Click Save.

The changes you make will be immediately applied to your configuration including any deployed service versions associated with the KV store.

Deleting a KV store

You can delete a KV store at any time.

Before deleting a KV store:

  • Unlink the KV store from your services. If the KV store is linked to any service, an error will appear when you try to delete the store.
  • Update any custom logic that references the key-value pairs in the KV store. Deleting a KV store also deletes all key-value pairs within the store.

To delete a KV store:

  1. Log in to the Fastly web interface and click the Resources link.
  2. Click the KV stores tab.
  3. Click trash to the right of the store you want to delete.
  4. Click Confirm and delete.
Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.