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.
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.
The Conductor must be installed and booted in order to use Vars.
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
sedto update the config file with the key values, then restarts HAProxy when the config file is updated.
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
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 (firstname.lastname@example.org) 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 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.
vars [--human | --host= | -v, --verbose | --version | -h, --help] <command>
vars executable accepts the following options:
- Enable human-readable text logging.
- Specify client port.
- Enable verbose output/logging.
- Show the current version.
- Show help text.
Vars Setup and IAM Policy¶
To get started with Vars, follow these three steps:
- Download and install the Fugue Client Tools, which includes the Vars client.
- Install the Fugue Conductor.
- Start the Vars daemon.
That’s it! Most of the time, this simple process is sufficient for setting up Vars. However, there are a couple situations in which you’ll need to set up the Vars client’s IAM permissions:
- If you plan to launch the Vars client daemon
--profileoption set to an AWS profile in a separate account, ensure the profile is associated with a cross-account IAM role.
- If you’re installing the Vars client on an EC2 instance, make sure the EC2 instance profile contains an IAM role with a policy containing sufficient permissions.
As for Vars’ server-side component, it runs on the Conductor instance. As a result, it has the same administrative access IAM permissions that the Conductor has. The policy is applied during the fugue install process, so you don’t have to do a thing.