Most of the operators I’ve built manage things that don’t live in Kubernetes: virtual machines on a hypervisor, cloud resources or any other external system that allows me to manage it declaratively. I wrote about that in Missing Piece of Kubernetes Operators, because I really like treating Kubernetes as a universal API. You describe what you want as a custom resource, and a controller makes it happen somewhere else.

The annoying part is running them. Every one of these operators needs a whole Kubernetes cluster behind it. You can definitely spin the operator up yourself on kind or any other local cluster setup but if you’re testing or developing operators frequently, that overhead becomes cumbersome especially when you have to delete and recreate clusters often.

So with that frustration in mind, I built ctrlplane with the goal of providing a ready-to-use Kubernetes control plane for operators who manage external resources, without the need to maintain a full cluster yourself.

What is ctrlplane?#

There are two things with that name, so let me separate them up front:

  • ctrlplane is the open source project: a Kubernetes control plane built for operators, with no nodes or workloads attached. The source is on GitHub and you can run it yourself.
  • ctrlplane.run is the hosted platform I operate on top of it, batteries included: the metrics and log storage, the scraping, the tunnel endpoints and the web console are all already wired up, so you don’t have to run anything at all.
 ┌───────────────────────────────┐
 │  Your control plane           │
 │  <id>.api.ctrlplane.run       │
 │  CRDs · RBAC · Webhooks       │
 └───────────────┬───────────────┘
                 │ watch / reconcile
                 ▼
 ┌───────────────────────────────┐
 │  Your controller              │
 │  ghcr.io/you/my-operator:v1   │
 └───────────────┬───────────────┘
                 │ tunnel (outbound only)
                 ▼
 ┌───────────────────────────────┐
 │  The outside world            │
 │  VMs · DNS · databases · APIs │
 └───────────────────────────────┘

The rest of this post is mostly about the hosted version, because that’s the quickest way to try it but you can also run the open source version yourself if you prefer.

What it isn’t?#

ctrlplane serves the Kubernetes API, not a cluster to run workloads on. Your control plane has no Pods, Deployments or Nodes: you can’t kubectl run anything on it. Your controllers are the only workloads, and ctrlplane runs them for you.

From zero to a running operator#

On ctrlplane.run, the whole flow is a handful of commands:

brew install alperencelik/tap/ctrlplane
ctrlplane login                    # sign in with GitHub
ctrlplane create dev --wait        # your own control plane, ready in about a minute
ctrlplane use dev                  # point kubectl at it
kubectl apply -f crds/             # your CRDs
ctrlplane deploy my-operator --image ghcr.io/you/my-operator:v1

From there it’s plain Kubernetes. kubectl apply a custom resource, kubectl get <kind> -w, and watch your controller pick it up. If you’d rather click than type, the site at app.ctrlplane.run does the same things: add CRDs by pasting YAML or a release URL, deploy a controller with a name and an image, then edit, restart, stop or remove it from the console.

If you already have a manager.yaml from kubebuilder, you can hand that over directly:

ctrlplane deploy -f config/manager/manager.yaml

Networking: reach your stuff without exposing it#

Operators that manage external resources need to reach those resources, and those usually sit on a private network. A Proxmox host in a homelab, a database in a VPC or an internal API. I didn’t want anyone to open inbound ports for this.

ctrlplane uses a tunnel that you start from inside your network, so traffic is outbound only and works behind NAT. There are two ways to set it up:

  • Connector: run a single container on a machine in your network. The tunnel can reach whatever that machine can reach.
  • Tailscale or Headscale: paste an ephemeral auth key and the tunnel joins your tailnet as ctrlplane-<control plane>. Your ACLs and subnet routes decide what it can see.

Observability: metrics, logs and events, kept for you#

Every controller gets its metrics endpoint (:8080/metrics by default) scraped every 15 seconds. You can see reconcile rates, errors, reconcile time, queue depth, and CPU, memory and network usage, with 15 days of retention. Logs are collected and searchable with LogsQL, with live tail.

The events generated by your operator are collected and retained alongside logs, so you can see what happened and when.

You can also use your own Grafana for metric visualizations since the control plane serves the data directly. Add https://<id>.api.ctrlplane.run/platform/metrics as a Prometheus data source using the provided URL.

Nothing to maintain#

After ctrlplane create, there’s nothing to look after. No upgrades, no certificate rotation, no backups to schedule. You sign in with kubectl and work against the API like any other cluster.

How it works under the hood#

Each control plane is a real Kubernetes API server, not a proxy or an imitation. It’s built on the generic control plane from upstream Kubernetes (KEP-4080). That’s the API server with the container-orchestration parts removed. There is no Pods, no nodes, no schedule. Basically api-server is built from ground up with only the components an external operator would need such as CRDs, RBAC, service accounts, configMaps, secrets and admission webhooks.

Instead of etcd, each control plane embeds kine backed by its own SQLite database. For a control plane that holds CRDs and the custom resources of one or a few operators, a full etcd cluster is overkill, and a single file is much easier to snapshot and restore. The namespace, service account and garbage collector controllers run in-process, so the API behaves the way your operator expects.

Dogfooding with kubemox#

The first operator I put on ctrlplane.run was my own: kubemox, which manages Proxmox objects as Kubernetes resources. Until then, I needed a cluster sitting next to the Proxmox host just to run kubemox’s controller. Now it’s a control plane on ctrlplane.run, Tailscale configured for my home network, and kubectl apply for VMs. Nothing else to run.

That’s the use case I’m building for: you have an operator (yours or someone else’s) that manages something outside Kubernetes, and you want the Kubernetes API for it without operating Kubernetes.

Try it#

ctrlplane.run is in early access and under active development. Sign in with GitHub at app.ctrlplane.run. New accounts are approved by hand for now. The getting started guide walks through the whole flow, and the CLI is on Homebrew.

If you’d rather run it yourself, the ctrlplane source is on GitHub.

If you run operators against things outside your cluster, I’d love to hear how you do it today and whether ctrlplane would fit. Feedback and issues are all welcome.

If you’d like to give it a try, request access at app.ctrlplane.run or send me an email at [email protected] for an invite.