Getting Started with the Seaplane Coordination Service

The seaplane coordination service allows you to coordinate the activities of the different parts of your Seaplane application that are running all over the world. It is a distributed, reliable key-value store with strong consistency guarantees, accessible using a REST API.

Authentication

To get started, you'll need to set up an account with Seaplane. The examples here rely on Seaplane's platform-wide authorization, so you'll need to use your Seaplane API key to get a per-request token.

# You can get your API key from the Seaplane dashboard.
# It lasts a long time (so don't share it with anyone!)
API_KEY=<TOP SECRET STUFF>

# You'll use your API key to generate a short term access token.
# It will last for about a minute.
curl https://cplane.cloud/token --request POST \
  --header "Authorization: Bearer $API_KEY"

You'll need to use a token any time you call the coordination service.

Base64 encoding

The seaplane coordination service can store any data you'd like up to 1 MB per record. To allow the data to be transported via HTTP, keys and values in the API are url-safe base64 encoded

The default perl install on most Linux and Mac OS machines has built in support for this encoding (as do the standard libraries for most popular programming platforms.)

For convenience in the examples, we'll be using a few shell functions to do the encoding and decoding for us

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

function decode {
    perl -MMIME::Base64=decode_base64url -ne 'print decode_base64url($_),"\n"'
}

Coordination Service Quick Start

The service works by setting and reading keys and values, like a simple database or dictionary data structure. What makes these keys and values useful is:

  • They're very reliable. It takes a lot more than a hard drive crash to lose data once it's been written to the coordination service.
  • Changes to any individual key happen in the same order for all observers.

That means it's a good way to synchronize or communicate between processes in distributed systems - like your containers on the Seaplane platform.

To write a value to the service, PUT the value using the encoded key in your URL

key=$(echo "the key" | encode)
value=$(echo "the value" | encode)
curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}"
    --request PUT
    --data "${value}"

having written to the service, you can read it back with a GET request for the same URL. The result will be a JSON object with base64 encoded member values.

# The value will be returned encoded 
key=$(echo "the key" | encode)
curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}"
    --request GET 

You can also delete records using the key, by sending a DELETE request

key=$(echo "the key" | encode)
curl "https://metadata.cplane.cloud/v1/config/base64:${key}" \
    --header "Authorization: Bearer ${TOKEN}"
    --request DELETE

Did this page help you?