ocaml-kube: a native Kubernetes client and controller library for OCaml

What was released

OCaml developers can now write Kubernetes operators without leaving their language. A library named ocaml-kube, published on opam as kube, provides a Kubernetes client and controller runtime. According to the announcement on dev.to, release 0.1.3 covers Kubernetes versions 1.34 through 1.37 and is exercised by integration tests against real API servers. Clusters outside that range may still work through the library's generic client, but they are unsupported, and supporting a minor version does not imply covering every alpha feature it contains.

Native OCaml, not a Go binding

The implementation is written directly in OCaml 5 rather than wrapping Go's client-go. Its HTTP/1.1 transport communicates over Unix sockets and relies on the OCaml TLS stack, while watches and controller workers run on system threads with cooperative cancellation.

Typed resource records and JSON codecs are generated from Kubernetes OpenAPI schemas pinned by checksum, with one schema library per minor release, from kube.api.v1_34 through kube.api.v1_37, all sharing a common runtime. The dev.to tutorials use the v1_36 library for their resource types, which the author notes does not restrict the finished operators to a 1.36 cluster.

On top of the client sit LIST/WATCH caches, a work queue, and retry handling. A Kube.Operator module looks after process startup, credentials, shutdown, diagnostics, and optional leader election, leaving application code to describe what should exist.

A Kubebuilder-style workflow

The library follows the scaffold-define-generate-reconcile rhythm familiar from Kubebuilder. With OCaml 5.1 or newer and opam installed, opam install kube.0.1.3 pulls in the library, and an ocaml-kube init command scaffolds a project given an API group, version, and kind — the equivalent of what Kubebuilder splits across its init and create-api steps. The generated project ships a model, a controller skeleton, a CRD, RBAC rules, a sample resource, a Deployment, and a Dockerfile.

APIs are described as OCaml records, with a PPX deriver producing JSON codecs and schemas. Field attributes, such as minimum and maximum string lengths, become validation rules in the generated CRD, and module functors instantiate typed clients and controllers for a given resource type. Running dune exec tools/generate_crd.exe produces the CRD manifest, and a dune build @codegen-check target fails when the checked-in manifest no longer matches the OCaml model — the library's answer to Kubebuilder's make manifests drift check.

Three tutorial operators

The post walks through three examples, each an independent Dune project with tests and deployment files. Greeting writes a message from its spec into a ConfigMap and introduces Server-Side Apply, owner references, and a Ready status condition. WebApp manages a Deployment and Service, watches both child kinds, and surfaces the Deployment's ready replica count in its status. Project is cluster-scoped and manages a Namespace plus a ResourceQuota, using a finalizer to delay the Project's removal until namespace deletion finishes.

Writing an owned resource is a single call that attaches the owner reference and applies the desired fields. A watch on child resources enqueues the parent when a child changes, and Kubernetes garbage-collects the children when the owner disappears; the Project example adds explicit cleanup to demonstrate finalizers.

A companion examples repository on GitHub provides make targets for building, testing, and a kind-based smoke test. The author reports running all three controllers against a Kubernetes 1.37 kind cluster, where the smoke test verified ConfigMap contents, the WebApp rollout and its status, the Project quota, and that finalization removed the Project's Namespace. Five unit tests and the CRD drift checks also passed.

Why it matters

Operator development is overwhelmingly a Go affair, with Rust and Python as secondary options, so teams with OCaml codebases have generally had to reach for another language to automate cluster state. ocaml-kube changes that calculus: the reconciliation contract — drive actual state toward the spec — is language-independent, and this library expresses it with idiomatic OCaml in the form of typed records, PPX-generated codecs, and module functors. The checksum-pinned, per-minor schema libraries are a pragmatic answer to Kubernetes API churn, and the Kubebuilder-shaped workflow keeps the learning curve shallow for anyone who has already written a Go operator. At version 0.1.3, with tutorial-scale examples, the project is clearly early — but it marks a credible entry for OCaml into cluster automation.