coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
64cbbd543e00e4075944e7aa34cc01bb5f667f21
orca/README.md
T
Jon Chery b6dd86fdf3 docs(P11): doc drift round 2 — README, cli.md, CHANGELOG, verify-reqs (REQ-160) 
- README: status banner v0.12+v0.13, latest tag v0.12.10, subcommand
  table expanded (auth/nft/peer-setup/secrets rotate-master), "mTLS by
  default" corrected to "SSH-push canonical", docs table updated
- docs/cli.md: complete rewrite (521->1465 lines), all ~40 subcommands
- CHANGELOG: regenerated from git log (v0.11.29..HEAD)
- help text: job run HCL->markdown, job stop daemon->SSH-push
- docs/security-runbook.md: expanded to match P05 reality (seal/unseal,
  doctor audit/modes/oidc, incident response)
- docs/webauthn.md: added auth register (P06)
- docs/namespace.md: added inherit + set-constraint
- internal/proxmox/bootstrap.go: comments password->key auth
- internal/cli/status.go: deprecation warning
- scripts/verify-docs.sh + make verify-docs: cli.md <-> orca --help
- cmd/verify-reqs/main.go: fix bold-format regex (was bypassing v0.12)
  + case-insensitive status matching
- .ciagent/REQUIREMENTS.md: v0.12 REQs marked complete
- .ciagent/ROADMAP.md: v0.12 bolded COMPLETE

---ci---
project: orca
phase: 11
milestone: v0.13
status: complete
requirements:
  covered: [160]
---/ci---
2026-08-10 14:18:27 +00:00

165 lines
7.4 KiB
Markdown
Raw Blame History

