README
¶
tops
Temporal Orchestration Tool for SREs
tops is a Go-based CLI for deploying, operating, and investigating self-hosted Temporal clusters on Linux servers.
The goal is to manage Temporal infrastructure through a declarative configuration instead of a collection of manual commands and deployment scripts.
Goals
- Declarative configuration
- Plan before applying
- Safe operations
- Remote management
- Operational visibility
- Incremental deployments
Architecture
- CLI: Runs on your workstation, reads configuration, plans changes, coordinates operations, and presents results.
- Node helper: Runs on a remote server to execute explicitly requested operations and return results.
Quickstart
tops 0.1 works offline: it checks a fleet repo and compares its environments. It does not touch a node yet.
Install a release, or with Go 1.26 or newer:
go install github.com/2SSK/tops/cmd/tops@latest
Start a fleet repo with its first environment:
mkdir fleet && cd fleet && git init
echo 'environments/*/secrets.env' > .gitignore
tops init lab
Edit environments/lab/cluster.yaml, set the password in environments/lab/secrets.env, then:
tops -e lab validate # every problem, with its file and line
tops knobs cacheTTL # search Temporal's dynamic-config settings
tops knobs history.cacheTTL -e lab # where that key gets its value in lab
tops init staging
tops diff lab staging # exit 2 when promotable values differ
Every command takes --json and has documented exit codes: 0 success, 1 failed, 2 differences to report, 3 refused, 4 invalid input, 5 unhealthy, 130 interrupted.
Temporal 1.31 settings are supported today; 1.30 specs are accepted but validate reports that their catalog is not there yet.
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tops
command
Command tops manages a Temporal cluster over SSH
|
Command tops manages a Temporal cluster over SSH |
|
internal
|
|
|
catalog
Package catalog is the settings catalog of each supported Temporal minor, embedded in the binary: every dynamic-config key with its type, default, roles and apply hint.
|
Package catalog is the settings catalog of each supported Temporal minor, embedded in the binary: every dynamic-config key with its type, default, roles and apply hint. |
|
cli
Package cli defines the tops command
|
Package cli defines the tops command |
|
fleet
Package fleet finds the fleet repo and loads one environment from it.
|
Package fleet finds the fleet repo and loads one environment from it. |
|
helper
Package helper is the node side of tops: it runs as root on a node, reads one request and writes one response.
|
Package helper is the node side of tops: it runs as root on a node, reads one request and writes one response. |
|
secret
Package secret holds values that must never be printed, like the passwords in secrets.env.
|
Package secret holds values that must never be printed, like the passwords in secrets.env. |
|
settings
Package settings reads the fleet's dynamic-config files (base/ and overrides.yaml), checks them against the settings catalog, and merges them per role.
|
Package settings reads the fleet's dynamic-config files (base/ and overrides.yaml), checks them against the settings catalog, and merges them per role. |
|
spec
Package spec loads and validates cluster.yaml.
|
Package spec loads and validates cluster.yaml. |
|
term
Package term renders tops output: errors, symbols, tables and JSON.
|
Package term renders tops output: errors, symbols, tables and JSON. |
|
wire
Package wire holds the types tops and its node helper exchange as JSON.
|
Package wire holds the types tops and its node helper exchange as JSON. |