armada

module
v0.0.0-rehearsal.1 Latest Latest
Warning

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

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

README

Armada

Status: pre-alpha. Not ready for production use yet.

Armada turns a handful of Linux machines into a container platform: apps, revisions, rolling updates, domains, and automatic TLS. One binary, one install command.

name: web
image: ghcr.io/acme/web:1.4.2
ingress:
  type: external
  port: 8080
probes:
  readiness:
    path: /healthz
scale:
  min: 2
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.
  • HTTPS by default. HAProxy on every node, certificates from Let's Encrypt (HTTP-01, or DNS-01 with Cloudflare for 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.
  • Secrets. Encrypted at rest, versioned, delivered as env vars or as read-only files on tmpfs.
  • Multiple nodes. Join with a single-use token; nodes get short-lived mTLS certificates that they renew themselves. 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.
  • 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. 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: the binary embeds its own container runtime (containerd, runc, CNI plugins) and its state store (etcd).

Documentation

Tested environments

Environment Status
Cloudflare DNS-01 with Let's Encrypt staging Tested: wildcard certificate for the root domain
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, Let's Encrypt staging Tested end to end: install.sh, server joins, replicas on all three nodes, HTTPS through any node, leader stop and SIGKILL under load without errors, scale and rolling update through the new leader, backup, all three machines rebooted at once

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
make test     # unit tests with the race detector
make check    # vet + lint + test + govulncheck (what CI runs)

License

Apache License 2.0

Directories

Path Synopsis
api
cmd
armada command
Command armada is the single binary for the control plane, the node agent, and the CLI.
Command armada is the single binary for the control plane, the node agent, and the CLI.
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.
Package cli wires the armada command tree.
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.
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.
runtime
Package runtime abstracts the container engine.
Package runtime abstracts the container engine.
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