Raftt - Cloud-Native Dev Mode for Kubernetes¶

Raftt is a developer experience tool that brings your code to the cluster - unlike tools that bring traffic to your machine. It provides instant file synchronization, live reloading, and remote debugging inside a real Kubernetes environment, giving you a localhost-like experience without leaving the cluster.

What will we learn?¶

• What Raftt is and how it differs from Telepresence and Skaffold
• How to install and configure the Raftt CLI
• Creating a .raftt environment definition for a Node.js application
• Deploying an entire dev environment with raftt up
• Live code sync - editing locally, updating instantly in the cluster
• Remote debugging a Node.js app with VS Code and --inspect
• Managing environment variables without redeploying Pods
• Troubleshooting sync conflicts and binary compatibility issues
• Cleaning up Raftt state and cluster resources

Official Documentation & References¶

Introduction¶

What is Raftt?¶

• Raftt is a Dev-Mode tool for Kubernetes that synchronizes your local source code into running containers inside the cluster
• Instead of rebuilding Docker images on every change, Raftt uses a high-performance file sync engine to push changes instantly
• Your application runs in the cluster with full access to other services, ConfigMaps, Secrets, and networking - but reloads as fast as if it were running on localhost

Architecture Overview¶

graph TD
    A[Developer Machine] --> B[Raftt CLI]
    B -->|File Sync Engine| C[kind Cluster]
    C --> D[Pod: backend<br/>Node.js + nodemon]
    C --> E[Other Services<br/>DB / Queue / API]
    D -->|"Hot Reload<br/>(nodemon detects changes)"| D
    B -->|"raftt dev / exec"| D

    style A fill:#667eea
    style B fill:#764ba2
    style C fill:#48bb78
    style D fill:#ed8936
    style E fill:#f6ad55

How Dev-Mode Sync Works¶

sequenceDiagram
    participant Dev as Developer (Local)
    participant CLI as Raftt CLI
    participant Pod as Container in Cluster

    Dev->>Dev: Save file locally
    Dev->>CLI: File watcher detects change
    CLI->>Pod: Sync changed files to /usr/src/app
    Pod->>Pod: nodemon detects change → restart
    Dev->>Pod: curl / browser → see updated response
    Note over Dev,Pod: Total latency: sub-second

Terminology¶

Key Features¶

Prerequisites¶

System Requirements¶

Installation¶

Step 01 - Create the kind Cluster¶

Use the provided setup script or create the cluster manually:

# Navigate to lab directory
cd Labs/38-Raftt

# Run the setup script (creates cluster + deploys app)
./setup.sh

Or manually:

# Create the kind cluster
kind create cluster --name raftt-lab --config resources/kind-config.yaml

# Verify cluster
kubectl cluster-info --context kind-raftt-lab

Step 02 - Install the Raftt CLI¶

brew install raftt/tap/raftt

# Verify installation
raftt version

curl -fsSL https://get.raftt.io | sh

# Verify installation
raftt version

Step 03 - Deploy the Application (Without Raftt)¶

Before using Raftt, let’s deploy the app the traditional way to see what we’re working with:

# Build the Docker image
docker build -t raftt-lab-backend:latest ./app

# Load the image into kind
kind load docker-image raftt-lab-backend:latest --name raftt-lab

# Deploy to the cluster
kubectl apply -f resources/01-namespace.yaml
kubectl apply -f resources/02-deployment.yaml
kubectl apply -f resources/03-service.yaml

# Wait for ready
kubectl wait --for=condition=ready pod -l app=backend -n raftt-lab --timeout=120s

# Test the app
kubectl port-forward -n raftt-lab svc/backend 3000:3000 &
curl http://localhost:3000/status

{
  "service": "raftt-lab-backend",
  "status": "healthy",
  "uptime": 12.345,
  "memory": {
    "rss": "45 MB",
    "heapUsed": "12 MB"
  }
}

The Application¶

Our backend is a Node.js Express application with three endpoints:

Application Architecture¶

