Skip to content

Controllers

A controller is a container image ctrlplane runs against your control plane. For a popular operator, a plugin runs it for you with no image to bring. Deploy one under Controllers → Deploy a controller with a name and an image (Edit changes it later), or with the CLI:

Terminal window
ctrlplane deploy guestbook --image ghcr.io/you/guestbook:v1 -- --leader-elect
ctrlplane deploy -f config/manager/manager.yaml

With -f, ctrlplane reads your operator’s Deployment (or the one in an install.yaml) and takes what the form asks for from its manager container: the image, args, env, CPU and memory limits, probes, a port named webhook-server, and metrics from kubebuilder’s --metrics-bind-address. Nothing is applied to your control plane; the CLI says what it didn’t use, such as volumes or sidecars.

KUBECONFIG=/var/run/tenant/kubeconfig A kubeconfig for your control plane, used automatically by controller-runtime and client-go.
WATCH_NAMESPACE, POD_NAMESPACE Your control plane’s namespace.
HTTPS_PROXY, NO_PROXY Only with a tunnel; see Networking.

It may do anything in your control plane’s namespace and with your own API types, and nothing else.

Most controller-runtime and kubebuilder operators work unchanged. Check these:

  • Runs as non-root. Controllers run as user 65532, without capabilities. Write to /tmp.
  • Metrics are scraped from :8080/metrics over HTTP unless you say otherwise under Metrics. kubebuilder v4’s secure metrics (--metrics-bind-address=:8443) work too: set port 8443 and HTTPS.
  • Webhooks need a webhook port; see Webhooks.
  • Arguments and environment: one argument per line; environment as KEY=value lines.

  • CPU and memory limits: controllers share their control plane’s CPU and memory; without a limit, a controller gets an even share of what’s left.

  • Metrics: the port and path your controller serves Prometheus metrics on (default :8080/metrics; port 0 turns scraping off), and HTTPS for controller-runtime’s secure metrics. ctrlplane scrapes HTTPS metrics with a token your controller accepts.

  • Probes: liveness, readiness and startup probes as Kubernetes YAML:

    livenessProbe:
    httpGet: {path: /healthz, port: 8081}
  • Private images: a registry username and token, stored for that controller only.

Edit rolls out the new version; if it can’t start, the old one keeps running. Restart replaces the controller’s pod. Remove deletes the controller; your resources stay.

The site shows why (ImagePullBackOff, CrashLoopBackOff, or limits that don’t fit), and Logs shows its output. See Troubleshooting.