Operator Installation (Recommended)¶

The NovaEdge Operator is the recommended way to deploy and manage NovaEdge in production.

Overview¶

The Operator provides:

Automated lifecycle management - Deploy, upgrade, and scale with a single CRD
Self-healing - Automatic recovery from failures
Configuration management - Centralized configuration via NovaEdgeCluster
Rolling upgrades - Zero-downtime version updates

flowchart LR
    subgraph Operator["What You Do"]
        CR["Apply<br/>NovaEdgeCluster"]
    end

    subgraph Auto["Operator Creates"]
        CTRL["Controller"]
        AGENT["Agents"]
        WEBUI["Web UI"]
        RBAC["RBAC"]
    end

    CR --> Auto

    style Operator fill:#e6f3ff
    style Auto fill:#90EE90

Prerequisites¶

Kubernetes 1.29+
Helm 3.0+
kubectl configured with cluster admin access

Step 1: Install the Operator¶

# Clone the repository
git clone https://github.com/piwi3910/novaedge.git
cd novaedge

# Install the operator
helm install novaedge-operator ./charts/novaedge-operator \
  --namespace novaedge-system \
  --create-namespace

Verify the operator is running:

kubectl get pods -n novaedge-system -l app.kubernetes.io/name=novaedge-operator

Step 2: Deploy NovaEdge¶

Create a NovaEdgeCluster resource:

# novaedge-cluster.yaml
apiVersion: novaedge.io/v1alpha1
kind: NovaEdgeCluster
metadata:
  name: novaedge
  namespace: novaedge-system
spec:
  version: "v0.1.0"

  controller:
    replicas: 1
    leaderElection: true

  agent:
    hostNetwork: true
    vip:
      enabled: true
      mode: L2

  webUI:
    enabled: true
    service:
      type: ClusterIP

kubectl apply -f novaedge-cluster.yaml

Step 3: Verify Deployment¶

# Check cluster status
kubectl get novaedgecluster -n novaedge-system

# Check all pods are running
kubectl get pods -n novaedge-system

# Expected output:
# novaedge-operator-xxx      1/1     Running
# novaedge-controller-xxx    1/1     Running
# novaedge-agent-xxxxx       1/1     Running (one per node)
# novaedge-webui-xxx         1/1     Running

Configuration Examples¶

Production HA Setup¶

apiVersion: novaedge.io/v1alpha1
kind: NovaEdgeCluster
metadata:
  name: novaedge-prod
  namespace: novaedge-system
spec:
  version: "v0.1.0"

  controller:
    replicas: 3
    leaderElection: true
    resources:
      requests:
        cpu: "200m"
        memory: "256Mi"
      limits:
        cpu: "1000m"
        memory: "1Gi"
    affinity:
      podAntiAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchLabels:
                  app.kubernetes.io/component: controller
              topologyKey: kubernetes.io/hostname

  agent:
    hostNetwork: true
    resources:
      requests:
        cpu: "200m"
        memory: "256Mi"
      limits:
        cpu: "2000m"
        memory: "2Gi"
    vip:
      enabled: true
      mode: L2
    updateStrategy:
      type: RollingUpdate
      maxUnavailable: 1

  webUI:
    enabled: true
    replicas: 2
    service:
      type: LoadBalancer

  observability:
    metrics:
      enabled: true
      serviceMonitor:
        enabled: true
    tracing:
      enabled: true
      endpoint: "jaeger-collector:4317"
    logging:
      level: info
      format: json

BGP Mode¶

apiVersion: novaedge.io/v1alpha1
kind: NovaEdgeCluster
metadata:
  name: novaedge-bgp
  namespace: novaedge-system
spec:
  version: "v0.1.0"

  controller:
    replicas: 2
    leaderElection: true

  agent:
    hostNetwork: true
    vip:
      enabled: true
      mode: BGP
      bgp:
        asn: 65000
        routerID: "10.0.0.1"
        peers:
          - address: "10.0.0.254"
            asn: 65001
            port: 179

  webUI:
    enabled: true

Minimal Setup (Development)¶

apiVersion: novaedge.io/v1alpha1
kind: NovaEdgeCluster
metadata:
  name: novaedge-dev
  namespace: novaedge-system
spec:
  version: "v0.1.0"
  controller:
    replicas: 1
  agent:
    hostNetwork: true
    vip:
      enabled: true
      mode: L2

