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:
ctrlplane deploy guestbook --image ghcr.io/you/guestbook:v1 -- --leader-electctrlplane deploy -f config/manager/manager.yamlWith -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.
What your controller gets
Section titled “What your controller gets”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.
Making your operator fit
Section titled “Making your operator fit”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/metricsover 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.
Settings
Section titled “Settings”-
Arguments and environment: one argument per line; environment as
KEY=valuelines. -
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.
Updating and removing
Section titled “Updating and removing”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.
When it doesn’t start
Section titled “When it doesn’t start”The site shows why (ImagePullBackOff, CrashLoopBackOff, or limits that don’t fit), and
Logs shows its output. See Troubleshooting.