armada

module
v0.1.0-alpha.4 Latest Latest
Warning

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

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

README

Armada logo

Armada

Status: alpha. Specs, flags, and the state format may still change between releases.

Armada turns a handful of Linux machines into a container platform: apps, revisions, rolling updates, domains, and automatic TLS. One install command: armadad runs each machine, armada manages apps from anywhere, Linux or macOS.

name: web
image: ghcr.io/acme/web:1.4.2
ingress:
  type: external
  port: 8080
probes:
  readiness:
    path: /healthz
scale:
  min: 2
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh
armada deploy -f web.yaml    # → https://web.apps.example.com

What it does

  • Desired state, reconciled. The CLI writes what you want; the control plane and an agent on every node converge to it and keep it there.
  • Rolling updates and rollback. Revisions pin the image digest and the secret versions. New replicas take traffic only once their probes pass, and old ones are drained, not killed.
  • Traffic splitting. revisions.mode: multiple splits requests between revisions by weight, with a URL of their own for labelled revisions, for canaries and previews.
  • HTTPS by default. HAProxy on every node, certificates from Let's Encrypt (HTTP-01, or DNS-01 with Cloudflare for the root domain and a wildcard), custom domains after TXT ownership verification.
  • Internal services. ingress: internal apps are reachable from any container in the cluster at http://<app>.internal, never from outside.
  • Local-first routing. Each node sends requests to its own replicas while they are about as busy as the rest, and spreads the excess over every node, so most requests never cross the network.
  • Cluster network. Each node's containers get their own subnet of one private range, routed between nodes over a tunnel on the private network, so replicas are reached at their own address and see their caller's real one; --network wireguard encrypts it. Apps reach each other only through their internal names.
  • Projects. Apps, jobs, secrets, domains, and volumes belong to a project, so web can run in staging and in default side by side. Tools such as CI systems get automation identities that manage only their projects, never the cluster. Each project resolves and reaches only its own internal names (ingress.allow narrows an app to chosen callers), and its containers are kept away from the nodes, the private network, and the cloud's metadata service.
  • Administrators. Each person gets a certificate under their own name (armada admin add), so the audit log names them, and armada admin rm takes one person's access back at once.
  • Secrets. Encrypted at rest, versioned, delivered as env vars or as read-only files on tmpfs; envFrom: secrets turns all of an app's secrets into variables.
  • One spec, several environments. ${NAME} in a spec is filled in from armada deploy --vars production.env --var TAG=....
  • Logs and exec. armada logs streams a replica's output, rotated and rate limited on the node so no app can flood its disk; armada exec web -it -- sh opens a shell in one, with the container's own security settings, and every session is audited.
  • Usage. armada top shows the CPU and memory each app, replica, and node uses next to what it reserves, sampled every 10 seconds, and per project also its volumes, requests, and egress.
  • Autoscaling. scale.rules keep an app between scale.min and scale.max by requests in progress, CPU, or memory per replica. With scale.min: 0, an idle app stops its last replica and the next request starts it again.
  • Jobs. kind: job runs a container to completion, on demand or on a cron schedule with a time zone, with timeouts, retries, and run history.
  • Volumes. volumes keep an app's data on its node across deploys, crashes, and reboots, for databases and uploads; armada volume backup and restore copy it out and back, onto another node if its own is gone.
  • Events. armada events shows what the cluster did over the last day: crashes and restarts, rollouts, lost nodes, replicas moved, certificates; -f follows new ones.
  • Metrics. The leader serves Prometheus metrics (apps, replicas, nodes, usage, reconciles) on a private address, only to client certificates that armada metrics credentials creates.
  • Multiple nodes. Join with a single-use token; nodes get short-lived mTLS certificates that they renew themselves, and servers renew their own. Cordon, evacuate, remove. Replicas of a lost node are started elsewhere, and apps spread out again, one replica at a time, when a node returns or joins.
  • Placement. Label nodes (by hand or in the join token), keep apps to the nodes they require, and spread them evenly over a label's values (sites, racks); restricted nodes run only the apps that ask for them. Every node reports its OS, architecture, and container runtime as labels, and apps run only on nodes their image is built for. Replicas reserve CPU and memory on their node, and no node is overcommitted.
  • Highly available control plane. One server works; three survive the loss of any one. Servers elect a leader, agents and the CLI follow it, and certificates are not re-issued on failover.
  • Rolling upgrades. armada version and armadad doctor say when a newer release is out, and sudo armadad upgrade installs it, verified, on a machine. Upgrade servers, then nodes, one at a time while apps keep serving; state migrations wait until every server runs the new version, and downgrades onto migrated state are refused.
  • Confined containers. Dropped capabilities, no-new-privileges, seccomp, AppArmor or SELinux (each container in its own MCS categories), and memory, CPU, and PID limits.

