put

Usage

vars [global options] put [options] <KEY> <VALUE>

Arguments

<KEY>
Key to be stored; maximum size: 1,024 characters.
<VALUE>
Value to be stored; maximum size: 5GB.

Options

Global options are detailed here.

-e | --encryptkey=
The ID of the AWS Key Management Service (KMS) master key used to encrypt the value. To refer to a KMS key ID by its alias, use -e alias/[ALIAS].
--output=
Output encoding. Available OUTPUT options are plain (default), json, and xml.
-t | --ttl=
Time to live (TTL) in seconds, after which the value will be treated as expired.
-v | --version=
Only perform the update if the specified version of the value matches the current version.
--if-none-match
Only perform the update if the key has never existed.
-f | --file=
Treat the value as a file path and upload the contents to the store.
-h | --help
Show this help message.

Definition

The put command publishes the value of a key to the Vars server, which replicates it to all other Vars clients.

put may optionally give a key a time to live (TTL) in seconds, after which the value expires.

put may optionally encrypt a value with an AWS Key Management Service (KMS) master key.

put also allows conditional updates based on whether the current version of a value matches a specified number and whether a key has never existed before.

Maximum key size is 1,024 characters. Maximum value size is 5 gigabytes, but values of greater than 150 kilobytes will be stored in Amazon S3 rather than DynamoDB. Note: This operation is seamless to the user and does not impact the user’s interaction with Vars.

Note

Some time is required for the updated value to be replicated across instances, so immediate reads may be outdated.

Examples

Storing a value in Vars

To store a key/value pair in Vars, use vars put <KEY> <VALUE>:

vars put mykey myvalue

You’ll see the value echoed to the screen when the operation is complete:

myvalue

Storing a value in Vars from a file

To store a key/value pair from a file in Vars, use vars put -f <KEY> <VALUE>:

vars put -f mykeyfile /home/value_file

You’ll see the full path of the file echoed to the screen when the operation is complete:

/home/value_file

Encrypting key/value pairs, such as database connection parameters

If you want to encrypt a value using a master encryption key (accessible from the IAM dashboard), use the -e or --encryptkey flag with the alias of the encryption key.

For example, to encrypt and database connection parameters locally and share them with another instance in your fleet, you can execute the following, which uses an encryption key with the alias varskey to encrypt a value, secretpassword1234, for the key prod.db.password:

vars put prod.db.password secretpassword1234 -e alias/varskey

On the other instance, execute the following command, which instructs Vars to retrieve the encrypted password, decrypt it, and export it to the environmental variable DB_PASS:

export DB_PASS=$(vars get prod.db.password)

If you’d like to see the encrypted password, navigate to the DynamoDB dashboard in the AWS console and look for it in the table titled fugue-vars-store.

Enabling key expiration

If you want to set a TTL (time to live) on a key, use the -t or --ttl flag.

For example, if you have multiple EC2 instances running but only need one of them to execute a task, you could have all of your instances attempt to write a unique value (IP address, hostname, etc.) to the same key at the same time, with a watch file configured on each instance so the “winning” instance carries out the task upon a successful write.

Because Vars uses optimistic locking, only one write will be recorded. That means the first and only instance to successfully write the value will be the one to execute the desired task, and all other instances fail with a lock error.

Key expiration is desirable in this use case because if a task worker were to go offline before it completed its task, the lock would never be released.

To enable key expiration after one minute on the key taskworker with an environmental variable $ip (for IP address) as the key’s value, execute the following:

vars put --ttl=60 taskworker $ip

After 60 seconds, the taskworker key expires. At that time, if the winning instance has not completed the desired task, you may restart the task worker selection process by running the put command again.

Conditionally updating a key based on its version number

If you want to update a key, but only if its version number matches a specified version number, use the -v or --version flag. For example, the following command stores the key taskworker with the value $ip only if the current version of the taskworker value is version 5:

vars put -v 5 taskworker $ip

If the taskworker value’s version isn’t 5, then the put command fails and returns an error message:

{
  "component": "vars",
  "log_level": "err",
  "message": "Error attempting to update an old version.",
  "timestamp": "2016-07-15T19:46:07.065888"
}

Conditionally updating a key based on whether it’s new

If you want to update a key, but only if it’s never existed before, use the --if-none-match flag. For example, the following command stores the key taskworker with the value $ip only if the key taskworker has never existed before:

vars put --if-none-match taskworker $ip

If the taskworker key currently exists or has existed in the past, then the put command fails and returns an error message:

{
  "component": "vars",
  "log_level": "err",
  "message": "Error attempting to update an old version.",
  "timestamp": "2016-07-19T18:43:05.813515"
}