Edge Storage

Edge Storage stores key-value data that CDB EdgeCompute applications can read at runtime.

Each store is a named container for key-value pairs. After creating a store, link it to a CDB EdgeCompute application before the application can access its data — linking instructions are in Managing applications.

Data is replicated across CDB's edge network, so reads are served from a local copy at the edge location handling each request.

Create a store

Creating a store uses a two-step wizard. The first step sets the store name; the second step adds key-value pairs before saving.

To start, open the CDB Technical Web Portal, navigate to CDB EdgeCompute, and select Edge Storage in the sidebar.

1. Click Add Edge Storage in the top-right corner.

2. Enter a name and optionally a description.

3. Click Create Edge Storage to proceed to the second step.

4. In the second step, add key-value pairs using the Insert item button, or skip this step — pairs can be added later by opening the store from the list.

5. Click Save Edge Storage.

The store appears in the Edge Storage list.

Insert key-value pairs

Key-value pairs are added through the Insert item panel inside the store view. Pairs can be added during the creation wizard (step 2) or at any time by clicking the store name in the Edge Storage list to open it.

Add a pair manually

Click Insert item and select KV pair. In the panel that opens, enter the key and value. Click + Add value to add another row. Click Save to apply the changes.

Keys are limited to 256 bytes.

Upload a value from a file

To load a value from a file instead of typing it, click the upload icon in the value row. Text and binary files are supported — images, fonts, and similar assets. The maximum file size is 1 MB. After uploading, the portal displays a hash of the file content rather than the original filename.

Set an expiration date

To assign an expiration to a value, click the expiry icon in the value row and select a date and time. After that point, the value stops being returned to applications. It may remain visible in the portal briefly after expiration.

Edit a key-value pair

Once pairs are in a store, individual values can be updated at any time. Clicking a store name in the Edge Storage list opens the Edit Edge Storage page where all pairs are listed. To edit a pair, click the three-dot icon next to it, select Edit, update the value or expiration date, then click Save.

ℹ️

Additional pairs can be inserted from the edit view. Submitting a key that already exists in the store overwrites its current value.

Delete key-value pairs

To remove outdated or incorrect data, pairs can be deleted individually or in bulk. Open the store by clicking its name in the Edge Storage list to access both options.

To delete a single pair, click the three-dot icon next to it, select Delete, and confirm.

To delete multiple pairs, select the checkboxes in the first column of the table, click Group actions, and select Delete all.

BYOD: Bring Your Own Database

BYOD connects a CDB EdgeCompute store to an external key-value database instead of CDB's hosted storage. Applications access a BYOD store through the same JavaScript SDK or Rust SDK as a regular store — no code changes required.

Any store implementing the Redis protocol is supported: Redis, Apache Kvrocks, and other Redis-compatible key-value stores.

The external store must be publicly accessible. CDB's edge nodes connect to it over the network on each request.

Hosted Edge Storage vs BYOD

With hosted Edge Storage, data lives at every edge location globally and reads are served locally — latency is typically in the single-digit milliseconds. With BYOD, each read is a live query to the external database, so response time depends on the network distance between the edge location and the database host.

BYOD is a practical choice for development, testing, or workloads where read speed is not critical. For latency-sensitive production workloads, hosted Edge Storage is recommended.

Supported URL schemes:

• redis:// — standard Redis protocol
• rediss:// — Redis protocol over TLS

URL format: redis://:password@host:port/db-index or redis://username:password@host:port/db-index

Create a BYOD store

Follow steps 1–3 from Create a store, then:

4. Select the BYOD: Bring Your Own Database checkbox. Two additional fields appear:

   • URL — the connection URL for the Redis-compatible store. For example: redis://:mypassword@redis.example.com:6379/0
   • Prefix — a string prepended to every key when CDB EdgeCompute reads or writes the store. For example, with prefix app:prod:, a read for key greeting retrieves app:prod:greeting from the external database. Use a prefix to namespace application data within a shared instance. Leave blank if no namespacing is needed.

5. Click Create Edge Storage to validate the connection and create the store.

ℹ️

CDB validates the connection to the external store when clicking Create Edge Storage. If the connection cannot be established — for example, because the host is unreachable, the port is blocked, or the credentials are wrong — the store is not created and an error message is displayed. Verify that the store is publicly accessible and the URL is correct, then try again.

⚠️

A store cannot be converted between BYOD and hosted storage after creation. The store type is permanent.

Link a BYOD store to an application

After creation, link the BYOD store to a CDB EdgeCompute application using the same process as a regular store — instructions are in Managing applications. Once linked, the application accesses the BYOD store through the standard SDK API. The prefix is applied transparently and the application code does not need to know whether the store is BYOD or hosted.