# Orca
A minimalist, offline-first, CLI-first orchestration engine inspired by
HashiCorp Nomad. Proxmox is one supported node type — not the project's
identity.
## Status
**v0.12: Security Hardening (Zero-Trust Identity) — COMPLETE** | **v0.13: Production Hardening Round 2 + UAT Plan — IN PROGRESS** | **v1.0: UAT-gated** (cut
separately after v0.13 completion per operator decision)
See [.ciagent/ROADMAP.md](.ciagent/ROADMAP.md) for the full roadmap.
## Pillars
- **Simplicity** — single binary, minimal dependencies, no daemon on the
critical path
- **Offline-first** — no cloud dependencies; the cluster is the OS
- **CLI-first** — the command line is the primary interface (humans and
AI agents)
- **Security before features** — SSH-push is the canonical transport
(mTLS available for daemon mode); NFRs ship before new functionality
- **WASM-first** — workloads target OS primitives (systemd units,
journald), not a container runtime shim
- **Bug fixes before features** — stability is paramount
## Quickstart
### Install (1-liner)
```bash
# User-level install (binary at ~/.local/bin/orca, state at ~/.orca)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash
# System-level install (binary at /usr/local/bin/orca, state at /root/.orca)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | sudo bash -s -- --system
# Pin a specific version (latest tag: v0.12.10)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --version v0.12.10
# Dry-run: check what would be installed without writing
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --check
```
Then initialize local state and verify:
```bash
orca init # creates ~/.orca/ (or /root/.orca with --system)
orca version # prints version info
orca --help # show all subcommands
```
### Build from source
```bash
make build # Build binary to ./bin/orca
./bin/orca init # Initialize local state
./bin/orca version # Verify
```
### Update in place
Re-running the installer updates the binary while preserving your
config, database, and certificates in the namespace dir:
```bash
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash
# → "updated orca from v0.11.28 to v0.12.10"
```
## Subcommands
| Command | Description |
|---------|-------------|
| `orca init` | Initialize local orca state with full bootstrap |
| `orca status` | **(deprecated v0.1 stub)** Show orca daemon status — use `orca node list` + `orca metrics /healthz` |
| `orca version` | Print version information |
| `orca daemon` | **(deprecated)** Run the orca daemon (HTTP API + health checks) |
| `orca metrics` | Start metrics endpoint (Prometheus text exposition) |
| `orca logs` | Aggregate journald logs across nodes (`--all-nodes --since`) |
| `orca backup` | Create a signed tar.gz backup of ORCA_HOME |
| `orca restore` | Restore ORCA_HOME from a verified signed backup |
| `orca upgrade` | Upgrade orca to a new version (thin wrapper; R-017 cutover) |
| `orca node` | Manage orca nodes: `join`, `leave`, `list`, `key-reset`, `drain`, `capacity` |
| `orca job` | Manage orca jobs: `run`, `list`, `stop`, `logs`, `lint`, `verify`, `migrate`, `restart` |
| `orca ns` | Manage orca namespaces: `list`, `create`, `delete`, `inspect`, `validate`, `inherit`, `set-constraint` |
| `orca cert` | **(deprecated)** Manage orca certificates: `ca-init`, `gen`, `show`, `renew`, `fingerprint` |
| `orca doctor` | Run self-checks: `cert`, `network`, `db`, `os`, `proxmox`, `no-orca-on-server`, `nft`, `audit`, `modes`, `oidc`, `db-retention` |
| `orca audit` | View orca audit log (`list`) |
| `orca cache` | CLI cache management: `show`, `invalidate`, `invalidate-all` |
| `orca acl` | ACL management: `grant`, `revoke`, `list`, `check` |
| `orca secrets` | Secrets management: `set`, `get`, `list`, `rotate`, `delete`, `rotate-master` |
| `orca drift` | Drift detection: `show`, `watch`, `acknowledge`, `remediate`, `config` |
| `orca txn` | Transaction management: `apply`, `list`, `show`, `rollback` |
| `orca nft` | nftables ingress management: `show`, `diff`, `doctor`, `country block`, `rate limit` |
| `orca collector` | Collector/aggregator management: `start`, `stop`, `status` |
| `orca cluster` | Cluster management: `cutover`, `rotate-lead`, `compat-check`, `seal`, `unseal` |
| `orca auth` | OIDC authentication: `login`, `logout`, `status`, `init-idp`, `register` |
| `orca peer-setup` | Create the orca system user + drift-events dir on a peer (REQ-111) |
See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags
and examples.
## Honest trade-offs
Orca is not a Kubernetes replacement for every workload. This table is
the honest comparison — K8s wins in several dimensions, and that is
acknowledged rather than papered over.
| Dimension | Kubernetes wins | Orca wins |
|-----------|-----------------|-----------|
| Ecosystem | Mature CNCF ecosystem; vast operator, controller, plugin surface | — |
| Talent pool | Large pool of K8s-experienced engineers | — |
| Multi-cloud | Portable across all major clouds; control plane is cloud-agnostic | — |
| Stateful operators | Rich operator pattern (CRD + controller) for stateful workloads | — |
| Service mesh | First-class service mesh (Istio, Linkerd) | — |
| Auto-scaling | Cluster autoscaler, HPA/VPA, deep integrations | — |
| Daemon footprint | — | No daemon on the critical path; the cluster is the OS |
| OS-native | — | Workloads are systemd units + journald; no container runtime shim |
| Transport | — | SSH-push is canonical (no daemon needed); mTLS available for daemon mode |
| Offline-first | — | No cloud dependencies; fully air-gapped operation |
| WASM-first | — | Workloads target OS primitives, not a container runtime |
| Proxmox | — | First-class Proxmox node type (`--type proxmox`) via SSH-push |
## Documentation
| Document | Description |
|----------|-------------|
| [docs/cli.md](docs/cli.md) | CLI reference — every command, flag, and example |
| [docs/jobspec.md](docs/jobspec.md) | Jobspec reference — markdown frontmatter schema |
| [docs/ingress.md](docs/ingress.md) | Ingress guide — Traefik configuration |
| [docs/namespace.md](docs/namespace.md) | Namespace and path layout |
| [docs/install.md](docs/install.md) | Installation guide |
| [docs/security-scanning.md](docs/security-scanning.md) | Security scanning tools |
| [docs/security-runbook.md](docs/security-runbook.md) | Security runbook — seal/unseal, rotation, incident response |
| [docs/webauthn.md](docs/webauthn.md) | WebAuthn / passkeys registration and login |
| [docs/threat-model.md](docs/threat-model.md) | STRIDE threat model + zero-trust architecture |
| [docs/oidc.md](docs/oidc.md) | OIDC configuration — Dex quickstart, BYO IdP |
## Examples
| Example | Description |
|---------|-------------|
| [examples/full-stack/](examples/full-stack/) | Full-stack deployment with ingress (5 services + rendered artifacts) |
## Development
```bash
make build # Build binary to ./bin/orca
make test # Run tests
go vet ./... # Vet all packages
make lint # Run gofmt + go vet + shellcheck
make verify-reqs # Assert ROADMAP ↔ REQUIREMENTS consistency
make verify-docs # Assert docs/cli.md ↔ `orca --help` consistency
```
## Architecture
See [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) for full
architecture details.
## License
MIT — see [LICENSE](LICENSE).
Reference in New Issue View Git Blame Copy Permalink