Public | Automated Build

Last pushed: 2 years ago
Short Description
Gestalt sits in front of your K/V stores and enforces schemas.
Full Description

Gestalt

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

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->

Table of Contents

<!-- markdown-toc end -->

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.

Docker Pull Command
Owner
asteris
Source Repository

Comments (0)