items.nebuaRuntimeComponents.title

NebuaCloud uses three runtime components around customer infrastructure. Each component has a separate ownership boundary so Core stays a business platform and Kubernetes automation stays close to the cluster.

Component Responsibilities#

Component	Runs Where	Primary Role	Owns
nebua-agent	Linux cluster host, usually each private cluster node	Kubernetes integration layer	Cluster API communication, resource synchronization, metrics, logs, events, health reporting, local k3s bootstrap plumbing, and explicit commands requested by Core
nebua-operator	Inside customer Kubernetes clusters	Optional advanced cluster intelligence	Self-healing, AI-driven remediation, policy enforcement, backup orchestration, GitOps enforcement, add-on lifecycle, and other autonomous reconciliation
nebua-gateway	Linux gateway/proxy host	Environment gateway proxy connector	Pulling desired proxy state, rendering Caddy or NGINX config, reloading the local proxy, and reporting gateway sync health

NebuaCloud Core Boundary#

NebuaCloud Core owns business platform concerns: identity, organizations, RBAC, billing, subscriptions, API keys, dashboards, notifications, audit logs, public APIs, and stored user intent. Core should not run autonomous Kubernetes remediation loops and should avoid direct customer-cluster operations when an agent/operator path exists.

nebua-agent#

nebua-agent is the Kubernetes integration layer for private infrastructure. It connects outbound to NebuaCloud, authenticates with an agent token, reports cluster state, and executes explicit commands from Core.

Use nebua-agent for:

• cluster connectivity and heartbeat reporting
• Kubernetes resource reads for dashboard views
• metrics, logs, and event forwarding
• HPA, CronJob, node, and workload operations explicitly requested by Core
• local k3s bootstrap, join, kubeconfig sync, and host capability checks

Do not put autonomous add-on repair, policy enforcement, or continuous reconciliation loops in nebua-agent.

nebua-operator#

nebua-operator is optional and is installed inside customer clusters when advanced capabilities are needed. It uses in-cluster service account credentials and reconciles Kubernetes-native resources and NebuaCloud CRDs.

Use nebua-operator for:

• self-healing and bounded workload remediation
• AI-driven remediation recommendations and future autonomous strategies
• policy enforcement through NebuaPolicy and admission policy providers
• backup orchestration through NebuaBackupPlan
• GitOps enforcement and drift control
• add-on install, upgrade, health, drift detection, and repair

Operator decisions should be idempotent, safe to replay, and visible through Kubernetes Events or CRD status.

nebua-gateway#

nebua-gateway is separate from cluster management. It runs on a gateway host that owns local reverse-proxy configuration for one environment.

Use nebua-gateway for:

• environment gateway proxy routing
• Caddy or NGINX config rendering
• safe proxy reload commands
• reporting gateway availability and sync health

Run one gateway agent per gateway host/environment ownership boundary.

Installation Paths#

Each component has its own installation guide with full prerequisites, environment file reference, verification steps, and troubleshooting:

• nebua-agent — install on each private cluster host
• nebua-operator — optional, install inside the cluster via kubectl
• nebua-gateway — install on each gateway/proxy host

Placement Rule#

If a feature only reads cluster state or executes an explicit Core-requested action, place it behind nebua-agent. If a feature watches resources, decides when to act, repairs drift, enforces policy, manages add-ons, or performs continuous reconciliation, place it in nebua-operator. If a feature manages external HTTP exposure for an environment, place it in nebua-gateway.