gestalt

Gestalt

Gestalt sits in front of your K/V stores and enforces schemas.

Table of Contents

• Gestalt
  • Versioning
  • Deploying Gestalt
    • Running a Server
    • Using the client
  • Basic Workflow
    • Define a Schema
    • Submit the Schema to Gestalt
    • Use the Schema
  • License

Versioning

Gestalt is versioned with semver and reckons versions as BREAKING.FEATURE.FIX. In other words, the 1.x.x series will contain no breaking API changes to input and output (except in the case of bug fixes). You can always find the most recent version on the Github releases page. You can also pull matching images from the Docker hub.

With regards to the stability guarantees, we will prefer to take the design document as the source of truth, and consider it a bug if the implementation does not match in any way.

Deploying Gestalt

Gestalt is shipped as a single binary that can be both a client and a server. To see the commands available, run gestalt.

Running a Server

You'll need the source and credential information for any K/V stores you want to control with Gestalt. In this example, we'll use the Consul backend by writing the following to gestalt.toml:

schemaBackend="dev"
defaultBackend="dev"

[[backend]]
type="consul"
name="dev"
prefix="config"
endpoints=["127.0.0.1:8500"]

This means that on startup, there will be a store named "dev", whose keys will be rooted at /dev. Start the server with gestalt server --config=gestalt.toml (there's a default configuration for you to get started with at gestalt.sample.toml)

Using the client

See the generated documentation at docs/cli

Basic Workflow

The basic workflow for using Gestalt should be quite simple. You need to:

1. Define a Schema
2. Submit the schema to Gestalt
3. Use the Schema

Define a Schema

Gestalt uses a JSON format to specify schemas. Let's specify the configuration for a simple app with some feature flags.

{
    "name": "sample-app",
    "backend": "dev",
    "fields": [
        {"name": "email-host", "type": "string", "required": true},
        {"name": "features/an-amazing-feature", "type": "boolean", "default": false}
    ]
}

(this sample is also available at sample-schema.json)

In this (admittedly simplified) schema, we have two keys: email-host, which is required, and an-amazing-feature, a boolean which defaults to false. These keys will end up in the store at the following locations:

• email-host: /dev/sample-app/email-host
• an-amazing-feature: /dev/sample-app/features/an-amazing-feature

If you want to explicitly set the root of your keys, you can set the root value on a key. Otherwise, a path prefix will be constructed with the backend's prefix and the schema name.

Note: you can define fields that are not required and have no default, but that will result in the keys not being present in the store. Be aware of this condition when reading keys back out.

Submit the Schema to Gestalt

After you have a server running, you can use the gestalt CLI tool to submit the schema:

$ gestalt schema submit sample-schema.json --host=localhost:3000
{ response json elided }

This command will set any defaults set in your schema. Use the same command to update an existing schema. If you don't have access to the gestalt tool, you can also use cURL:

$ curl -X POST -d @sample-schema.json -H "Content-Type: application/json" http://localhost:3000/v1/schemas
{ response json elided }

Once you have the schema submitted, you can also use gestalt to set the values:

$ gestalt value write sample-app email-host 1.2.3.4 --host=localhost:3000

Or the corresponding cURL:

$ curl -X PUT -d '"1.2.3.4"' -H "Content-Type: application/json" http://localhost:3000/v1/schemas/sample-app/values/email-host
{ response json elided }

Use the Schema

Once you have values written to your K/V store through Gestalt, you can use them with the tools you usually would, but with the added assurance that anytime you set a value through Gestalt, it will be the right type in the K/V store. You can also read values through Gestalt directly (see gestalt read), but your K/V store will probably scale to read-heavy workloads much better and have built-in tools for updates (see consul-template for Consul or confd for etcd).

License

Gestalt is licensed under the Apache 2.0 license.