Vars Guide


What’s in this guide?

The Vars Guide includes everything you need to know about Vars, Fugue‘s distributed variable service. This guide defines Vars, describes how to use it, and explains how it works. You’ll also find CLI and API references and a tutorial.

What is Vars?

Vars is a distributed variable service bundled with the Fugue client package. It functions as a service registry, service discovery tool, configuration synchronization service, and lock service all in one. You can use Vars in conjunction with Fugue or independently of Fugue.

Unlike other service registry/service discovery tools, Vars requires very little infrastructure overhead. The Vars package has two components: a server-side component that runs on the Fugue Conductor EC2 instance, and a client-side component. Because of its unique architecture and its reliance on AWS services, there aren’t leader elections or complex consensus protocols. Vars is an HTTP-based RESTful API that makes use of DynamoDB, SQS, SNS, and optionally KMS. Key/value pairs saved in Vars are immutable and versioned, and they are stored in DDB.

Vars Features

Vars offers several key features: item encryption, optimistic locking, key expiration, and watches.

Item encryption
Item encryption is handled securely through AWS’s Key Management Service (KMS) and DynamoDB. When invoked, Vars encrypts the desired value using a data encryption key that is then encrypted by a master key in a process known as envelope encryption (also called key wrapping). Your encrypted value and wrapped data encryption key are stored in DynamoDB. Upon retrieval, Vars uses the master key to decrypt the data key, then uses the decrypted data key to decrypt your value.
Optimistic locking
As a lock service, Vars uses optimistic locking for every write, so the first Vars client to successfully write the value is the one to execute the desired task, and all other Vars clients fail with a lock error.
Key expiration
To facilitate its lock service, Vars offers key expiration. You can set a key/value pair’s time to live (TTL) when you execute a Vars write. Key expiration is also useful for any situation in which a key’s value must be intentionally short-lived.
Vars allows you to set a “watch” on a key, which means Vars triggers an arbitrary action whenever that key changes. For example, you can set a watch to echo a warning in your terminal whenever a particular value changes, or to change an environmental variable based on an updated value.

Vars Use Cases

Vars supports a variety of use cases. Here are a few examples:

Synchronizing a server IP address
Vars’ configuration synchronization feature allows it to function as a service registry and service discovery tool. For example, you can use Vars to save a service’s IP address as a key/value pair. When a key/value pair is updated on the server-side component, Vars automatically broadcasts the change to each client-side component, synchronizing the server’s IP address across each your entire fleet of instances.
Encrypting and sharing database connection parameters
Vars can securely manage and distribute shared credentials, such as database connection parameters. For example, to synchronize a fleet of instances to use the same database connection parameters, you can save the credentials as an encrypted key/value pair in Vars, then set an environmental variable on each client to point to the key/value pair. When you export the environmental variable on the client boxes, Vars fetches the encrypted parameters and decrypts them.
Changing and refreshing local config files based on watched values
You can combine watches and shell scripts as “glue” between Vars and other software applications. For example, if you are running HAProxy, you can save a Vars key with HAProxy configuration information and set a watch so that whenever the value changes, Vars executes a shell script that uses sed to update the config file with the key values, then restarts HAProxy when the config file is updated.