Quick Start

Get NovaEdge running in your Kubernetes cluster in under 5 minutes.

Prerequisites

• Kubernetes 1.29+
• kubectl configured
• Helm 3.0+

Step 1: Install NovaEdge

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

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

# Deploy NovaEdge cluster
kubectl apply -f - <<EOF
apiVersion: novaedge.io/v1alpha1
kind: NovaEdgeCluster
metadata:
  name: novaedge
  namespace: nova-system
spec:
  version: "v0.1.0"
  controller:
    replicas: 1
  agent:
    hostNetwork: true
    vip:
      enabled: true
      mode: L2
EOF

Step 2: Verify Installation

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

# Expected output:
# NAME                                    READY   STATUS    RESTARTS   AGE
# novaedge-operator-xxx                   1/1     Running   0          1m
# novaedge-controller-xxx                 1/1     Running   0          1m
# novaedge-agent-xxxxx                    1/1     Running   0          1m

Step 3: Create Your First Gateway

This example creates a complete load balancing setup:

flowchart LR
    Client((Client)) --> VIP{{"192.168.1.100"}}
    VIP --> GW["Gateway<br/>:80"]
    GW --> Route["Route<br/>app.example.com"]
    Route --> Backend["Backend"]
    Backend --> SVC["my-service:8080"]

3.1 Create a VIP

# Apply with: kubectl apply -f -
apiVersion: novaedge.io/v1alpha1
kind: ProxyVIP
metadata:
  name: my-vip
spec:
  address: 192.168.1.100/32
  mode: L2ARP

3.2 Create a Gateway

apiVersion: novaedge.io/v1alpha1
kind: ProxyGateway
metadata:
  name: my-gateway
spec:
  vipRef: my-vip
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    hostnames:
    - "*.example.com"

3.3 Create a Backend

apiVersion: novaedge.io/v1alpha1
kind: ProxyBackend
metadata:
  name: my-backend
spec:
  serviceRef:
    name: my-service
    port: 8080
  lbPolicy: RoundRobin
  healthCheck:
    interval: 10s
    httpHealthCheck:
      path: /health

3.4 Create a Route

apiVersion: novaedge.io/v1alpha1
kind: ProxyRoute
metadata:
  name: my-route
spec:
  parentRefs:
  - name: my-gateway
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRef:
      name: my-backend

Step 4: Test

# Test the endpoint
curl -H "Host: app.example.com" http://192.168.1.100/

# Or add to /etc/hosts and test directly
echo "192.168.1.100 app.example.com" | sudo tee -a /etc/hosts
curl http://app.example.com/

All-in-One Example

Apply everything at once:

# save as novaedge-example.yaml
---
apiVersion: novaedge.io/v1alpha1
kind: ProxyVIP
metadata:
  name: my-vip
spec:
  address: 192.168.1.100/32
  mode: L2ARP
---
apiVersion: novaedge.io/v1alpha1
kind: ProxyGateway
metadata:
  name: my-gateway
spec:
  vipRef: my-vip
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    hostnames:
    - "*.example.com"
---
apiVersion: novaedge.io/v1alpha1
kind: ProxyBackend
metadata:
  name: my-backend
spec:
  serviceRef:
    name: my-service
    port: 8080
  lbPolicy: RoundRobin
  healthCheck:
    interval: 10s
    httpHealthCheck:
      path: /health
---
apiVersion: novaedge.io/v1alpha1
kind: ProxyRoute
metadata:
  name: my-route
spec:
  parentRefs:
  - name: my-gateway
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRef:
      name: my-backend

kubectl apply -f novaedge-example.yaml

Using the CLI

NovaEdge includes novactl for management:

# Build the CLI
make build-novactl

# List resources
./novactl get gateways
./novactl get routes
./novactl get backends

# Check status
./novactl status

Next Steps

Topic	Description
Installation	Detailed installation options
Routing	Advanced routing configuration
Policies	Rate limiting, CORS, JWT auth
Observability	Metrics and tracing