graph LR
    Client[Client / curl] -->|HTTP :3000| Svc[Service: backend]
    Svc --> Pod[Pod: backend]
    Pod --> App["Express App<br/>/status<br/>/calculate<br/>/info"]

    style Client fill:#667eea
    style Svc fill:#48bb78
    style Pod fill:#ed8936
    style App fill:#f6ad55

Module 1: The “Up” Command¶

Step 01 - Understand the .raftt Configuration¶

The .raftt file is the brain of Raftt. It maps your local source code to the container:

# View the Raftt configuration
cat raftt.yaml

# raftt.yaml - Raftt Dev-Mode Configuration
version: "1"

# Environment name
name: raftt-lab

# Kubernetes context to use
context: kind-raftt-lab

# Namespace for the dev environment
namespace: raftt-lab

# Services to manage
services:
  backend:
    # Which deployment to target
    deployment: backend

    # Map local source → container path
    sync:
      - local: ./app
        remote: /usr/src/app
        exclude:
          - node_modules
          - .git

    # Override the container command for development
    command: ["npx", "nodemon", "--legacy-watch", "server.js"]

    # Ports to expose
    ports:
      - local: 3000
        remote: 3000
      - local: 9229
        remote: 9229

    # Environment variable overrides for dev
    env:
      NODE_ENV: development
      LOG_LEVEL: debug

Step 02 - Launch Dev-Mode¶

# Start the Raftt environment
raftt up

✔ Connected to cluster kind-raftt-lab
✔ Namespace raftt-lab ready
✔ Deployment backend patched for dev-mode
✔ File sync started: ./app → /usr/src/app
✔ Port forwarding: localhost:3000 → backend:3000
✔ Port forwarding: localhost:9229 → backend:9229

🚀 Dev-Mode active - edit locally, changes sync instantly

Step 03 - Verify Dev-Mode¶

# Test the running application
curl http://localhost:3000/status

# Check the info endpoint (should show NODE_ENV=development)
curl http://localhost:3000/info

Module 2: Live Code Sync¶

Step 01 - Make a Visible Change¶

Edit the /status endpoint to add a custom field:

# Open the app source in your editor
code app/server.js

Find the /status endpoint and add a lab field:

// In app/server.js - modify the /status handler
app.get('/status', (req, res) => {
  const memUsage = process.memoryUsage();
  res.json({
    service: 'raftt-lab-backend',
    lab: 'Raftt Dev-Mode Lab 38',     // ← ADD THIS LINE
    status: 'healthy',
    uptime: process.uptime(),
    memory: {
      rss: `${Math.round(memUsage.rss / 1024 / 1024)} MB`,
      heapUsed: `${Math.round(memUsage.heapUsed / 1024 / 1024)} MB`,
    },
  });
});

Step 02 - Watch the Sync¶

As soon as you save the file, watch the Raftt output:

[sync] app/server.js → /usr/src/app/server.js (0.02s)
[nodemon] restarting due to changes...
[nodemon] starting `node server.js`
Server listening on port 3000

Step 03 - Verify the Change¶

# Hit the endpoint - the new field should appear instantly
curl http://localhost:3000/status | jq .

{
  "service": "raftt-lab-backend",
  "lab": "Raftt Dev-Mode Lab 38",
  "status": "healthy",
  "uptime": 2.456,
  "memory": {
    "rss": "45 MB",
    "heapUsed": "12 MB"
  }
}

Module 3: Remote Debugging¶

Step 01 - Trigger the Bug¶

# This should work
curl -X POST http://localhost:3000/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 2, "operation": "divide"}'

# This will trigger the bug
curl -X POST http://localhost:3000/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 0, "operation": "divide"}'

{
  "error": "Internal Server Error",
  "message": "Cannot divide by zero... or can we?"
}

Step 02 - Enable the Node.js Inspector¶

The Raftt config already exposes port 9229. Now start the process with --inspect:

# Use raftt dev to override the command with inspect enabled
raftt dev backend --command "node --inspect=0.0.0.0:9229 server.js"

