awsflock 0.2.0

Simple locking in AWS

AWS flock

flock-like functionality for applications in AWS, using dynamodb as a backend for synchronization.

A CLI tool as simple as the classic flock command.

Use Cases

• Synchronizing multiple automated jobs across workers in AWS
• Writing scripts that only one human operator can be running at a time (e.g. production deployment tools with terraform, CFN, etc)
• Synchronizing jobs in non-AWS systems (e.g. GitHub Actions) using AWS credentials

Usage

Full usage info can be found with

awsflock --help

Create the table in DynamoDB in order to start using awsflock:

awsflock table-create

Acquire a lock, with a 15 minute expiration, and get the lock LEASE_ID:

LEASE_ID="$(awsflock acquire LockFoo --lease-duration '15 minutes')"

Renew the lock, getting back the new LEASE_ID and reducing the expiration window to 5 minutes, specified in seconds:

LEASE_ID="$(awsflock renew LockFoo "$LEASE_ID" --lease-duration '300s')"

Release the lock, so that others may use it:

awsflock release LockFoo "$LEASE_ID"

Attempt to acquire another lock, but don't block and wait for it to be acquired:

LEASE_ID="$(awsflock acquire LockBar --no-wait)"
if [ $? -eq 0 ]; then
  # lock acquired ...
else
  # lock not acquired ...
fi

Behavior / Model

Locks are held for a limited period of time. After that time, if not renewed, the lock expires and another worker may reclaim the lock. While the lock is held, the worker holding it has a "lease" on the lock, proven by a given LEASE_ID. A LEASE_ID can be used to "renew" or "release" a given lock.

awsflock requires a table in DynamoDB to store active locks. By default, the table name is awsflock, but custom names can be used. You must create the table before locks can be used (it will never be created automatically). Locks are identified by name, and those names are unique keys into the awsflock table.

Locks have a limited lifetime (default: 2 hours) if not explicitly released, after which they may be "reclaimed" by anyone trying to acquire that lock.

NOTE: Local clock time is compared against lock expirations to determine whether or not reclamation may be tried. The default reclamation window (5 seconds) is more than sufficient for most use-cases, but assumes that your clocks are synchronized by NTP or a similar protocol. Usage where clocks cannot be trusted may result in incorrect lock reclamations.

When you acquire a lock, you get back a LEASE_ID. The LEASE_ID can then be used to renew the lock or release it. In this way, locks are held by a single owner for a limited period of time, and the LEASE_ID constitutes proof of ownership.

CHANGELOG

0.2.0

• More advanced parsing of durations

0.1.1

• Minor fixup

0.1.0

• Initial release