Jon Chery
3be86e6daf
REQ-183: Fix .gitea/workflows/release.yml — the git clone of the private coreci repo failed because the clone command had no credentials. The actions/checkout@v4 step only injects auth for the orca repo. Fix: pass GITEA_TOKEN env to the Install CoreCI step and embed it in the clone URL (https://cloudinit-bot:${GITEA_TOKEN}@git.cloudinit.dev/...). REQ-184: Rewrite .coreci.yml from the invalid pipelines:/steps:/image:/ commands: format to CoreCI's native jobs:/plugin:/invoke:/vars: format with a proper DAG (needs:). CoreCI's Pipeline struct only recognizes jobs:/services:/env: top-level keys — unknown fields are silently dropped by yaml.Unmarshal, producing an empty Jobs map → zero jobs execute. The rewrite: - 8 jobs: go-vet → fan-out (verify-reqs, gosec, govulncheck, gitleaks) → build → test → release - plugin: docker://golang:1.25.12 + invoke: on each job (container path with shell-isolated fallback — Go is installed on the runner) - GITEA_TOKEN via vars: with ${{ secrets.GITEA_TOKEN }} (resolved from env via CoreCI's secret resolver os.Getenv fallback) - CI_COMMIT_BRANCH (tag name on tag push) and CI_COMMIT_SHA for version injection — no ${VAR} interpolation in YAML fields (shell expansion only works inside invoke: via sh -c) - No apk add (runner is ubuntu, not alpine — uses curl for tool downloads) - Release job handles duplicate release (ship workflow creates release first with title+body; coreci run attaches binary assets later via API fallback if tea releases create fails) - Release job verifies asset count ≥ 2 (REQ-097 gate C-21) with retry Root cause: all 87 releases in repo history had zero binary assets because coreci run never executed any jobs (empty Jobs map from the invalid format) and the Gitea Actions workflow failed before reaching coreci run (private repo clone had no credentials). ---ci--- project: orca phase: 1 milestone: v0.16 status: execute requirements: covered: [183, 184] partial: [] ---/ci---
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 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)
# 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:
orca init # creates ~/.orca/ (or /root/.orca with --system)
orca version # prints version info
orca --help # show all subcommands
Build from source
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:
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 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 | CLI reference — every command, flag, and example |
| docs/jobspec.md | Jobspec reference — markdown frontmatter schema |
| docs/ingress.md | Ingress guide — Traefik configuration |
| docs/namespace.md | Namespace and path layout |
| docs/install.md | Installation guide |
| docs/security-scanning.md | Security scanning tools |
| docs/security-runbook.md | Security runbook — seal/unseal, rotation, incident response |
| docs/webauthn.md | WebAuthn / passkeys registration and login |
| docs/threat-model.md | STRIDE threat model + zero-trust architecture |
| docs/oidc.md | OIDC configuration — Dex quickstart, BYO IdP |
Examples
| Example | Description |
|---|---|
| examples/full-stack/ | Full-stack deployment with ingress (5 services + rendered artifacts) |
Development
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 for full architecture details.
License
MIT — see LICENSE.