README
¶
Speedrun
Speedrun helps you control your compute fleet with minimal effort.
Example, stop nginx across 3k machines:
speedrun service stop nginx --target "Labels.role == 'nginx'"
Features:
- stateless
- serverless
- idempotent
- no complex configuration required
- service discovery via native cloud integration (currently Google Cloud only, AWS, Azure and Consul coming up!)
- extensible (plugin system is in the works)
Installation
MacOS, Linux, Windows
Download the precompiled binaries from here: Releases
Usage
Quickstart
On a server:
sudo ./portal --insecure
On your machine:
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/serviceaccount.json
speedrun run whoami --insecure
Architecture
Speedrun
Speedrun is the client. Speedrun is the CLI tool you run on your computer to send commands to your VMs.
Portal
Portal is the agent running on each server you want to send commands to. It will receive commands sent from Speedrun and respond with the outcome details accordingly.
Service Discovery
There is no server component in Speedrun's architecture. Service discovery is performed against native facilities of each supported provider such as GCP, AWS or Consul. This eliminates the need to deploy,maintain and operate a server and all problems that would come with it as a consequence, such as: scalability, failure tolerance, redundancy, agent lifecycle management etc.
sequenceDiagram
Speedrun ->> GCP API: Get list of VMs
GCP API ->> Speedrun: Return list of VMs
Speedrun ->> Speedrun: Filter list of VMs
Speedrun ->> Portals: Send command
Protocols
Communication between Speedrun and Portals is performed via dRPC, a lightweight, drop-in replacement for gRPC. All dRPC interactions travel on top of TLS1.3 and can be mutually authenticated (mTLS).
Language Definition
Speedrun supports a flexible yet simple expression language to filter Service Discovery results (--target), it's based on antonmedv/expr. Full language definition can be found here.
Plugins
Plugins will allow you to add custom commands without altering the source code. This is not implemented yet.
Examples
Stop Nginx on VMs that have a label role with value nginx and a label named project with value someproject
speedrun service stop nginx --target "Labels.role == 'nginx' and Labels.project == 'someproject'"
Run arbitrary shell command on the target machines. Ignore Portal's certificate and connect via private IP address.
speedrun run "ls -la" --target "Labels.env != 'prod'" --insecure --use-private-ip
Use a different config file
speedrun run whoami -c /path/to/config.toml
Configuration
Config samples are located under conf.
Run Portal as a systemd service
Find a sample unit here
Use self signed certificates during testing
In the scripts folder you can find scripts that will help you generate:
- a CA cert/key
- Speedrun cert/key
- Portal cert/key
Run them:
scripts/generate_fake_ca.sh
scripts/generate_portal_cert.sh
scripts/generate_speedrun_cert.sh
This will generate the required key/cert pairs:
ca.crt
ca.key
portal.crt
portal.key
speedrun.crt
speedrun.key
Set the path in the [tls] config block:
Portal:
[tls]
ca = "ca.crt"
cert = "portal.crt"
insecure = false
key = "portal.key"
Speedrun:
[tls]
ca = "ca.crt"
cert = "speedrun.crt"
insecure = false
key = "speedrun.key"
List of built-in Actions
- run: run arbitrary shell commands
- service: control systemd services
- file: perform file operations such as read or tail
- disk: perform storage operations such as listing partitions and available disk space
- ps: fetch process information
- top: fetch or stream high level system stats
- pkg: manage packages via default package manager
- system: host control operations such as reboot, shutdown etc. ...
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Project Status
This project is in a very early stage so expect a lot of breaking changes in the nearest future
Community & Support
Join the Speedrun Slack and ask questions 😃
Directories