OpenKubes Kubernetes Platform Distribution Framework

What it is

A contract-first platform engineering framework

OpenKubes formalizes how Kubernetes capabilities get built, provisioned, and verified — without locking teams into a single vendor, cloud, or component. Every capability follows the same chain from idea to running cluster:

Capability → Contract → Implementation Profile → Provider Values → Contract Tests

"A cluster is not considered fully provisioned until the contract test passes." — ADR-018

"No structure without a forcing consumer." A contract is only formalized once a second real consumer needs it.

Decisions are recorded as Architecture Decision Records (ADRs) and never skipped — there is no implementation without a committed ADR. The project's knowledge graph (okgraph.py) maps every ADR, commit, and issue into a single traversable structure, so the reasoning behind the platform is never lost.

How decisions get made

Three-way review, human merge

Every ADR passes through a structured review before it can be merged:

Author

Anyone — maintainer or external contributor — can author an ADR or propose a change on a branch. No direct write access to main.

Claude & GPT review

Claude checks internal consistency and missing counter-arguments. GPT checks governance language and cross-ADR consistency. AI may argue — it does not merge.

Human merge

The maintainer holds project context and makes the final call. "AI may argue; only humans merge."

Branch protection is enforced on the mother repo: pull requests required, no force-push, linear history. The three-way review is a process discipline, not a technical gate.

Where the code lives

Repositories

openkubes/openkubes

Mother repo — architecture, ADRs, platform-engineering-method.md, knowledge graph.

public
openkubes/ok-cluster

Cluster lifecycle capability — provisioning, bootstrap, teardown, kubeconfig contracts. Live cluster access is VPN-only.

public
openkubes/ok-storage

Storage capability contracts and provider implementations.

public
openkubes/ok-observability

Per-cluster Prometheus, Grafana, and OpenSearch stack (ADR-018).

public
openkubes/ok-linux

Base OS layer for constrained and edge deployment profiles.

public

All repos are public — code, contracts, and ADRs are open. Real provider values and cluster credentials never live in the repos; reaching a live cluster itself requires VPN access.

Get involved

How to contribute

Read the method first. Start with docs/platform-engineering-method.md in openkubes/openkubes and browse the ADR series to understand what's already decided.
Find a forcing consumer. OpenKubes doesn't build structure speculatively — proposals land better when tied to a real second use case, not a hypothetical one.
Open a branch, not a direct commit. main is protected. Author your ADR or change on a branch and open a pull request.
Go through three-way review. Expect feedback from both AI reviewers before a maintainer makes the merge decision.
Small, scoped changes. ADRs are precise and narrow — future ideas become new tickets rather than expanding an in-flight one.

Good places to start

Constrained edge profile

Five open spikes: OS candidate, GitOps agent, image strategy, storage, autonomy-under-partition.

`ok` CLI

Wrapper-vs-logic-carrier design spike — standalone binary vs. kubectl plugin (Krew).

Requirements inventory

Research spike on whether a first-class Requirement layer belongs in the architecture.

Cluster deregistration

make unregister-cluster — clean up orphaned secrets and ProviderConfigs after teardown.

Community

Launch meetup & contact

🚀 OpenKubes Launch Meetup — Thu, Aug 6, 2026, 7:00 PM, online via Zoom. Hosted by Kubernauts Worldwide Meetup. Agenda: why OpenKubes, project vision, a live demo of declarative cluster provisioning with private AI, roadmap, and how to become a contributor.

GitHub Issues Slack kubernauts.io