Automate KV store management using the Python SDK or Go SDK for store-level operations, while key-value data operations require direct HTTP calls to the CDB EdgeCompute REST API.

ℹ️

An API token is required. Retrieve the store ID from the response when creating a store or from the list endpoint.

export GCORE_API_KEY="{YOUR_API_KEY}"
export STORE_ID="{YOUR_STORE_ID}"

Create a store

A store must exist before key-value pairs can be written to it. The response includes the store ID used in all subsequent requests.

import os
from gcore import CDB

client = CDB(api_key=os.environ["GCORE_API_KEY"])

kv_store = client.edgecompute.kv_stores.create(
    name="my-store",
    comment="Optional description",
)
print(kv_store.name)

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/edgecompute"
    "github.com/G-Core/gcore-go/option"
)

func main() {
    client := gcore.NewClient(
        option.WithAPIKey(os.Getenv("GCORE_API_KEY")),
    )
    kvStore, err := client.Fastedge.KvStores.New(context.TODO(), edgecompute.KvStoreNewParams{
        KvStore: edgecompute.KvStoreParam{
            Name:    "my-store",
            Comment: "Optional description",
        },
    })
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("created store: %s\n", kvStore.Name)
}

curl -X POST "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-store", "comment": "Optional description"}'

The API returns the new store ID:

{
  "id": 130,
  "name": "my-store",
  "comment": "Optional description",
  "app_count": 0,
  "size": 0
}

Save the id value — it is required for all data operations.

To create a BYOD store backed by an external Redis-compatible database, add the byod object with the connection URL and an optional key prefix:

curl -X POST "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-byod-store",
    "byod": {
      "url": "redis://:mypassword@redis.example.com:6379/0",
      "prefix": "app:prod:"
    }
  }'

CDB validates the connection at creation time and returns an error if the external store is unreachable. The store type cannot be changed after creation.

Insert or update key-value pairs

Use PUT /docs/edgecompute/v1/kv/{store_id}/data to write or overwrite key-value pairs. Each entry in the request array requires an op field — use "add" to insert or overwrite a key.

curl -X PUT "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv/$STORE_ID/data" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "add",
      "key": "greeting",
      "datatype": "kv",
      "payload": {
        "encoding": "plain",
        "value": "Hello from CDB EdgeCompute!"
      }
    },
    {
      "op": "add",
      "key": "color",
      "datatype": "kv",
      "payload": {
        "encoding": "plain",
        "value": "blue"
      }
    }
  ]'

The API returns write statistics:

{
  "write_count": 2,
  "del_count": 0,
  "write_size": 37,
  "store_size": 37,
  "revision": 577
}

To store binary content, set "encoding": "base64" and provide the Base64-encoded value instead of plain text. The key length limit is 256 bytes.

List key-value pairs

Retrieve all pairs in a store with GET /docs/edgecompute/v1/kv/{store_id}/data. Use the limit and offset query parameters for pagination.

curl "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv/$STORE_ID/data" \
  -H "Authorization: APIKey $GCORE_API_KEY"

The API returns:

{
  "count": 2,
  "entries": [
    {
      "key": "color",
      "datatype": "kv",
      "payload": { "encoding": "plain", "value": "blue" }
    },
    {
      "key": "greeting",
      "datatype": "kv",
      "payload": { "encoding": "plain", "value": "Hello from CDB EdgeCompute!" }
    }
  ]
}

To retrieve a single key, append the key name to the path: GET /docs/edgecompute/v1/kv/{store_id}/data/{key}.

Delete key-value pairs

Use the same PUT /docs/edgecompute/v1/kv/{store_id}/data endpoint with "op": "del_key" to delete one or more keys. Multiple keys can be deleted in a single request.

curl -X PUT "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv/$STORE_ID/data" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"op": "del_key", "key": "color", "datatype": "kv"}
  ]'

The API returns:

{
  "del_count": 1,
  "write_count": 0,
  "write_size": 0,
  "store_size": 28,
  "revision": 578
}

Delete a store

Deleting a store permanently removes it and all its data. This action cannot be undone.

import os
from gcore import CDB

client = CDB(api_key=os.environ["GCORE_API_KEY"])

store_id = 130  # replace with the actual store ID
client.edgecompute.kv_stores.delete(store_id)

import (
    "context"
    "os"

    "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/option"
)

client := gcore.NewClient(option.WithAPIKey(os.Getenv("GCORE_API_KEY")))
err := client.Fastedge.KvStores.Delete(context.TODO(), 130) // replace with actual store ID
if err != nil {
    panic(err.Error())
}

curl -X DELETE "https://api.cdb-staging.cdn.orange.com/edgecompute/v1/kv/$STORE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY"

Returns HTTP 204 with no body on success. Returns HTTP 409 if the store is still linked to one or more applications — unlink the store from all applications before deleting.