NovaEdgeCluster Reference¶

Spec Fields¶

Field	Type	Description
`version`	string	NovaEdge version to deploy (required)
`imageRepository`	string	Image repository (default: `ghcr.io/piwi3910/novaedge`)
`imagePullPolicy`	string	Pull policy (default: `IfNotPresent`)
`controller`	object	Controller configuration
`agent`	object	Agent configuration
`webUI`	object	Web UI configuration
`observability`	object	Metrics, tracing, logging
`tls`	object	Internal mTLS configuration

Controller Configuration¶

Field	Type	Default	Description
`replicas`	int	1	Number of controller replicas
`leaderElection`	bool	true	Enable leader election
`grpcPort`	int	9090	gRPC config server port
`metricsPort`	int	8080	Prometheus metrics port
`resources`	object	-	Resource requirements
`nodeSelector`	map	-	Node selector
`tolerations`	array	-	Pod tolerations
`affinity`	object	-	Pod affinity

Agent Configuration¶

Field	Type	Default	Description
`hostNetwork`	bool	true	Use host networking
`httpPort`	int	80	HTTP traffic port
`httpsPort`	int	443	HTTPS traffic port
`vip.enabled`	bool	true	Enable VIP management
`vip.mode`	string	L2	VIP mode (L2, BGP, OSPF)
`vip.interface`	string	-	Network interface
`vip.bgp`	object	-	BGP configuration
`updateStrategy`	object	RollingUpdate	Update strategy
`resources`	object	-	Resource requirements
`nodeSelector`	map	-	Node selector
`tolerations`	array	-	Pod tolerations

Web UI Configuration¶

Field	Type	Default	Description
`enabled`	bool	false	Enable Web UI
`replicas`	int	1	Number of replicas
`port`	int	9080	Web UI port
`readOnly`	bool	false	Read-only mode
`service.type`	string	ClusterIP	Service type
`ingress.enabled`	bool	false	Enable ingress

Observability Configuration¶

Field	Type	Default	Description
`metrics.enabled`	bool	true	Enable Prometheus metrics
`metrics.serviceMonitor.enabled`	bool	false	Create ServiceMonitor
`tracing.enabled`	bool	false	Enable tracing
`tracing.endpoint`	string	-	OTLP endpoint
`tracing.samplingRate`	int	10	Sampling rate (0-100)
`logging.level`	string	info	Log level
`logging.format`	string	json	Log format

Upgrading¶

Update the version in your NovaEdgeCluster:

kubectl patch novaedgecluster novaedge -n novaedge-system \
  --type=merge \
  -p '{"spec":{"version":"v0.2.0"}}'

Monitor the upgrade:

kubectl get novaedgecluster novaedge -n novaedge-system -w

Cluster Status¶

Check the status of your deployment:

kubectl describe novaedgecluster novaedge -n novaedge-system

Status fields:

Field	Description
`phase`	Pending, Initializing, Running, Upgrading, Degraded, Failed
`conditions`	Ready, ControllerReady, AgentReady, WebUIReady
`controller`	Controller deployment status
`agent`	Agent DaemonSet status
`webUI`	Web UI deployment status

Uninstalling¶

# Delete the cluster
kubectl delete novaedgecluster novaedge -n novaedge-system

# Uninstall the operator
helm uninstall novaedge-operator -n novaedge-system

# Optional: Remove CRDs
kubectl delete crd novaedgeclusters.novaedge.io

Troubleshooting¶

Operator Not Starting¶

kubectl describe pod -n novaedge-system -l app.kubernetes.io/name=novaedge-operator
kubectl logs -n novaedge-system -l app.kubernetes.io/name=novaedge-operator

Cluster Stuck in Initializing¶

# Check operator logs
kubectl logs -n novaedge-system -l app.kubernetes.io/name=novaedge-operator

# Check events
kubectl get events -n novaedge-system --sort-by='.lastTimestamp'

Components Not Ready¶

# Check component logs
kubectl logs -n novaedge-system -l app.kubernetes.io/component=controller
kubectl logs -n novaedge-system -l app.kubernetes.io/component=agent

Next Steps¶

Quick Start - Create your first gateway
Routing - Configure routes
VIP Management - Configure VIP modes
Observability - Set up monitoring