armada

module
v0.1.0-alpha.34 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0

README

Armada logo

Armada

Turn a few Linux machines into a container platform.
Apps with HTTPS, rolling updates, autoscaling, jobs, and volumes, on machines you already have.

CI Release Go version

Quickstart · Documentation · Guides · CLI reference · Spec reference · Releases


[!NOTE] Armada is in alpha. It is tested end to end on real machines before every release, but specs, flags, and the state format may still change between releases.

In one minute

# On each machine: install
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh

# On the first machine: create the cluster
sudo armadad init
sudo systemctl enable --now armada-server
armada cluster set --acme-email you@example.com --root-domain apps.example.com

# Deploy an app: two replicas behind HTTPS
armada app create web --image traefik/whoami:v1.10 --port 80 --ingress external --min 2 --wait
curl https://web.apps.example.com      # answers with the replica's name and the request

Ship a new version, watch it roll out, and go back if you need to:

armada app update web --image traefik/whoami:v1.11 --wait
armada app rollback web                # back to v1.10

Every example works as written: traefik/whoami answers on port 80 with who it is and what it received. Put your own image and port in its place. Keep the app as a file in git and change it from there:

# web.yaml, from: armada app show web -o yaml
name: web
image: traefik/whoami:v1.11
ingress:
  type: external
  port: 80
env:
  - name: WHOAMI_NAME
    value: web
scale:
  min: 2
  max: 10
  rules:
    - type: http
      concurrent: 50
probes:
  readiness:
    path: /health
armada app update web --file web.yaml --diff   # what would change
armada app update web --file web.yaml --wait

Install

The same script installs Armada everywhere. It verifies what it downloads and installs or upgrades only: it never sets a machine up by itself.

Where What gets installed Command
A Linux machine of the cluster armadad (runs the machine) and the armada client curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh
Your Linux laptop, a CI runner, any Linux machine that only manages the cluster The armada client only curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo ARMADA_CLIENT_ONLY=1 sh
macOS (Intel or Apple silicon) The armada client only (always on macOS) curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh

Without root, install the client into your home directory instead:

curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | ARMADA_CLIENT_ONLY=1 ARMADA_PREFIX="$HOME/.local" sh

ARMADA_VERSION=v0.1.0-alpha.6 pins a version. The client then needs a certificate of your own and a way to reach the control plane's private address (a VPN or an SSH tunnel): see Use armada from your own computer.

Why Armada

  • Small and complete. armadad runs on every machine and brings its own container runtime, state store, and proxy. armada is the client, for Linux and macOS, and needs no root.
  • Safe by default. HTTPS with automatic certificates, rolling updates that send traffic only to ready replicas, drained shutdowns, confined containers, encrypted secrets, and mTLS between every component.
  • Grows with you. Start on one machine. Add nodes with a one-time token, and two more servers for a control plane that survives losing one.
  • Everything is a spec. Apps and jobs are YAML files you keep in git. armada app show -o yaml exports what runs, and --diff shows a change before it happens.

Features