Armada needs Linux machines (cloud instances, VMs, or bare metal) with a private network between them, and nothing else: armadad embeds its own container runtime (containerd, runc, CNI plugins) and its state store (etcd). The armada client needs no root and also runs on macOS.

Documentation

Tested environments

Environment Status
Cloudflare DNS-01 with Let's Encrypt staging Tested on depa.id (amd64, Ubuntu 24.04): certificates for the root domain and a wildcard, domain verification, challenge records removed afterwards, the token kept out of logs and events, and requests through the Cloudflare proxy with trusted proxies (the client's address kept, forged headers from elsewhere dropped)
Local lab: Linux VMs (arm64), Pebble ACME, 1–2 nodes Tested end to end: deploys, rolling update, secret files, internal ingress and DNS, crash recovery, containerd restart with containers kept running, reboot recovery, rolling upgrade with a state migration, rebalancing after uncordon under HTTPS load without errors, replicas across nodes
Oracle Cloud (arm64, Oracle Linux 9, SELinux enforcing), one server, Let's Encrypt staging Tested end to end: install.sh with systemd, doctor, wildcard certificate over Cloudflare DNS-01, rolling update under load without errors, crash recovery, containerd restart, reboot recovery, SELinux-confined apps and HAProxy, HAProxy restarted after a crash
depa.id (amd64, Ubuntu 24.04), three control plane servers and one node, Let's Encrypt staging Tested end to end with test/e2e: server and node joins, only HAProxy public, certificates on every node, secrets, rolling update, rollback, and agent restart under load without errors, leader stop and SIGKILL under load, node loss and rebalancing under load, backup, all machines rebooted at once
Mixed architectures: three depa.id servers (amd64, Ubuntu 24.04) and an Oracle Cloud node (arm64, Oracle Linux 9, SELinux enforcing), Let's Encrypt staging Tested end to end with test/e2e: every scenario above except the reboot, plus placement under load and images built for one architecture running only on nodes of that architecture
depa.id (amd64, Ubuntu 24.04, kernel 6.8), two machines on a private network, --network wireguard Tested: the kernel WireGuard device on both nodes, handshakes in armadad doctor, requests between replicas on different nodes, only encrypted traffic on the private network, the tunnel staying up while an agent is stopped, the same key after an agent restart, and recovery after a node reboot

Reports from other providers are welcome.

Development

Requires Go (see go.mod), golangci-lint v2, govulncheck, and protoc (only for make proto).

make build    # ./bin/armada (client) and ./bin/armadad (daemon)
make test     # unit tests with the race detector
make check    # vet + lint + test + govulncheck (what CI runs)

test/e2e builds a cluster on real machines and tests it end to end: rolling updates and failover under load, node loss, reboots.

License

Apache License 2.0

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.
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.
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.
fsutil
Package fsutil writes and reads sensitive files with strict permissions.
Package fsutil writes and reads sensitive files with strict permissions.
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.
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, 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, 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.
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.

Jump to

Keyboard shortcuts

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