Getting Started with the Metadata Key-Value Store

Available through: CLI, Python SDK, Rust SDK, API

The Metadata KVS supports 4 primary operations set, get, update, and delete.

Setting a key-value pair

You can set a key-value pair through any of the available interfaces by supplying it with a key and a value. For more information see setting a key-value pair.

CLI

seaplane metadata set <KEY> <VALUE>

For larger values such as public keys, large text files, or blobs of data you can use @- to load values from STDIN.

seaplane metadata set <key> @- < <file>

Alternatively, you can use @<path/to/my/file> to directly load values from a file.

seaplane metadata set <key> @<path/to/my/file>

cURL

# function to base64 encode the key and value
function encode {
    perl -MMIME::Base64=encode_base64url -ne 'print encode_base64url($_),"\n"' 
}

# base64 encode key and value
key=$(printf "<KEY>" | encode)
value=$(printf "<VALUE>" | encode)

# set key value pair
curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}" \
    --request PUT \
    --data "${value}"

Python

from seaplanekit import sea
from seaplanekit.model import KeyValue

# set a key-value pair
sea.metadata.set(
  key_value=KeyValue(b"<KEY>", b"<VALUE>")
)

Retrieving a key-value pair

You can retrieve a key-value pair through any of the available interfaces by supplying it with a key. For more information, see get a key-value pair.

CLI

Keys and values are sent to the API base64 encoded. If you have values that can be printed to a terminal safely, use the --decode or -D flag to automatically decode your key-value pair.

seaplane metadata get <KEY> --decode

cURL

# function to base64 encode the key
function encode {
    perl -MMIME::Base64=encode_base64url -ne 'print encode_base64url($_),"\n"' 
}

# function to base64 decode the returned key value pair
function decode {
    perl -MMIME::Base64=decode_base64url -ne 'print decode_base64url($_),"\n"'
}

# base64 encode key
key=$(printf "<KEY>" | encode)

# request key-value pair
result=$(curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}" \
    --request GET)

# decode the result 
echo $result | jq .value | decode

Python

from seaplanekit import sea
from seaplanekit.model import Key

# get key-value pair
sea.metadata.get(key=Key(b'<KEY>'))

Deleting a key-value pair

Deleting a key-value pair permanently removes it from the coordination service. All key-value pairs are strongly consistent and deployed on multiple cloud services to survive outages and data loss. However, Seaplane does not keep a record of deleted key-value pairs. Executing a delete query on the Metadata KVS permanently removes the key-value pair.

For more information see, deleting a key-value pair.

CLI

seaplane metadata delete <KEY>

cURL

# function to base64 encode the key
function encode {
    perl -MMIME::Base64=encode_base64url -ne 'print encode_base64url($_),"\n"' 
}

# base64 encode key
key=$(printf "<KEY>" | encode)

# delete a key-value pair
curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}" \
    --request DELETE

Python

from seaplanekit import sea
from seaplanekit.model import Key

# get key-value pair
sea.metadata.delete(key=Key(b'<KEY>'))

Working with the command line interface (CLI)