Nebua Runtime Components

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.