Or update the raftt.yaml command to include the inspect flag:

services:
  backend:
    command: ["node", "--inspect=0.0.0.0:9229", "server.js"]

Then re-sync:

raftt up

Debugger listening on ws://0.0.0.0:9229/...
For help, see: https://nodejs.org/en/docs/inspector

Step 03 - Attach VS Code Debugger¶

Create or update .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Raftt (kind)",
      "type": "node",
      "request": "attach",
      "address": "127.0.0.1",
      "port": 9229,
      "localRoot": "${workspaceFolder}/app",
      "remoteRoot": "/usr/src/app",
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

1. Open VS Code
2. Go to Run and Debug (Ctrl+Shift+D / Cmd+Shift+D)
3. Select “Attach to Raftt (kind)”
4. Click the green play button

Step 04 - Set a Breakpoint and Debug¶

1. Open app/server.js in VS Code
2. Set a breakpoint on the line inside the /calculate POST handler
3. Trigger the bug again:

curl -X POST http://localhost:3000/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 0, "operation": "divide"}'

1. VS Code will pause at the breakpoint - inspect variables a, b, and operation
2. Step through the code to see where the division-by-zero occurs

Step 05 - Fix the Bug¶

Add a guard clause in app/server.js:

// In the /calculate POST handler, add this check before the division:
if (operation === 'divide' && b === 0) {
  return res.status(400).json({
    error: 'Bad Request',
    message: 'Division by zero is not allowed',
  });
}

Save the file - Raftt syncs it instantly. Test again:

curl -X POST http://localhost:3000/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 0, "operation": "divide"}'

{
  "error": "Bad Request",
  "message": "Division by zero is not allowed"
}

Module 4: Environment Variables¶

Step 01 - Check Current Environment¶

curl http://localhost:3000/info | jq .

{
  "version": "1.0.0",
  "nodeEnv": "development",
  "logLevel": "debug"
}

Step 02 - Update Environment Variables¶

Edit raftt.yaml to add or modify environment variables:

services:
  backend:
    env:
      NODE_ENV: development
      LOG_LEVEL: verbose          # ← Changed from "debug"
      FEATURE_FLAG_V2: "true"     # ← New variable

Apply the changes:

# Raftt detects config changes and updates the environment
raftt up

Step 03 - Verify the Update¶

curl http://localhost:3000/info | jq .

{
  "version": "1.0.0",
  "nodeEnv": "development",
  "logLevel": "verbose",
  "featureFlagV2": "true"
}

Troubleshooting¶

Common Issues¶

sync:
  - local: ./app
    remote: /usr/src/app
    exclude:
      - node_modules

command: ["npx", "nodemon", "--legacy-watch", "server.js"]

# Find and kill the process using the port
lsof -ti:3000 | xargs kill -9

# Restart raftt
raftt up

# Verify the kind cluster is running
kind get clusters

# Ensure kubectl context is correct
kubectl config use-context kind-raftt-lab

# Test connectivity
kubectl cluster-info --context kind-raftt-lab

# Force a full re-sync
raftt sync --reset

# Or restart dev-mode entirely
raftt down && raftt up

Best Practices¶

Clean Up¶

# Stop Raftt dev-mode
raftt down

# Delete the kind cluster and all state
kind delete cluster --name raftt-lab

# Or use the cleanup script
./cleanup.sh

Summary¶

Raftt vs. Traditional Development Loop¶

graph LR
    subgraph Traditional["Traditional (Slow)"]
        T1[Edit Code] --> T2[docker build]
        T2 --> T3[kind load]
        T3 --> T4[kubectl apply]
        T4 --> T5[Wait for Pod]
        T5 --> T6[Test]
    end

    subgraph Raftt["Raftt Dev-Mode (Fast)"]
        R1[Edit Code] --> R2[Auto-Sync]
        R2 --> R3[nodemon Restart]
        R3 --> R4[Test]
    end

    style T1 fill:#e53e3e
    style T6 fill:#e53e3e
    style R1 fill:#48bb78
    style R4 fill:#48bb78