How NebulaCtrl works

NebulaCtrl is a deployment control plane for K3s clusters. The control plane is a central service that stores the desired state: what runs, where. An agent in each cluster makes it so. You describe the result you want, and the agent does the work in the cluster.

The partsCopy Anchor Link

flowchart LR
you["You: console, API, CLI"] --> api
git["Git providers"] -->|"push webhooks"| api
subgraph cp["Control plane (one host, Docker)"]
  api["HTTP API and console"]
  pg[("PostgreSQL")]
  api --- pg
end
subgraph ca["Cluster A (K3s)"]
  agentA["Agent"] --> podsA["Your services"]
end
subgraph cb["Cluster B (K3s)"]
  agentB["Agent"] --> podsB["Your services"]
end
agentA -->|"outbound HTTPS: desired state in, events out"| api
agentB -->|"outbound HTTPS: desired state in, events out"| api
ca <-->|"WireGuard mesh"| cb

• Control plane. One process, nebula serve, runs in a container on a host you own. It serves the HTTP API and the console, keeps its data in PostgreSQL with TimescaleDB, and runs the background jobs that schedule builds, expire approvals and flag stalled deployments.
• Agent. A pair of replicas in the nebula-system namespace of each cluster, one active at a time. The agent turns desired state into Kubernetes objects, runs your builds in the nebula-build namespace, and reports nodes, workloads, logs and events back.
• Cluster. A K3s cluster that one agent belongs to. A cluster has one or more nodes. Environments run on a cluster, and one cluster can host environments of several projects.
• Mesh. Every node of every cluster in your organization joins one WireGuard network, so clusters can reach each other privately. See Networking.

The control plane never runs your workloads. The agent never decides what runs. That split is why a cluster keeps serving when the control plane is down for an update.

Desired stateCopy Anchor Link

When you deploy, change a variable or add a domain, the control plane records the change and compiles a desired state for the affected environments: the releases, processes and domains that are meant to run, at a numbered revision. It sends the whole state to the cluster's agent. The agent reconciles the cluster toward it and ignores any state older than the revision it already applied.

If the control plane can't compile a service, for example because a variable points at a deleted service, it sends that service as held. The agent leaves what it already runs for it exactly as it is and applies everything else.

The link is outbound onlyCopy Anchor Link

The agent opens an HTTPS connection to your control plane's public URL and keeps it open. Desired state and commands arrive through that connection, and the agent sends a heartbeat every 15 seconds.

• A cluster needs no inbound port for NebulaCtrl, so a cluster behind NAT works.
• Your control plane's URL must be reachable, with valid TLS, from every cluster.
• If a cluster sends no heartbeat for 60 seconds, the console shows it as Disconnected. Its workloads keep running. Deployments that need that cluster show the blocker delivery until the agent returns.

A deployment end to endCopy Anchor Link

1. You deploy a service in the console, or a push to a tracked Git branch does it for you.
2. For a Git service, the control plane schedules a build. The agent runs it as a job in the cluster and pushes the image to the cluster's registry. See Builds.
3. A successful build, or your choice of image, creates a release: an immutable image digest plus the configuration frozen at that moment.
4. In a protected environment, the release first waits for an approval. See Change sets and approvals.
5. The control plane starts a deployment of the release and sends the new desired state. The agent starts the new processes, probes them, switches traffic and retires the old release. See Deployments.
6. The agent reports each stage back, and the console shows them as they happen.

What NebulaCtrl keepsCopy Anchor Link

The control plane's database holds your organizations, projects, configuration, release history, deployment events and audit events. Secret values are sealed with the master key from the control plane's .env file before they're stored. A database restored without that key keeps its data, but every sealed value in it is lost. Build logs and container logs are kept for 7 days.

RelatedCopy Anchor Link