fleeting

fleeting is a command-line utility that launches an ephemeral VM instance with Docker Engine (dockerd) in your cloud provider account and configures a docker context so you can use the Docker CLI (docker) against it. The instance will automatically terminate once fleeting exits. It is aimed at running one-off tasks, for example image builds or test runs during CI.

% fleeting ec2 docker run debian:bookworm echo hello world
[... progress omitted ...]
hello world

Priorities are:

1. Security: Ephemeral keys are created automatically for every VM.
2. Cost control: The VM instance will auto-terminate unless fleeting sends keepalives.
3. Performance: On AWS EC2, a docker host is typically ready in 30-60 seconds.

Installation

fleeting is distributed as a single binary and available for Linux and macOS.

To install on Linux:

curl -fsSL -o fleeting.gz https://github.com/jakajancar/fleeting/releases/latest/download/fleeting-$(uname -m)-unknown-linux-musl.gz
gunzip fleeting.gz
chmod +x fleeting
mv fleeting /usr/local/bin

Windows builds are also available, but currently untested. Feedback and contributions welcome.

Usage

General

The simplest way to "docker run" or "docker build" in the cloud

Usage: fleeting <PROVIDER> [OPTIONS] [COMMAND]...

Run a single docker command on an ephemeral host:

    fleeting ec2 docker run debian:bookworm echo hello world

Run multiple commands on the same ephemeral host:

    fleeting ec2 --while $$ --context-name greeter
    docker --context greeter run debian:bookworm echo hello world
    docker --context greeter run debian:bookworm echo hello again

Providers:
  ec2        AWS Elastic Compute Cloud
  gce        Google Compute Engine
  multipass  Canonical Multipass (local)

Options:
  -h, --help
          Print help (see a summary with '-h')

Task (mutually exclusive):
      --while <PID>
          Keep the VM/Docker context alive in background while PID is running.
          
          When started with '--while', fleeting does the following:
          
          1. Starts a detached worker in background and prints its PID to stdout
          so it can be captured (VM_PID=$(fleeting ...)) and killed explicitly,
          if desired.
          
          2. Waits for the worker to finish launching a Docker context and
          exits. The exit code is 0 is the VM started successfully or 1 if not.
          This ensures the following commands have a fully-functioning Docker
          context.
          
          3. The worker monitors PID and exits when it is no longer running.
          Consider using $$, $PPID or 1 as PID.

  [COMMAND]...
          The subprocess to run

Logging options:
  -q, --quiet
          Output only warnings and errors, no progress

  -v, --verbose
          Output additional debugging information

      --log-file <PATH>
          Log file for the background worker.
          
          Applicable only when using '--while'. Helps debugging docker context
          failures after the foreground launcher has exited.

VM/Docker options:
      --context-name <NAME>
          Name of the ephemeral docker context [default: fleeting-<pid>]

      --dockerd-version <SELECTOR>
          Docker version to install on server, e.g. '=1.2.3' or '^1.2.3'
          
          [default: *]

AWS Elastic Compute Cloud

Usage: fleeting ec2 [OPTIONS] [COMMAND]...

Authentication:
  - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
  - Shared config (~/.aws/config, ~/.aws/credentials)
  - Web Identity Tokens
  - ECS (IAM Roles for Tasks) & General HTTP credentials
  - EC2 IMDSv2

More info:
https://docs.rs/aws-config/1.5.5/aws_config/default_provider/credentials/struct.DefaultCredentialsChain.html

Options:
      --region <REGION>
          [default: $AWS[_DEFAULT]_REGION > profile > EC2 IMDSv2 > us-east-1]

      --instance-type <INSTANCE_TYPE>
          [default: t4g.nano]

      --disk <DISK>
          Disk size, in GiBs

Google Compute Engine

Usage: fleeting gce [OPTIONS] [COMMAND]...

Authentication:
  - GOOGLE_APPLICATION_CREDENTIALS (pointing to JSON file)
  - gcloud auth application-default login
  - Metadata server, if running on GCE

Setup:
  - Create a project
  - Enable the Compute Engine API for it
  - Create a service account and download credentials JSON

Limitations:
While GCE instances will automatically stop, they will not be automatically
deleted. fleeting collects garbage at the beginning of the run, but you will
be left with a small number of stopped instances and will continue to pay for
their associated disks. Hopefully, this will be resolved in the future with
termination_time / max_run_duration, once GCE client libraries support it.

Options:
      --project <PROJECT>
          Project in which to create instances [required]

      --zone <ZONE>
          [default: us-central1-a]

      --machine-type <MACHINE_TYPE>
          [default: e2-micro]

      --disk <DISK>
          Disk size, in GiBs

Canonical Multipass (local)

Usage: fleeting multipass [OPTIONS] [COMMAND]...

This provider is primarily intended for developing and testing fleeting
itself. To get started, install multipass as described on:

    https://multipass.run/install

Options:
      --cpus <CPUS>
          CPUs

      --memory <MEMORY>
          Memory, in GBs

      --disk <DISK>
          Disk size, in GiBs

License

Licensed under the MIT license.