Vars Guide

Overview

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.

What is Vars?

Vars is a distributed variable service bundled with the Fugue Client Tools. 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.
Watches
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.

Note

To change the name of the Conductor Vars Table for use with Fugue, see Changing the System Vars DDB Table Prior to Installation and Changing the System Vars DDB Table During Upgrade. By default, this table is called fugue-vars-headless-store.

Warning

When upgrading Fugue from a previous release, if your fugue-vars-headless-store DynamoDB table is larger than 3GB, you will see a message to contact Fugue Support (support@fugue.co) to help you compact the table. This process will ensure you have a successful upgrade.

If you wish to continue the upgrade on your own, you may enter y at the prompt. You may also use the fugue upgrade --force option to bypass the confirmation. However, we recommend that you contact Fugue Support first.

Vars Examples

Vars Tutorial
This tutorial teaches the basics of using Vars and demonstrates its item encryption and watch features.
RDS Password Encryption with Vars
This example demonstrates how to set up an Amazon Relational Database Service (RDS) (in this example, a SQL database) and access that database with an encrypted password.

Usage

vars [--human | --host= | -v, --verbose | --version | -h, --help] <command>

Global Options

The vars executable accepts the following options:

--human
Enable human-readable text logging.
--host=
Specify client port.
-v | --verbose
Enable verbose output/logging.
--version
Show the current version.
-h | --help
Show help text.