Deploy Rolling updates, rollback, revisions pinned to image digests, traffic splitting for canaries and previews
Traffic HTTPS on every node, custom domains, internal services by name (http://<app>, <app>.internal), internal TCP for databases, IP allow and deny lists, CORS, sticky sessions
Scale Autoscaling on requests, CPU, memory, queue length, or a schedule; scale to zero and back on the next request
Run Jobs and cron jobs, jobs started by a queue, init containers, sidecars, exec into replicas, logs with a searchable history, sent to Loki or OTLP
Data Volumes, scheduled encrypted backups to an S3-compatible bucket, failover to another node, NFS exports
Operate Highly available control plane, self-healing, placement by labels, spaces, users and roles, events, alerts to Slack, Discord, Telegram, or email, Prometheus metrics, verified upgrades

Read the full feature list.

Learn

Quickstart From empty machines to an app on HTTPS
Concepts Apps, revisions, replicas, nodes, spaces: how Armada thinks
Guides Complete recipes: a web app, a database, workers, cron jobs, canaries, CI/CD, and more
CLI reference Every armada and armadad command and flag
Spec reference Every field of an app or job spec
Operations guide Running a cluster day to day: upgrades, backups, nodes, networking, monitoring
Security The threat model, and how to report a vulnerability

Requirements

  • Linux machines (amd64 or arm64): cloud instances, VMs, or bare metal, with a private network between them and systemd.
  • A domain whose DNS you control, for HTTPS.
  • The armada client runs on Linux and macOS.

Armada is tested on real machines before each release.

Contributing

Bug reports, ideas, and pull requests are welcome. CONTRIBUTING.md explains how to build Armada and run its tests, and the architecture decisions explain why it works the way it does.

License

Apache License 2.0: free to use, change, and sell, also commercially. Armada's dependencies and the container runtime it embeds are under licenses that allow the same; THIRD_PARTY_NOTICES.md lists them and what passing Armada on requires.

Directories

Path Synopsis
api
cmd
armada command
Command armada is the client: it manages apps on an Armada cluster through the control plane's API.
Command armada is the client: it manages apps on an Armada cluster through the control plane's API.
armadad command
Command armadad runs on every machine of an Armada cluster: the control plane, the node agent, and the embedded container runtime.
Command armadad runs on every machine of an Armada cluster: the control plane, the node agent, and the embedded container runtime.
internal
agent
Package agent runs on every node: it receives the desired set of replicas from the server and reconciles local containers against it.
Package agent runs on every node: it receives the desired set of replicas from the server and reconciles local containers against it.
alert
Package alert sends notices about cluster events to people (ADR 0045): a JSON webhook, Slack, Discord, Telegram, or email over SMTP.
Package alert sends notices about cluster events to people (ADR 0045): a JSON webhook, Slack, Discord, Telegram, or email over SMTP.
backup
Package backup creates and restores archives of a control plane: a snapshot of its etcd keyspace, the secrets master key, the cluster CA, the server certificate, ACME certificates, and the embedded agent's identity.
Package backup creates and restores archives of a control plane: a snapshot of its etcd keyspace, the secrets master key, the cluster CA, the server certificate, ACME certificates, and the embedded agent's identity.
certs
Package certs obtains and renews TLS certificates on the control plane with ACME (certmagic).
Package certs obtains and renews TLS certificates on the control plane with ACME (certmagic).
cli
Package cli wires the armada command tree: the client that talks to the control plane.
Package cli wires the armada command tree: the client that talks to the control plane.
clidoc
Package clidoc writes the command line reference (docs/cli) from the commands themselves, so it never drifts from them.
Package clidoc writes the command line reference (docs/cli) from the commands themselves, so it never drifts from them.
clientconfig
Package clientconfig loads and stores the CLI's credentials (~/.armada/config) and dials the control plane with them.
Package clientconfig loads and stores the CLI's credentials (~/.armada/config) and dials the control plane with them.
clusternet
Package clusternet routes the cluster network's node subnets between nodes (ADR 0025).
Package clusternet routes the cluster network's node subnets between nodes (ADR 0025).
conntrack
Package conntrack reads and raises the limit of the kernel's connection tracking table on a node (ADR 0025).
Package conntrack reads and raises the limit of the kernel's connection tracking table on a node (ADR 0025).
daemon
Package daemon wires the armadad command tree: the services that run on every machine (control plane, agent, embedded runtime) and the commands that set a machine up or inspect it as root.
Package daemon wires the armadad command tree: the services that run on every machine (control plane, agent, embedded runtime) and the commands that set a machine up or inspect it as root.
dnsserver
Package dnsserver is the node-local resolver for app containers.
Package dnsserver is the node-local resolver for app containers.
etcd
Package etcd runs the embedded etcd member that holds the control plane's state, and connects clients to it.
Package etcd runs the embedded etcd member that holds the control plane's state, and connects clients to it.
etcd/etcdtest
Package etcdtest starts embedded etcd members for tests on loopback ports picked at run time.
Package etcdtest starts embedded etcd members for tests on loopback ports picked at run time.
fsutil
Package fsutil writes and reads sensitive files with strict permissions.
Package fsutil writes and reads sensitive files with strict permissions.
logexport
Package logexport sends app output to a log store outside the cluster (ADR 0044): a Loki push endpoint or an OTLP/HTTP logs endpoint, both as JSON, gzipped.
Package logexport sends app output to a log store outside the cluster (ADR 0044): a Loki push endpoint or an OTLP/HTTP logs endpoint, both as JSON, gzipped.
netutil
Package netutil enforces that internal services only listen on private network addresses.
Package netutil enforces that internal services only listen on private network addresses.
pki
Package pki implements the cluster's internal certificate authority and the mTLS configuration used between the CLI, the server, and agents.
Package pki implements the cluster's internal certificate authority and the mTLS configuration used between the CLI, the server, and agents.
proxy
Package proxy defines the ingress configuration pushed to every node and the Driver interface implemented by proxy backends (HAProxy in v0.1, Nginx planned for v0.2).
Package proxy defines the ingress configuration pushed to every node and the Driver interface implemented by proxy backends (HAProxy in v0.1, Nginx planned for v0.2).
proxy/fake
Package fake provides an in-memory proxy.Driver for tests.
Package fake provides an in-memory proxy.Driver for tests.
proxy/haproxy
Package haproxy implements proxy.Driver with HAProxy running as an Armada-managed system container.
Package haproxy implements proxy.Driver with HAProxy running as an Armada-managed system container.
queuelen
Package queuelen reads the length of a Redis list or a RabbitMQ queue for queue autoscaling rules (ADR 0034).
Package queuelen reads the length of a Redis list or a RabbitMQ queue for queue autoscaling rules (ADR 0034).
release
Package release finds Armada's latest release and compares versions (ADR 0030).
Package release finds Armada's latest release and compares versions (ADR 0030).
runtime
Package runtime abstracts the container engine.
Package runtime abstracts the container engine.
runtime/conformance
Package conformance tests that the container runtime behaves as Armada needs (ADR 0011): the security defaults, checked from inside containers, the container lifecycle, labels, publishing on a private address, logs, exec, stats, volumes, network sandboxes, and errors.
Package conformance tests that the container runtime behaves as Armada needs (ADR 0011): the security defaults, checked from inside containers, the container lifecycle, labels, publishing on a private address, logs, exec, stats, volumes, network sandboxes, and errors.
runtime/containerd
Package containerd implements runtime.Driver on the containerd instance that Armada embeds (ADR 0011).
Package containerd implements runtime.Driver on the containerd instance that Armada embeds (ADR 0011).
runtime/embedded
Package embedded runs containers on Armada's own containerd instance (ADR 0011).
Package embedded runs containers on Armada's own containerd instance (ADR 0011).
runtime/embedded/mkbundle command
Command mkbundle downloads the artifacts pinned in embedded.Lock, checks their SHA-256, and writes the runtime pack that release builds embed.
Command mkbundle downloads the artifacts pinned in embedded.Lock, checks their SHA-256, and writes the runtime pack that release builds embed.
runtime/fake
Package fake provides an in-memory runtime.Driver for tests.
Package fake provides an in-memory runtime.Driver for tests.
runtime/imagecheck
Package imagecheck checks that an image's layers are what its config says they are before a runtime reuses an unpacked layer for it.
Package imagecheck checks that an image's layers are what its config says they are before a runtime reuses an unpacked layer for it.
runtime/supervisor
Package supervisor is the container runtime of ADR 0046: images and container records kept by the agent itself, containers supervised by armada-shim.
Package supervisor is the container runtime of ADR 0046: images and container records kept by the agent itself, containers supervised by armada-shim.
secrets
Package secrets encrypts secret values at rest with envelope encryption and provides a value type that never prints its contents.
Package secrets encrypts secret values at rest with envelope encryption and provides a value type that never prints its contents.
server
Package server implements the control plane: the gRPC API for the CLI and agents, and the reconciler that turns desired state into assignments.
Package server implements the control plane: the gRPC API for the CLI and agents, and the reconciler that turns desired state into assignments.
spec
Package spec defines the user-facing app configuration format, its strict YAML parsing, defaulting, and validation.
Package spec defines the user-facing app configuration format, its strict YAML parsing, defaulting, and validation.
store
Package store persists cluster state.
Package store persists cluster state.
store/storetest
Package storetest provides etcd-backed stores for tests in other packages.
Package storetest provides etcd-backed stores for tests in other packages.
version
Package version exposes build metadata for the armada binary.
Package version exposes build metadata for the armada binary.
volbackup
Package volbackup keeps deduplicated, encrypted backups of volumes in an S3-compatible bucket (ADR 0041).
Package volbackup keeps deduplicated, encrypted backups of volumes in an S3-compatible bucket (ADR 0041).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL