DEV Community: Alain Airom (Ayrom)

Benchmarking Local AI: Building a llama.cpp vs. Ollama Comparison & Benchmarking App

Alain Airom (Ayrom) — Wed, 12 Aug 2026 17:19:56 +0000

Pros and cons of both tools provided by Bob!

Introduction

I’ve been reading and seeing blog posts regarding the virtues of llama.cpp versus Ollama. Myself, I'm an Ollama user since a long time. I decided to ask Bob to build a thorough comparison and if possible a benchmarking code. And amazingly, this is exactly what I got!

Bob didn’t just give me a static list of bullet points; he engineered a full-stack Flask application equipped with live environment probes, dynamic GGUF model discovery, and an asynchronous benchmarking engine to test real-time inference side by side.

System Architecture & Overview

To evaluate both backends objectively, Bob structured the system around a lightweight, single-page application (SPA) frontend paired with a Python/Flask REST backend.

┌─────────────────────────────────────────────────────┐
│  Browser (vanilla JS SPA)                           │
│  benchRun() → POST /api/bench → poll /api/bench/job │
└────────────────────┬────────────────────────────────┘
                     │ HTTP
┌────────────────────▼────────────────────────────────┐
│  Flask Backend (app.py)                             │
│  api_bench() → background worker thread              │
│  _run_bench_job() → _bench_ollama() / _bench_llamacpp│
└───────────┬───────────────────┬─────────────────────┘
            │ HTTP              │ Subprocess
┌───────────▼──────┐  ┌─────────▼────────────────────┐
│  Ollama Daemon   │  │  llama CLI / Dispatcher      │
│  localhost:11434 │  │  PATH / ~/.local/bin          │
│  /api/generate   │  │  llama cli -m … -p … -n …    │
└──────────────────┘  └──────────────────────────────┘

The application serves static comparison data, auto-detects installed local tools and .gguf model files, and executes isolated timing benchmarks.

# app.py: Core Flask Application Setup & Data Routes
from flask import Flask, jsonify, render_template, request
from flask_cors import CORS
import json, os, subprocess, threading, time

app = Flask(__name__)
CORS(app)

DATA_PATH  = os.path.join(os.path.dirname(__file__), "data", "comparison.json")
BENCH_PATH = os.path.join(os.path.dirname(__file__), "data", "bench_history.json")

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/data")
def api_data():
    with open(DATA_PATH, "r", encoding="utf-8") as fh:
        return jsonify(json.load(fh))

Interface & Local Tool Integration

Ollama: Frictionless Desktop & Daemon Workflows

Ollama provides an out-of-the-box desktop UI and background daemon process (localhost:11434). It simplifies model management into one-liner commands like ollama run and abstract model tags (e.g., ibm/granite4:3b).

The Flask backend probes the live Ollama daemon to discover currently pulled models:

@app.route("/api/probe/ollama")
def probe_ollama():
    result = {"installed": False, "version": None, "models": [], "error": None}

    # Check CLI presence
    try:
        proc = subprocess.run(["ollama", "--version"], capture_output=True, text=True, timeout=5)
        if "version" in proc.stdout.lower() or "version" in proc.stderr.lower():
            result["installed"] = True
    except FileNotFoundError:
        result["error"] = "ollama binary not found in PATH"
        return jsonify(result)

    # Fetch models via Ollama API
    try:
        req = urllib.request.Request("http://localhost:11434/api/tags")
        with urllib.request.urlopen(req, timeout=5) as resp:
            data = json.loads(resp.read().decode())
            result["models"] = [
                {
                    "name": m.get("name", ""),
                    "size_gb": round(m.get("size", 0) / 1e9, 2),
                    "quantization": m.get("details", {}).get("quantization_level", ""),
                }
                for m in data.get("models", [])
            ]
    except Exception as exc:
        result["error"] = f"Ollama API unreachable: {exc}"

    return jsonify(result)

llama.cpp: Granular Binary & Hardware Optimization

llama.cpp focuses on high-performance C/C++ execution with raw hardware access, custom quantizations (such as mxfp4, Q8_0, Q4_0, Q4_K_M), and multi-command dispatchers (llama cli).

Bob built a scanner into app.py to auto-discover GGUF weights stored across local Hugging Face caches, custom folders, and system directories:

@app.route("/api/probe/llamacpp/models")
def probe_llamacpp_models():
    models = []
    search_dirs = [
        os.path.expanduser("~/.cache/huggingface/hub"),
        os.path.expanduser("~/models"),
        os.path.expanduser("~/Downloads"),
    ]

    for d in search_dirs:
        if not os.path.isdir(d):
            continue
        for dirpath, _, files in os.walk(d):
            for fname in files:
                if fname.lower().endswith(".gguf"):
                    full = os.path.join(dirpath, fname)
                    models.append({
                        "name": fname,
                        "path": full,
                        "size_gb": round(os.path.getsize(full) / 1e9, 2)
                    })
    return jsonify({"models": models})

Benchmarking Inference: Streaming vs. Subprocess Parsing

The primary technical challenge in comparing both systems is capturing accurate, equivalent performance metrics:

Tokens Per Second (TPS): Generation throughput.
Time to First Token (TTFT): Perceived initial latency.
Prompt Evaluation Time: Time required to ingest input tokens.

Ollama Streaming Runner

Bob used Ollama’s HTTP streaming API to capture the exact timestamp of the first token chunk received:

def _bench_ollama(model: str, prompt: str, n_predict: int) -> dict:
    url = "http://localhost:11434/api/generate"
    payload = {
        "model": model,
        "prompt": prompt,
        "stream": True,
        "options": {"num_predict": n_predict},
    }

    t_start = time.monotonic()
    t_first_token = None
    total_tokens = 0
    eval_duration_ns = 0

    resp = requests.post(url, json=payload, stream=True, timeout=300)
    for raw_line in resp.iter_lines():
        if not raw_line: continue
        chunk = json.loads(raw_line)

        # Capture TTFT on first non-empty response token
        if chunk.get("response") and t_first_token is None:
            t_first_token = time.monotonic()

        if chunk.get("done"):
            eval_duration_ns = chunk.get("eval_duration", 0)
            total_tokens = chunk.get("eval_count", 0)
            break

    t_end = time.monotonic()
    eval_ms = eval_duration_ns / 1_000_000 if eval_duration_ns else None
    tps = (total_tokens / (eval_ms / 1000)) if eval_ms else None

    return {
        "time_to_first_token_ms": round((t_first_token - t_start) * 1000, 2) if t_first_token else None,
        "total_time_ms": round((t_end - t_start) * 1000, 2),
        "tokens_per_second": round(tps, 2) if tps else None,
        "tokens_generated": total_tokens,
    }

llama.cpp Native Dispatcher Runner

For llama.cpp, the app executes the CLI binary via subprocess.Popen with safe pipe draining to avoid deadlock buffers, parsing standard timing blocks (llama_print_timings):

def _bench_llamacpp(model: str, prompt: str, n_predict: int) -> dict:
    cli_path, _ = _find_llama_cli()
    cmd = [
        cli_path, "cli",
        "-m", model,
        "-p", prompt,
        "-n", str(n_predict),
        "--no-conversation",
        "--single-turn",
        "--reasoning", "off",
        "--log-disable", "-e"
    ]

    t_start = time.monotonic()
    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
    stdout, stderr = proc.communicate(timeout=300)
    t_end = time.monotonic()

    combined = stdout + "\n" + stderr

    # Extract timings from llama_print_timings log output
    load_ms   = _parse_ms(r"load time\s*=\s*([\d.]+)\s*ms", combined)
    prompt_ms = _parse_ms(r"prompt eval time\s*=\s*([\d.]+)\s*ms", combined)
    eval_tps  = _parse_tps(r"eval time.*?([\d.]+)\s*tokens per second", combined)

    ttft_ms = (load_ms + prompt_ms) if (load_ms and prompt_ms) else prompt_ms

    return {
        "time_to_first_token_ms": round(ttft_ms, 2) if ttft_ms else None,
        "total_time_ms": round((t_end - t_start) * 1000, 2),
        "tokens_per_second": round(eval_tps, 2) if eval_tps else None,
        "command": " ".join(cmd),
    }

Key Takeaways & Comparison Matrix

Here is how the two stack up across core technical categories:

## Key Takeaways & Comparison Matrix

Here is how the two stack up across core technical categories:

| Dimension               | llama.cpp                                                    | Ollama                                                    |
| ----------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| **Architecture**        | C/C++ native backend engine                                  | Go wrapper daemon around custom `llama.cpp` builds        |
| **User Experience**     | CLI flags, config scripts, manual GGUF management            | Single binary / desktop app with REST API & model pulls   |
| **Model Discovery**     | Direct GGUF loading from disk or HF cache                    | Centralized model library registry (`ollama pull`)        |
| **Performance Control** | Unrestricted access to context sizing, GPU offloading, threads | Curated defaults optimized for ease of use                |
| **Ideal For**           | Custom pipelines, maximum hardware tuning, offline GGUFs     | Rapid prototyping, web wrappers, hassle-free agent setups |

Conclusion

Bob’s comparison application made it easy to test and quantify the trade-offs between both tools right on my local machine.

I will continue to use ollama, it’s handy, but I’ll use more heavily llama.cpp now that I’ve installed it and begining using it.

>>> Thanks for reading <<<

Implementing A Simple MCP Hook: From Zero to Stdio-Connected Tools

Alain Airom (Ayrom) — Mon, 10 Aug 2026 09:42:07 +0000

An introduction to MCP Hooks!

Introduction

The Model Context Protocol (MCP) has quickly become a standard for bridging Large Language Models with external tools, APIs, and data sources. While the protocol itself handles structured JSON-RPC messaging under the hood, seeing a end-to-end integration come together using a local stdio process — a setup often referred to as an MCP Hook or integration — is remarkably straight-forward.

In this post, we’ll walk through building a custom MCP server in TypeScript, registering tools with schema validation, and wiring up a Node.js client to spawn, negotiate, and execute tool calls end-to-end.

TL;DR-What is an MCP Hook? An Architectural Definition

At its core, a Model Context Protocol (MCP) Hook is an integration pattern that bridges a Large Language Model (LLM) host with external execution environments. While LLMs excel at reasoning, they operate in isolation from live data and system state. MCP solves this by establishing a standardized protocol for tool discovery, context injection, and function calling.

The term MCP Hook specifically describes the runtime linkage and communication channel established between the client application (the MCP Host) and a background tool server (the MCP Server):

Protocol Framing: Rather than making remote network calls over HTTP/REST, local MCP hooks typically leverage low-latency process communication (such as standard I/O streams: stdin and stdout).
Deterministic Delegation: The client process spawns the tool server as a child process, negotiates capabilities via a structured JSON-RPC 2.0 handshake, and dynamically dispatches function calls based on the model’s intent.
Process Isolation: By decoupling tool execution into a separate runtime process, the hook ensures that file I/O, API calls, or hardware manipulations happen safely outside the primary host application thread.

In essence, an MCP Hook transforms an LLM from a passive text-generation engine into an active agent capable of deterministically inspecting time, querying databases, executing shell operations, or interacting with host resources.

Implementation-System Architecture & Lifecycle

**An MCP Hook **connection over standard input/output (stdio) operates through a parent-child process relationship:

Host/Client Initialization: The client process spawns the MCP server executable as a child process.
Protocol Handshake: Standard I/O streams (stdin/stdout) frame JSON-RPC 2.0 requests to negotiate capacities and versions.
Tool Discovery & Call: The client queries available capabilities (listTools) and executes handlers (callTool).
Graceful Teardown: Closing the transport terminates the child process safely.

Server Implementation: Schemas & Tool Handlers

The server uses @modelcontextprotocol/sdk alongside zod to enforce strict parameter schemas before any tool handler is invoked.

Tip: When using a stdio transport, never output logging or debugging messages to console.log on the server. Doing so corrupts the stdout JSON-RPC message framing. Always redirect operational logs to console.error.

Server Entry Point (index.ts);

#!/usr/bin/env node
/**
 * mcp-hook-server — Demonstration MCP Server
 *
 * Exposes three tools:
 *   - echo        : returns the input message back
 *   - current-time: returns the current server date/time in the requested timezone
 *   - random-joke : returns a random programming joke
 *
 * Transport: stdio (spawned by an MCP host such as Bob)
 */
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// ─── Joke dataset ────────────────────────────────────────────────────────────
const JOKES = [
    "Why do programmers prefer dark mode? Because light attracts bugs.",
    "A SQL query walks into a bar, walks up to two tables and asks… 'Can I join you?'",
    "How many programmers does it take to change a light bulb? None — that's a hardware problem.",
    "Why do Java developers wear glasses? Because they don't C#.",
    "There are 10 types of people in the world: those who understand binary and those who don't.",
    "A byte walks into a bar looking pale. The barman asks: 'What's wrong?' It replies: 'I had a bit removed.'",
    "Why was the developer unhappy at their job? They wanted arrays.",
    "I would tell you a UDP joke, but you might not get it.",
];
// ─── Server setup ─────────────────────────────────────────────────────────────
const server = new McpServer({
    name: "mcp-hook-server",
    version: "0.1.0",
});
// ─── Tool: echo ──────────────────────────────────────────────────────────────
server.registerTool("echo", {
    description: "Echoes back the provided message. Useful for verifying that the MCP hook is working end-to-end.",
    inputSchema: z.object({
        message: z.string().describe("The message to echo back"),
    }),
}, async ({ message }) => {
    return {
        content: [
            {
                type: "text",
                text: `[MCP echo] ${message}`,
            },
        ],
    };
});
// ─── Tool: current-time ───────────────────────────────────────────────────────
server.registerTool("current-time", {
    description: "Returns the current date and time on the server.",
    inputSchema: z.object({
        timezone: z
            .string()
            .optional()
            .describe("IANA timezone name (e.g. 'Europe/Paris'). Defaults to UTC."),
        format: z
            .enum(["iso", "human"])
            .optional()
            .describe("Output format: 'iso' (default) or 'human'-readable."),
    }),
}, async ({ timezone, format }) => {
    const tz = timezone ?? "UTC";
    const fmt = format ?? "iso";
    let result;
    try {
        const now = new Date();
        if (fmt === "human") {
            result = now.toLocaleString("en-US", {
                timeZone: tz,
                dateStyle: "full",
                timeStyle: "long",
            });
        }
        else {
            result = now
                .toLocaleString("sv-SE", { timeZone: tz })
                .replace(" ", "T");
        }
    }
    catch {
        return {
            content: [
                {
                    type: "text",
                    text: `Unknown timezone: '${tz}'. Please use a valid IANA timezone name.`,
                },
            ],
            isError: true,
        };
    }
    return {
        content: [{ type: "text", text: result }],
    };
});
// ─── Tool: random-joke ────────────────────────────────────────────────────────
server.registerTool("random-joke", {
    description: "Returns a random programming or developer joke.",
    inputSchema: z.object({}),
}, async () => {
    const joke = JOKES[Math.floor(Math.random() * JOKES.length)];
    return {
        content: [{ type: "text", text: joke }],
    };
});
// ─── Start ────────────────────────────────────────────────────────────────────
async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error("mcp-hook-server running on stdio");
}
main().catch((error) => {
    console.error("Fatal error in mcp-hook-server:", error);
    process.exit(1);
});

Client Driver & Verification

To test the hook, the client process uses StdioClientTransport to target the compiled server binary (build/index.js), list the registered tools, and execute them.

- Client Script (index.js);

/**
 * mcp-hook-client — Demonstration MCP Client
 *
 * Spawns mcp-hook-server via stdio transport, discovers all available tools,
 * then calls each tool once to show an end-to-end MCP hook in action.
 *
 * Run: node src/index.js
 */

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import path from "node:path";
import { fileURLToPath } from "node:url";

// ─── Resolve absolute path to the built server ────────────────────────────────

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const SERVER_PATH = path.resolve(
  __dirname,
  "../../mcp-hook-server/build/index.js"
);

// ─── Helpers ──────────────────────────────────────────────────────────────────

function banner(title) {
  const line = "─".repeat(60);
  console.log(`\n${line}`);
  console.log(`  ${title}`);
  console.log(`${line}`);
}

function printResult(toolName, result) {
  const text = result?.content
    ?.filter((c) => c.type === "text")
    .map((c) => c.text)
    .join("\n");
  console.log(`[${toolName}] →`, text ?? JSON.stringify(result));
}

// ─── Main demo ────────────────────────────────────────────────────────────────

async function main() {
  banner("MCP Hook Demo — Client connecting to mcp-hook-server");

  // 1. Create client
  const client = new Client({
    name: "mcp-hook-client",
    version: "0.1.0",
  });

  // 2. Create stdio transport — spawns the server as a child process
  const transport = new StdioClientTransport({
    command: "node",
    args: [SERVER_PATH],
  });

  // 3. Connect
  console.log("\n[client] Connecting to server…");
  await client.connect(transport);
  console.log("[client] Connected ✓");

  // 4. List available tools
  const { tools } = await client.listTools();
  console.log(
    `\n[client] Server exposes ${tools.length} tool(s):`,
    tools.map((t) => t.name).join(", ")
  );

  // ── Demo: echo ──────────────────────────────────────────────────────────────
  banner("Tool demo: echo");
  const echoResult = await client.callTool({
    name: "echo",
    arguments: { message: "Hello from the MCP client!" },
  });
  printResult("echo", echoResult);

  // ── Demo: current-time (ISO, UTC) ────────────────────────────────────────────
  banner("Tool demo: current-time (ISO / UTC)");
  const timeIso = await client.callTool({
    name: "current-time",
    arguments: {},
  });
  printResult("current-time", timeIso);

  // ── Demo: current-time (human, Paris) ────────────────────────────────────────
  banner("Tool demo: current-time (human / Europe/Paris)");
  const timeParis = await client.callTool({
    name: "current-time",
    arguments: { timezone: "Europe/Paris", format: "human" },
  });
  printResult("current-time", timeParis);

  // ── Demo: random-joke ────────────────────────────────────────────────────────
  banner("Tool demo: random-joke");
  const joke = await client.callTool({ name: "random-joke", arguments: {} });
  printResult("random-joke", joke);

  // 5. Disconnect
  await client.close();
  console.log("\n[client] Disconnected. Demo complete ✓\n");
}

main().catch((err) => {
  console.error("Demo client error:", err);
  process.exit(1);
});

Overall Test Script

To test the implementation, we can run a small test script.

- Test Script (test.js);

/**
 * mcp-hook-client — Unit Tests
 *
 * Spawns the real mcp-hook-server and exercises every tool.
 * Exit code 0 = all passed. Exit code 1 = one or more failures.
 *
 * Run: node src/test.js
 */

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const SERVER_PATH = path.resolve(
  __dirname,
  "../../mcp-hook-server/build/index.js"
);

// ─── Tiny test harness ────────────────────────────────────────────────────────

let passed = 0;
let failed = 0;

function assert(condition, label) {
  if (condition) {
    console.log(`  ✓ ${label}`);
    passed++;
  } else {
    console.error(`  ✗ ${label}`);
    failed++;
  }
}

function getText(result) {
  return result?.content
    ?.filter((c) => c.type === "text")
    .map((c) => c.text)
    .join("\n") ?? "";
}

// ─── Tests ────────────────────────────────────────────────────────────────────

async function runTests(client) {
  // ── listTools ────────────────────────────────────────────────────────────────
  console.log("\n[suite] listTools");
  const { tools } = await client.listTools();
  const names = tools.map((t) => t.name);
  assert(names.includes("echo"), "exposes 'echo' tool");
  assert(names.includes("current-time"), "exposes 'current-time' tool");
  assert(names.includes("random-joke"), "exposes 'random-joke' tool");
  assert(tools.length === 3, "exposes exactly 3 tools");

  // ── echo ─────────────────────────────────────────────────────────────────────
  console.log("\n[suite] echo");
  const echo1 = await client.callTool({
    name: "echo",
    arguments: { message: "test-payload" },
  });
  assert(
    getText(echo1) === "[MCP echo] test-payload",
    "echoes message with prefix"
  );
  assert(!echo1.isError, "echo returns no error flag");

  const echoEmpty = await client.callTool({
    name: "echo",
    arguments: { message: "" },
  });
  assert(getText(echoEmpty) === "[MCP echo] ", "echoes empty string correctly");

  // ── current-time ─────────────────────────────────────────────────────────────
  console.log("\n[suite] current-time");
  const timeUtc = await client.callTool({
    name: "current-time",
    arguments: {},
  });
  const utcText = getText(timeUtc);
  assert(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(utcText), "UTC ISO format matches yyyy-mm-ddThh:mm");
  assert(!timeUtc.isError, "current-time UTC returns no error flag");

  const timeHuman = await client.callTool({
    name: "current-time",
    arguments: { timezone: "America/New_York", format: "human" },
  });
  assert(!timeHuman.isError, "human format (America/New_York) returns no error");
  assert(getText(timeHuman).length > 0, "human format returns non-empty string");

  const timeBad = await client.callTool({
    name: "current-time",
    arguments: { timezone: "Not/AReal_Zone" },
  });
  assert(timeBad.isError === true, "invalid timezone sets isError=true");

  // ── random-joke ───────────────────────────────────────────────────────────────
  console.log("\n[suite] random-joke");
  const joke1 = await client.callTool({ name: "random-joke", arguments: {} });
  assert(!joke1.isError, "random-joke returns no error flag");
  assert(getText(joke1).length > 0, "random-joke returns non-empty text");

  // Ensure it can return at least two different jokes across 20 calls (non-deterministic — might rarely fail)
  const jokeSamples = new Set();
  for (let i = 0; i < 20; i++) {
    const r = await client.callTool({ name: "random-joke", arguments: {} });
    jokeSamples.add(getText(r));
  }
  assert(jokeSamples.size > 1, "random-joke returns more than one unique joke across 20 calls");
}

// ─── Bootstrap ────────────────────────────────────────────────────────────────

async function main() {
  console.log("=== mcp-hook unit tests ===");

  const client = new Client({ name: "mcp-hook-test-client", version: "0.1.0" });
  const transport = new StdioClientTransport({
    command: "node",
    args: [SERVER_PATH],
  });
  await client.connect(transport);

  try {
    await runTests(client);
  } finally {
    await client.close();
  }

  console.log(`\n=== Results: ${passed} passed, ${failed} failed ===\n`);
  if (failed > 0) process.exit(1);
}

main().catch((err) => {
  console.error("Test runner error:", err);
  process.exit(1);
});

Which provides a log file validating the whole logic of the implementation.

────────────────────────────────────────────────────────────
  MCP Hook Demo — Client connecting to mcp-hook-server
────────────────────────────────────────────────────────────

[client] Connecting to server…
mcp-hook-server running on stdio
[client] Connected ✓

[client] Server exposes 3 tool(s): echo, current-time, random-joke

────────────────────────────────────────────────────────────
  Tool demo: current-time (human / Europe/Paris)
────────────────────────────────────────────────────────────
[current-time] → Monday, August 10, 2026 at 9:49:46 AM GMT+2

[client] Disconnected. Demo complete ✓

Integration into MCP Hosts (e.g., Bob)

Once compiled, registering your new custom server inside an agent or workspace host like Bob requires registering the process entry in .bob/mcp.json:

{
  "mcpServers": {
    "mcp-hook-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-hook-server/build/index.js"]
    }
  }
}

This makes echo, current-time, and random-joke directly available to the AI assistant as native tool primitives during chat sessions.

Conclusion: Implementing Your First MCP Hook

Implementing your first MCP Hook demonstrates how remarkably clean decoupled LLM integrations can be. By relying on lightweight stdio transports, process isolation, and standard schemas via zod, you keep your tool logic testable, language-agnostic, and completely independent of any specific client UI or host framework.

Building local MCP hooks gives you full control over tool security, deterministic execution, and process lifecycle management — laying a solid foundation for scaling up to complex agentic workflows.

Thanks for reading 🪝

Book Review & Technical Implementation: Kubernetes in Action, Second Edition

Alain Airom (Ayrom) — Wed, 05 Aug 2026 13:46:04 +0000

Book review: Kubernetes in Action, Second Edition from Manning

🚀 Introduction

Back to back to some of my initial technical interests, I think this book deserves a fine review. This book took very long to be published from MEAP to completion, and it was probably worth it!

When Marko Lukša released the first edition of Kubernetes in Action back in 2017, it rapidly established itself as the gold standard text for mastering container orchestration. However, over the past decade, the Kubernetes ecosystem has undergone significant evolution: legacy container engines yielded to OCI standards via containerd and CRI-O, standard Ingress resources expanded into the modular Gateway API, storage plugins consolidated around the Container Storage Interface (CSI), and sidecar helper patterns evolved into first-class native primitives.

Enter the Second Edition, co-authored by Marko Lukša alongside Red Hat engineering leader Kevin Conner. Spanning 18 chapters across 5 cohesive parts, this edition does not merely refresh code samples — it completely rebuilds the narrative around modern development patterns on modern Kubernetes.

Quick Disclaimers:
No Sponsorship: I’m not affiliated with Manning or the authors in any way — just sharing a review.
Fun Note: Big fan of the original illustrations in the book — always refreshing to see real artwork instead of AI-generated visuals!

Following the initial deep-dive analysis of the book per se, I tasked Bob with digesting the material, mapping out an architectural diagram of its structure, and building a full end-to-end demo application based on the code from the book’s official GitHub repository (Image blow provided by Bob).

🏗️ Part 1-Chapter Analysis & Breakdown

Getting Started & Core Architecture (Chapters 1–4)

What sets this book apart right from the opening pages is how the authors refuse to treat Kubernetes as a black box. Instead of just giving you commands to run, they take you back to Google’s Borg origins and walk you through how the system is actually wired under the hood.

Chapter 1: Introducing Kubernetes — The authors unpack cluster topology by showing how Kubernetes cleanly splits responsibilities. The Control Plane handles intelligence (kube-apiserver, etcd, kube-scheduler, and kube-controller-manager), while the Workload Plane does the actual heavy lifting via worker nodes running kubelet, kube-proxy, and an OCI runtime.

+-----------------------------------+
                      |      KUBERNETES CONTROL PLANE     |
                      |  +--------+ +-------------------+ |
                      |  |  etcd  | |  kube-apiserver   | |
                      |  +--------+ +-------------------+ |
                      |  +-----------+ +----------------+ |
                      |  | scheduler | | controllers    | |
                      |  +-----------+ +----------------+ |
                      +------------------+----------------+
                                         | RESTful API
               +-------------------------+-------------------------+
               |                                                   |
  +------------v------------+                         +------------v------------+
  |  WORKER NODE 1          |                         |  WORKER NODE 2          |
  |  +--------------------+ |                         |  +--------------------+ |
  |  |      Kubelet       | |                         |  |      Kubelet       | |
  |  +--------------------+ |                         |  +--------------------+ |
  |  | kube-proxy | CRI   | |                         |  | kube-proxy | CRI   | |
  |  +------------+-------+ |                         |  +------------+-------+ |
  |  [ Pod A ]  [ Pod B ]   |                         |  [ Pod C ]  [ Pod D ]   |
  +-------------------------+-------------------------+-------------------------+

Chapter 2: Containers & Linux Primitives — I really appreciate that Chapter 2 doesn’t jump straight into Kubernetes abstractions. It grounds you in low-level Linux kernel primitives — specifically Namespaces (for process, mount, and network isolation) and Control Groups (cgroups) (for CPU and memory limits). To make everything hands-on, the authors introduce Kiada (Kubernetes in Action Demo Application), a simple Node.js microservice used throughout the book:

# Chapter 2: Minimal Dockerfile for Kiada Demo Application
FROM node:23-alpine
COPY app.js /app.js
COPY html/ /html
ENTRYPOINT ["node", "app.js"]

Chapter 3: First Deployments — Here, you get your hands dirty spinning up local environments like Kind or Minikube before moving toward cloud clusters like GKE or EKS. You learn how kubectl interacts imperatively with the cluster before diving into declarative files (images from the book):

# Imperatively creating a Pod and exposing it via a Service
kubectl run kiada --image=luksa/kiada:0.1 --port=8080
kubectl expose pod kiada --type=NodePort --port=8080

Chapter 4: API & Object Model — This chapter hits on a fundamental mental model shift: understanding the REST API structure and the core distinction between the desired state (spec) and the observed state (status).

# Chapter 4: Declarative Object Manifest Structure
apiVersion: v1
kind: Pod
metadata:
  name: kiada-demo
  labels:
    app: kiada
spec:
  containers:
  - name: kiada-container
    image: luksa/kiada:0.1

Running Applications in Kubernetes (Chapters 5–7)

Once you understand the API, Part 2 dives into the atom of Kubernetes: the Pod.

Chapter 5: Pods — Instead of viewing containers as isolated units, the authors illustrate why containers inside the same Pod share the net and ipc namespaces. This enables tight co-location, shared localhost networking, and multi-container patterns like helper sidecars or init containers:

# Chapter 5: Multi-Container Pod with an Init Container and Main App
apiVersion: v1
kind: Pod
metadata:
  name: kiada-init-demo
spec:
  initContainers:
  - name: init-html
    image: busybox:1.36
    command: ['sh', '-c', 'echo "<h1>Welcome to Kiada</h1>" > /usr/share/nginx/html/index.html']
    volumeMounts:
    - name: html-vol
      mountPath: /usr/share/nginx/html
  containers:
  - name: web-server
    image: nginx:alpine
    volumeMounts:
    - name: html-vol
      mountPath: /usr/share/nginx/html
  volumes:
  - name: html-vol
    emptyDir: {}

Chapter 6: Pod Lifecycle & Health — This chapter is absolute gold for anyone who has ever debugged cascading failures in production. It covers the exact mechanics of Startup, Liveness, and Readiness probes, ensuring your app doesn’t receive traffic until it’s ready and gets restarted if it deadlocks:

# Chapter 6: Pod Manifest with Liveness, Readiness, and Startup Probes
apiVersion: v1
kind: Pod
metadata:
  name: kiada-healthy
  labels:
    app: kiada
    env: production
spec:
  containers:
  - name: kiada
    image: luksa/kiada:0.2
    ports:
    - containerPort: 8080
    startupProbe:
      httpGet:
        path: /
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /readiness
        port: 8080
      periodSeconds: 5

Chapter 7: Organization — As the clusters grows, keeping things organized becomes critical. This chapter explains how to group objects logically using Namespaces and query them cleanly using key-value Labels and Selectors (image from the book):

# Querying pods dynamically using label selectors
kubectl get pods -l app=kiada,env=production --namespace=default

Application Configuration & Storage (Chapters 8–10)

Building cloud-native apps means keeping them stateless and configuration-agnostic. Part 3 walks through how Kubernetes lets you inject configuration and attach storage seamlessly.

Chapter 8: Configuration — Here we learn how to decouple application logic from environment specifics using ConfigMap, inject sensitive items with Secret, and expose runtime cluster metadata back to the container via the Downward API (images from the book):

# Chapter 8: Injecting ConfigMap and Secret values as Environment Variables
apiVersion: v1
kind: Pod
metadata:
  name: kiada-config-demo
spec:
  containers:
  - name: kiada
    image: luksa/kiada:0.3
    env:
    - name: INITIAL_STATUS
      valueFrom:
        configMapKeyRef:
          name: kiada-config
          key: status.message
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: kiada-secret
          key: password

Chapter 9: Volumes — This chapter covers temporary volume types like emptyDir, host filesystem access with hostPath, and mounting configuration maps directly as filesystem files (image from the book):

# Chapter 9: Mounting a ConfigMap as a Volume
apiVersion: v1
kind: Pod
metadata:
  name: kiada-volume-demo
spec:
  containers:
  - name: kiada
    image: luksa/kiada:0.3
    volumeMounts:
    - name: config-volume
      mountPath: /etc/kiada
  volumes:
  - name: config-volume
    configMap:
      name: kiada-config

Chapter 10: Persistent Storage — The authors unpack the separation between persistent storage requests (PersistentVolumeClaim) and actual cluster storage backends (PersistentVolume) backed by CSI drivers:

[ Pod Spec ] ──( PVC Reference )──> [ PersistentVolumeClaim ]
                                           │ (Dynamic Provisioning)
                                           ▼
                                 [ PersistentVolume ] ──> [ Physical / Cloud Storage (CSI) ]

# Chapter 10: Dynamically Provisioned Storage via PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: quiz-data-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 2Gi
  storageClassName: standard

Connecting & Exposing Applications (Chapters 11–13)

Part 4 is one of the most rewarding parts of the book, taking you step-by-step from internal pod communication all the way to modern traffic management.

Chapter 11: Services — Pods are ephemeral, meaning their IP addresses change constantly. Services provide a stable virtual IP (ClusterIP), NodePort bindings, or cloud LoadBalancers to front your workloads, powered by internal DNS:

# Chapter 11: Service Manifest for Internal Cluster Routing
apiVersion: v1
kind: Service
metadata:
  name: kiada-service
spec:
  type: ClusterIP
  selector:
    app: kiada
  ports:
  - port: 80
    targetPort: 8080

Chapter 12: Ingress — When Layer 7 HTTP routing is needed, path matching, and SSL termination, standard Ingress steps in:

# Chapter 12: Classic Ingress Resource Manifest
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kiada-ingress
spec:
  rules:
  - host: kiada.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kiada-service
            port:
              number: 80

Chapter 13: Gateway API — This is a standout chapter! The authors provide an extensive, modern guide to the Gateway API (GatewayClass, Gateway, HTTPRoute), explaining why it cleanly separates infrastructure owner roles from application developer routing needs:

[ External Client ]
         │
         ▼
[ Gateway: prod-gateway ] ◄── (GatewayClass: istio / envoy)
         │
         ├─── (HTTPRoute: kiada-route)  ──► [ Service: kiada-service ]
         │
         └─── (HTTPRoute: quote-route)  ──► [ Service: quote-service ]

# Chapter 13: Modern Traffic Split using Gateway API (HTTPRoute)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: kiada-route
  namespace: default
spec:
  parentRefs:
  - name: prod-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v1/quotes
    backendRefs:
    - name: quote-service-v1
      port: 8080
      weight: 80
    - name: quote-service-v2
      port: 8080
      weight: 20

Managing Applications at Scale (Chapters 14–18)

The final part transitions from running single pods to orchestrating complex, self-healing, scalable application stacks in production.

Chapter 14: ReplicaSets — What is the core reconciliation loop — how Kubernetes continuously compares desired replica counts against actual running pods and creates or deletes pods to match? Hereafter the path;

# Chapter 14: Declarative ReplicaSet Manifest
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: kiada-rs
spec:
  replicas: 3
  selector:
    matchLabels:
      app: kiada
  template:
    metadata:
      labels:
        app: kiada
    spec:
      containers:
      - name: kiada
        image: luksa/kiada:0.1

Chapter 15: Deployments — Deployments build on top of ReplicaSets to offer zero-downtime rolling updates, canary rollouts, quick rollbacks, and blue/green deployments:

# Chapter 15: Deployment Manifest with RollingUpdate Strategy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kiada-deployment
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: kiada
  template:
    metadata:
      labels:
        app: kiada
    spec:
      containers:
      - name: kiada
        image: luksa/kiada:0.2

Chapter 16: StatefulSets — When dealing with databases or distributed stateful systems, pods need unique, predictable identities (pod-0, pod-1) and dedicated persistent storage claims:

# Chapter 16: StatefulSet with VolumeClaimTemplates
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: quiz-db
spec:
  serviceName: "quiz-db-headless"
  replicas: 3
  selector:
    matchLabels:
      app: quiz-db
  template:
    metadata:
      labels:
        app: quiz-db
    spec:
      containers:
      - name: mongo
        image: mongo:7.0
        ports:
        - containerPort: 27017
        volumeMounts:
        - name: data
          mountPath: /data/db
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      resources:
        requests:
          storage: 5Gi

Chapter 17: DaemonSets — Covering how to run exact per-node daemon copies across your cluster for log collection, node monitoring, or network plugin management:

# Chapter 17: DaemonSet for Cluster-Wide Log Collector
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluentd-elasticsearch
spec:
  selector:
    matchLabels:
      name: fluentd-elasticsearch
  template:
    metadata:
      labels:
        name: fluentd-elasticsearch
    spec:
      containers:
      - name: fluentd-elasticsearch
        image: quay.io/fluentd_elasticsearch/fluentd:v2.5.2

Chapter 18: Batch Processing — Finally, the authors cover short-lived, completable workloads via Job and scheduled periodic executions with CronJob:

# Chapter 18: Scheduled Workload using CronJob
apiVersion: batch/v1
kind: CronJob
metadata:
  name: kiada-backup-job
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: luksa/kiada-backup:1.0
          restartPolicy: OnFailure

Throughout the chapters of the book, a demo application named Kiada is progressively built. In Part 2, IBM Bob takes those concepts a step further by implementing a brand-new ‘Kiada’ *application built entirely from scratch, using the original code excerpts from the book as a foundation (schema provided by Bob).

Part 2-Putting the book’s knwoledge in Pactice

Beyond analyzing the theoretical concepts of Kubernetes in Action, 2nd Edition per se, I worked with Bob to translate those patterns into a tangible, production-ready implementation.

Instead of leaving the book’s learnings as static code snippets, Bob built kiada-go—a complete Go re-implementation of the author's Node.js Kiada demo application—and deployed it to a local kind Kubernetes cluster following the exact architecture, health-probe, configuration, and networking patterns taught throughout the 18 chapters.

🛠️ Application Architecture & Deployment Flow

The target system is structured into a multi-tiered Kubernetes architecture running inside an isolated kiada namespace. It demonstrates external traffic ingress, service abstraction, dynamic scaling, and environmental metadata injection (schema provided by Bob).

🏗️ Key Components & Applied Patterns

Application Layer (kiada-go)

Minimalist Container Footprint: Compiled using a multi-stage Docker build (golang:1.21-alpine → alpine:3.19) into a lightweight binary running as an unprivileged system user (appuser).
# - - - - - build stage - - - - - 
FROM golang:1.21-alpine AS builder
WORKDIR /build
COPY go.mod ./
RUN go mod download
COPY *.go ./
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o kiada-go .

# - - - - - runtime stage - - - - - 
FROM alpine:3.19
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
WORKDIR /app
COPY - from=builder /build/kiada-go /app/kiada-go
USER appuser
EXPOSE 8080
ENTRYPOINT ["/app/kiada-go"]

This dockerfile is optimized based on my own recommendations for image building to illustrate multi-stage images, and is nit based on the book.

Graceful Termination (Chapter 6): Implements explicit SIGTERM / SIGINT signal catching in Go, giving active HTTP requests a 10-second grace window to finalize during rolling updates or pod teardowns.
Service Proxying (Chapter 11): Includes /proxy/quote and /proxy/quiz endpoints that forward requests to internal cluster microservices via DNS service discovery.

// main.go
package main

import (
  "context"
  "fmt"
  "log"
  "net/http"
  "os"
  "os/signal"
  "syscall"
  "time"
)

const appName = "kiada-go"
const version = "1.0"

func main() {
  listenPort := getEnv("LISTEN_PORT", "8080")
  addr := fmt.Sprintf(":%s", listenPort)

  logStartup(addr)

  srv := &http.Server{
    Addr:         addr,
    Handler:      newRouter(),
    ReadTimeout:  10 * time.Second,
    WriteTimeout: 15 * time.Second,
    IdleTimeout:  60 * time.Second,
  }

  // Run server in goroutine so shutdown handling works
  go func() {
    log.Printf("%s v%s listening on %s", appName, version, addr)
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
      log.Fatalf("ListenAndServe error: %v", err)
    }
  }()

  // Graceful shutdown on SIGTERM / SIGINT (matches Ch 6 SIGTERM handler pattern)
  quit := make(chan os.Signal, 1)
  signal.Notify(quit, syscall.SIGTERM, syscall.SIGINT)
  <-quit

  log.Printf("Received shutdown signal. Shutting down %s...", appName)
  ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
  defer cancel()

  if err := srv.Shutdown(ctx); err != nil {
    log.Fatalf("Server shutdown error: %v", err)
  }
  log.Printf("%s shut down cleanly.", appName)
}

func logStartup(addr string) {
  hostname, _ := os.Hostname()
  log.Printf("-------------------------------------------")
  log.Printf("%s v%s — Kubernetes in Action Demo (Go)", appName, version)
  log.Printf("-------------------------------------------")
  log.Printf("Pod name   : %s", getEnv("POD_NAME", hostname))
  log.Printf("Pod IP     : %s", getEnv("POD_IP", "0.0.0.0"))
  log.Printf("Node name  : %s", getEnv("NODE_NAME", "unknown"))
  log.Printf("Node IP    : %s", getEnv("NODE_IP", "0.0.0.0"))
  log.Printf("QUOTE_URL  : %s", getEnv("QUOTE_URL", "(not set)"))
  log.Printf("QUIZ_URL   : %s", getEnv("QUIZ_URL", "(not set)"))
  log.Printf("Listen addr: %s", addr)
}

Kubernetes Resource Mapping

The implementation translates key book chapters directly into declarative Kubernetes manifests:


| Manifest File        | Book Chapter(s)            | Architectural Function                                       |
| -------------------- | -------------------------- | ------------------------------------------------------------ |
| `00-namespace.yaml`  | **Chapter 7**              | Creates an isolated `kiada` namespace boundary for resource allocation and security scoping. |
| `01-configmap.yaml`  | **Chapter 8**              | Decouples non-sensitive settings (port bindings, status messages) from container images. |
| `02-deployment.yaml` | **Chapters 6, 8, 14 & 15** | Manages 3 pod replicas with zero-downtime `RollingUpdate`, `liveness`/`readiness` probes, and **Downward API** field refs (`POD_NAME`, `POD_IP`, `NODE_NAME`). |
| `03-service.yaml`    | **Chapter 11**             | Exposes stable internal IP routing via `ClusterIP` on port 80 and direct developer access via `NodePort` on 30880. |
| `04-ingress.yaml`    | **Chapter 12**             | Provides Layer 7 domain-based HTTP routing to internal services. |
| `05-hpa.yaml`        | **Chapters 14–15**         | Dynamically scales pod replicas between 2 and 10 based on CPU utilization metrics. |

Downward API & Runtime Injection (Chapter 8)

To allow the application to remain self-aware of its placement in the cluster without depending on direct API server queries, the deployment injects runtime metadata directly through environment variables:

# ── Deployment: kiada-go ──────────────────────────────────────────────────────
# Implements patterns from Chapters 8, 11, 15:
#   - Downward API env vars (Ch 8)
#   - ConfigMap env injection (Ch 8)
#   - Readiness probe /healthz/ready (Ch 6/11)
#   - Rolling update strategy (Ch 15)
#   - 3 replicas (Ch 14)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kiada-go
  namespace: kiada
  labels:
    app: kiada-go
    rel: stable
spec:
  replicas: 3
  selector:
    matchLabels:
      app: kiada-go
      rel: stable
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: kiada-go
        rel: stable
        ver: "1.0"
    spec:
      terminationGracePeriodSeconds: 30
      containers:
      - name: kiada-go
        image: ${REGISTRY}/kiada-go:1.0
        imagePullPolicy: IfNotPresent
        ports:
        - name: http
          containerPort: 8080
          protocol: TCP
        env:
        # Downward API — injects pod/node metadata (Chapter 8)
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        - name: NODE_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        # Service URLs injected via ConfigMap (Chapter 8)
        - name: QUOTE_URL
          value: "http://quote.kiada.svc.cluster.local/quote"
        - name: QUIZ_URL
          value: "http://quiz.kiada.svc.cluster.local"
        # Status message from ConfigMap (Chapter 8)
        - name: INITIAL_STATUS_MESSAGE
          valueFrom:
            configMapKeyRef:
              name: kiada-go-config
              key: INITIAL_STATUS_MESSAGE
        # Liveness probe — restart container if it stops responding (Chapter 6)
        livenessProbe:
          httpGet:
            path: /healthz/ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
          failureThreshold: 3
        # Readiness probe — only route traffic when ready (Chapter 6/11)
        readinessProbe:
          httpGet:
            path: /healthz/ready
            port: 8080
          initialDelaySeconds: 3
          periodSeconds: 5
          failureThreshold: 1
        resources:
          requests:
            cpu: "50m"
            memory: "32Mi"
          limits:
            cpu: "200m"
            memory: "64Mi"

# ── Ingress: kiada-go ─────────────────────────────────────────────────────────
# Routes external traffic to the kiada-go service (Chapter 12 Ingress pattern)
# Requires an IngressController (e.g. nginx-ingress) to be installed.
#
# Access via:
#   curl -H "Host: kiada-go.example.com" http://<node-ip>
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kiada-go
  namespace: kiada
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: kiada-go.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kiada-go
            port:
              name: http

⚡ Quick Verification

Once launched locally, the implementation can be queried to confirm proper pod self-awareness and readiness checks:

Deploy the application
#!/usr/bin/env bash
# ──────────────────────────────────────────────────────────────
# launch.sh — Build and deploy kiada-go to a local kind cluster
# Usage:  ./scripts/launch.sh [REGISTRY] [IMAGE_TAG]
# ──────────────────────────────────────────────────────────────
set -euo pipefail

REGISTRY="${1:-$(id -un)/kiada-go}"
IMAGE_TAG="${2:-1.0}"
IMAGE="${REGISTRY}:${IMAGE_TAG}"
CLUSTER_NAME="kiada"
PORT=30880

echo "==> Building kiada-go Docker image: ${IMAGE}"
docker build -t "${IMAGE}" ./kiada-go

echo "==> Loading image into kind cluster '${CLUSTER_NAME}'"
if ! kind get clusters 2>/dev/null | grep -q "^${CLUSTER_NAME}$"; then
  echo "==> Creating kind cluster '${CLUSTER_NAME}'"
  kind create cluster --name "${CLUSTER_NAME}"
fi
kind load docker-image "${IMAGE}" --name "${CLUSTER_NAME}"

echo "==> Patching deployment image reference"
# Replace the ${REGISTRY}/kiada-go:1.0 placeholder with the real image
sed "s|\${REGISTRY}/kiada-go:1.0|${IMAGE}|g" \
  kiada-go/k8s/02-deployment.yaml > /tmp/kiada-go-deploy-patched.yaml

echo "==> Applying Kubernetes manifests"
kubectl apply -f kiada-go/k8s/00-namespace.yaml
kubectl apply -f kiada-go/k8s/01-configmap.yaml
kubectl apply -f /tmp/kiada-go-deploy-patched.yaml
kubectl apply -f kiada-go/k8s/03-service.yaml

echo "==> Waiting for rollout to complete..."
kubectl rollout status deployment/kiada-go -n kiada --timeout=90s

URL="http://localhost:${PORT}"
echo ""
echo "────────────────────────────────────────────"
echo "  kiada-go is running!"
echo "  NodePort URL : ${URL}"
echo "  Health check : ${URL}/healthz/ready"
echo "  Pod info     : ${URL}/info"
echo "────────────────────────────────────────────"
echo ""
echo "To watch pods:"
echo "  kubectl get pods -n kiada -w"

# Check the application status endpoint
$ curl http://localhost:30880/

Hello from kiada-go v1.0!
Pod: kiada-go-7d84f89d97-x9z2l | Node: kind-worker
Pod IP: 10.244.0.5 | Node IP: 172.18.0.2
Status: Welcome to kiada-go on Kubernetes!

# Verify health probes
$ curl http://localhost:30880/healthz/ready
{"status":"ready","time":"2026-08-05T12:51:00Z"}

📙 Conclusion for the Book

For me, Kubernetes in Action, Second Edition is a triumph of technical writing. Marko Lukša and Kevin Conner have delivered a book that strikes an exquisite balance between low-level system engineering concepts and practical, developer-friendly paradigms.

By building out concepts sequentially — starting from bare Linux namespaces up to the Gateway API, StatefulSets, and Custom Operators — the authors ensure readers build a deep, intuitive mental model of Kubernetes rather than merely memorizing command-line syntax.

For developers, SREs, and platform architects looking to build resilient cloud-native software on modern Kubernetes, this second edition is essential reading and was undoubtedly worth every bit of the wait!

🎯 Conclusion for the Implementation: From Static Code to Executable Architecture with IBM Bob

What makes this project truly remarkable is that IBM Bob didn’t merely generate boilerplate code — it absorbed the foundational knowledge of Kubernetes in Action, 2nd Edition directly from its text and repository code excerpts to engineer a fully realized, operational system. By ingesting the authors’ original patterns across all 18 chapters, IBM Bob autonomously architected, refactored, and deployed kiada-go—complete with graceful signal handling, multi-stage OCI builds, Downward API metadata injection, and zero-downtime rolling updates. This hands-on implementation proves that when advanced developer assistants like IBM Bob are paired with high-quality, production-minded literature, theoretical cloud-native concepts can be instantly transformed into resilient, battle-tested software.

Thanks for reading 😅

Building a Full-Stack Document Intelligence with the Docling TypeScript Ecosystem

Alain Airom (Ayrom) — Tue, 04 Aug 2026 12:50:51 +0000

How to wire IBM’s @docling/docling-core, @docling/docling-components, and a Python AI backend into a single, coherent React + Node.js application — with a fully offline path that needs no server at all.

Disclaimer: This text and corpus were created using IBM Bob in “Story Telling” ad-hoc mode (on purpose) — killing two birds with one stone!
*It showcases the power of docling-ts while giving you a glimpse into another one of Bob’s many capabilities.
*

First things first: what is Docling-TS?

Docling TS is a set of Type/JavaScript libraries and examples for working with the JSON output format of Docling.

Note: “Docling TS” is an unstable draft implementation that evolves quickly.

Introduction

Document intelligence — the ability to understand the structure and semantics of a PDF, DOCX, spreadsheet, or image — has historically been the exclusive domain of Python. You needed heavy ML models, complex pipelines, and significant infrastructure just to extract a table from a scanned report.

[Docling](Introduction
Document intelligence — the ability to understand the structure and semantics of a PDF, DOCX, spreadsheet, or image — has historically been the exclusive domain of Python. You needed heavy ML models, complex pipelines, and significant infrastructure just to extract a table from a scanned report.

Docling, an open-source project by IBM Research, changes that equation. It provides a best-in-class Python AI engine for document parsing, but critically it also ships a TypeScript ecosystem — @docling/docling-core and @docling/docling-components — that lets front-end and full-stack developers consume pre-converted documents entirely in the browser, with zero Python dependency.

This blog post walks through Docling TS Demo, a full-stack demonstration application that showcases three distinct usage modes:), an open-source project by IBM Research, changes that equation. It provides a best-in-class Python AI engine for document parsing, but critically it also ships a TypeScript ecosystem — @docling/docling-core and @docling/docling-components — that lets front-end and full-stack developers consume pre-converted documents entirely in the browser, with zero Python dependency.

This blog post walks through Docling TS Demo, a full-stack demonstration application that showcases three distinct usage modes:

| Mode                  | Server?         | What it uses                                                 |
| --------------------- | --------------- | ------------------------------------------------------------ |
| 🟢 **JSON Viewer**     | ❌ None          | `@docling/docling-core` + `@docling/docling-components` — pure browser TypeScript |
| 🟢 **SDK Explorer**    | ❌ None          | Copy-ready code for all Docling TS packages                  |
| 🔵 **Live Conversion** | ✅ docling-serve | Express proxy → Python AI backend                            |

The key insight: docling-ts does not convert documents. It provides the TypeScript layer to consume pre-converted Docling JSON. Convert once with the Python CLI, then work entirely offline in TypeScript — no servers, no models, no latency.

Architecture

The application is built with three distinct layers that can operate fully independently.

System Architecture — Three Modes

Offline Data Flow (JSON Viewer)

The offline path is the heart of the docling-ts story. A document is converted once with the Python CLI, and thereafter the TypeScript layer takes over entirely inside the browser.

Live Conversion Data Flow

When docling-serve is running, the full AI pipeline becomes available. Files are forwarded from the React UI through an Express proxy to the Python backend, and the results — Markdown, HTML, JSON, plain text — are persisted to disk and returned to the browser in a single response.

Package Dependency Map

Mode Decision Tree

Project Structure

docling-ts-demo/
├── src/
│   ├── server/                   # Express API (optional proxy)
│   │   ├── index.ts              # Server bootstrap + route wiring
│   │   └── routes/
│   │       ├── convert.ts        # /api/convert/file + /api/convert/url
│   │       ├── health.ts         # /api/health
│   │       └── doclingInfo.ts    # /api/docling/info
│   ├── client/
│   │   └── src/
│   │       ├── App.tsx           # Router + sidebar layout
│   │       ├── pages/
│   │       │   ├── JsonViewerPage.tsx  ← offline docling-ts demo
│   │       │   ├── HomePage.tsx        ← 3-mode overview
│   │       │   ├── ConvertPage.tsx     ← live file upload
│   │       │   ├── UrlConvertPage.tsx  ← live URL convert
│   │       │   ├── ComponentsPage.tsx  ← SDK code explorer
│   │       │   └── HealthPage.tsx      ← system status
│   │       └── types/
│   │           └── docling.d.ts        ← JSX types for web components
│   └── tests/test.ts             # 11 integration tests
├── input/
│   ├── sample-document.md
│   └── sample-docling.json       ← ready-to-use offline demo file
├── scripts/
│   ├── start.sh                  # Launch in detached mode
│   └── stop.sh                   # Graceful shutdown
├── Docs/
│   ├── Architecture.md
│   └── Quickstart.md
└── README.md

Code Deep-Dive

The Offline JSON Viewer — `@docling/docling-core` in Action

The centrepiece of the application is JsonViewerPage.tsx, which demonstrates the full offline path with zero server calls.

Importing real types and utilities: DoclingDocument is the top-level TypeScript type that mirrors the Python DoclingDocument Pydantic model. iterateDocumentItems is a generator that walks the document body in reading order, and isDocling provides discriminated type guards — isDocling.TextItem(item), isDocling.TableItem(item), etc.

// Real imports from @docling/docling-core
import {
  type DoclingDocument,
  type SectionHeaderItem,
  type TextItem,
  type TableItem,
  type PageItem,
  iterateDocumentItems,
  isDocling,
} from '@docling/docling-core'

Type-safe document analysis: This is purely in-browser TypeScript — no fetch, no server calls, just JSON.parse into a typed structure.

function analyseDocument(doc: DoclingDocument): DocStats {
  const pages = doc.pages ? Object.values(doc.pages) : []
  const headers: SectionHeaderItem[] = []
  const textItems: TextItem[]        = []
  const tables: TableItem[]          = []
  let pictureCount = 0
  let totalItems   = 0

  for (const [item] of iterateDocumentItems(doc)) {
    totalItems++
    if (isDocling.SectionHeaderItem(item)) headers.push(item)
    else if (isDocling.TextItem(item))     textItems.push(item)
    else if (isDocling.TableItem(item))    tables.push(item)
    else if (isDocling.PictureItem(item))  pictureCount++
  }

  return { pages, headers, textItems, tables, pictureCount, totalItems }
}

Lazy-loading @docling/docling-components web components: The web components are loaded as a dynamic import to avoid bundling them unless the user actually opens the viewer tab. Once loaded, <docling-img> and <docling-table> are globally registered as custom HTML elements.

// Lazy-load @docling/docling-components — registers custom elements globally
useEffect(() => {
  import('@docling/docling-components')
    .then(() => setComponentsLoaded(true))
    .catch(() => setComponentsLoaded(false))
}, [])

Wiring a web component via a React ref: Because <docling-img> is a custom element, React cannot set complex objects via JSX attributes alone. We use a ref and set the .src property programmatically after mount — a clean pattern for bridging React and native Web Components.

function DoclingImgViewer({ doc }: { doc: DoclingDocument }) {
  const ref = useRef<HTMLElement>(null)

  useEffect(() => {
    if (ref.current) {
      // The web component accepts a parsed DoclingDocument object on `.src`
      ;(ref.current as unknown as { src: unknown }).src = doc
    }
  }, [doc])

  return (
    <docling-img ref={ref} pagenumbers="" style={{ display: 'block', width: '100%' }} />
  )
}

File ingestion via FileReader: No network round-trip. The entire pipeline from file drop to typed DoclingDocument is local and synchronous.

const onDrop = useCallback((accepted: File[]) => {
  const file = accepted[0]
  if (!file) return
  const reader = new FileReader()
  reader.onload = (e) => {
    try {
      const parsed = JSON.parse(e.target?.result as string) as DoclingDocument
      setDoc(parsed)
      setFilename(file.name)
      setActiveTab('stats')
    } catch {
      setError('Could not parse file as a Docling JSON document.')
    }
  }
  reader.readAsText(file)
}, [])

The Express Backend — Proxy to docling-serve

The backend, defined in src/server/index.ts, is intentionally thin. Its sole responsibility for live conversion is to act as a secure, CORS-enabled proxy that adds API key support and persists outputs to disk.

Server bootstrap

const app = express()
const PORT = parseInt(process.env.PORT || '3001', 10)

app.use(cors())
app.use(express.json({ limit: '50mb' }))
app.use('/output', express.static(OUTPUT_DIR))

app.use('/api/health',   healthRouter)
app.use('/api/convert',  convertRouter)
app.use('/api/docling',  doclingInfoRouter)

File conversion endpoint — forwarding to docling-serve

The convert.ts route receives a multipart file upload, builds a new FormData for docling-serve, and persists every output format with a timestamp:

router.post(
  '/file',
  upload.single('file'),
  async (req: Request, res: Response): Promise<void> => {
    // Build multipart form for docling-serve
    const form = new FormData()
    form.append('files', req.file.buffer, {
      filename: req.file.originalname,
      contentType: req.file.mimetype,
    })
    outputFormats.forEach((fmt) => form.append('to_formats', fmt))
    form.append('do_table_structure', 'true')

    const response = await axios.post(
      `${doclingUrl}/v1/convert/file`,
      form,
      { headers, timeout: 300000 } // 5 min timeout for large docs
    )

    // Persist outputs to output/ with a timestamp
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
    if (docData.document?.md_content) {
      const outPath = path.join(outputDir, `${baseName}_${timestamp}.md`)
      fs.writeFileSync(outPath, docData.document.md_content, 'utf-8')
      savedFiles.markdown = `/output/${path.basename(outPath)}`
    }
    // …same for html, json
  }
)

The URL conversion endpoint follows an identical pattern, pointing at /v1/convert/source and forwarding http_sources:

await axios.post(
  `${doclingUrl}/v1/convert/source`,
  {
    http_sources: [{ url }],
    options: { to_formats: toFormats, do_table_structure: true },
  },
  { headers, timeout: 300000 }
)

The SDK Explorer — Copy-Ready Code Examples

ComponentsPage.tsx demonstrates how to use all three packages through a tabbed UI of copy-ready snippets. Here is the @docling/docling-core example embedded in the component:

// Iterate all items with type discrimination
import { iterateDocumentItems, isDocling } from '@docling/docling-core'

const doc = await fetchDoc('https://your-host/conversion.json')

for (const [item, level] of iterateDocumentItems(doc)) {
  if (isDocling.TextItem(item)) {
    console.log('TEXT:', item.text)
  } else if (isDocling.TableItem(item)) {
    console.log('TABLE cells:', item.data.grid.length)
  } else if (isDocling.PictureItem(item)) {
    console.log('PICTURE at page:', item.prov?.[0]?.page_no)
  } else if (isDocling.SectionHeaderItem(item)) {
    console.log('HEADER (level', level, '):', item.text)
  }
}

And the docling-sdk community client pattern for RAG pipelines:

const client = new Docling({
  api: { baseUrl: process.env.DOCLING_SERVE_URL ?? 'http://localhost:5001' },
})

// Document chunking (for RAG pipelines)
const chunks = await client.chunkHybridSync(buf, 'document.pdf', {
  chunking_max_tokens: 200,
})
chunks.forEach(c => console.log(c.text))

Integration Tests — Offline + Live Suites

The test suite in src/tests/test.ts covers four suites across 11 tests. Suites 1–3 always run without docling-serve; Suite 4 auto-skips gracefully if the Python backend is unreachable.

// Suite 3 — Offline JSON parsing (no server needed)
await test('sample-docling.json has DoclingDocument structure (pages + texts + tables)', async () => {
  const doc = JSON.parse(fs.readFileSync(p, 'utf-8'))
  if (typeof doc.pages !== 'object') throw new Error('missing pages')
  if (!Array.isArray(doc.texts))     throw new Error('missing texts array')
  if (!Array.isArray(doc.tables))    throw new Error('missing tables array')
})

// Suite 4 — graceful skip if docling-serve is not reachable
if (!doclingAvailable) {
  console.log('  ⚠️  Docling Serve not reachable — skipping live conversion tests (this is fine)')
}

This design makes CI/CD straightforward: the core test battery never requires the AI backend.

Application Router

The App.tsx root component wires the sidebar navigation and all page routes in a clean BrowserRouter + Routes structure:

<Routes>
  <Route path="/"           element={<HomePage />}       />
  <Route path="/json-viewer" element={<JsonViewerPage />} />
  <Route path="/convert"     element={<ConvertPage />}    />
  <Route path="/url-convert" element={<UrlConvertPage />} />
  <Route path="/components"  element={<ComponentsPage />} />
  <Route path="/health"      element={<HealthPage />}     />
</Routes>

The sidebar distinguishes the two modes visually with emoji badges, making the offline vs. live distinction obvious to users at a glance.

Key Dependencies

| Package                       | Version  | Role                                                         |
| ----------------------------- | -------- | ------------------------------------------------------------ |
| `@docling/docling-core`       | `^0.0.7` | TypeScript types + `iterateDocumentItems` / `isDocling` utilities |
| `@docling/docling-components` | `^0.0.7` | `<docling-img>` / `<docling-table>` web components           |
| `react` + `vite`              | 18 / 5   | Frontend SPA with HMR                                        |
| `express`                     | 4        | Backend API proxy (optional)                                 |
| `multer` + `axios`            | —        | File upload + HTTP forwarding                                |
| `react-dropzone`              | 14       | Drag-and-drop file zones                                     |
| `docling-sdk`                 | `^2.0.0` | Community TypeScript API/CLI/Web client                      |

Getting Started in 3 Steps

# 1. Clone and configure
cp .env.example .env

# 2. Start the demo (offline features work immediately)
./scripts/start.sh
# → http://localhost:3000

# 3. (Optional) Start docling-serve for live conversion
podman run -p 5001:5001 \
  -e DOCLING_SERVE_ENABLE_UI=1 \
  quay.io/docling-project/docling-serve

Drop input/sample-docling.json onto the JSON Viewer page to explore the offline mode immediately — no Python, no container, no models required.

Conclusion

The Docling TS Demo project demonstrates that document intelligence no longer has to be a Python-only story.

Through this application we can demonstrate end-to-end;

A fully offline document viewer — @docling/docling-core provides production-quality TypeScript types (DoclingDocument, TextItem, TableItem, PictureItem, SectionHeaderItem) and the iterateDocumentItems / isDocling utility layer that mirrors the Python library's API. Any document converted once by the Docling Python CLI can be explored, parsed, and rendered in a React application with zero server dependencies.
Native web component integration — @docling/docling-components ships <docling-img> and <docling-table> as standards-based custom elements. Bridging them into a React application via refs and programmatic property assignment (el.src = doc) is a clean, future-proof pattern that works today with any modern browser.
A production-ready Express proxy — for teams that need live, on-demand conversion, the three-tier architecture (React → Express → docling-serve) provides a clean separation of concerns. The API key layer, memory-buffered uploads, 5-minute timeout, and timestamped output persistence are all patterns directly applicable to production workloads.
A test strategy that matches the architecture — the four-suite integration test battery (API health, input validation, offline JSON parsing, optional live conversion) reflects the tiered nature of the system. CI always passes on the offline suites; the live suite degrades gracefully when the AI backend is absent.
Developer experience — the SDK Explorer page, copy-ready code snippets, and the mode decision tree lower the barrier to entry for developers who want to add document intelligence to TypeScript applications without committing to a full ML infrastructure.

The Docling TypeScript ecosystem is young — both packages are at v0.0.7 — but the design mirrors the mature Python library closely enough that the API surface will be familiar to anyone who has used docling-core in Python. This project serves as a concrete, working reference for anyone looking to bring structured document understanding into the browser.

Thanks for reading (I wrote this 😂)

Kubernetes Architectural Shift: Moving Workloads from Rancher Desktop (K3s) to Managed Cluster (part 2)

Alain Airom (Ayrom) — Sun, 02 Aug 2026 20:09:26 +0000

Enterprise Production vs. Local Prototyping: Red Hat OpenShift (called ROKS) vs. Rancher Desktop!

Introduction and context

Following a recent technical discussion regarding the tradeoffs between managed cloud services — such as IBM Kubernetes Service (IKS) (part 1, previously exposed) or Red Hat OpenShift — and local development environments like Rancher Desktop, I put together a detailed comparison framework. Here is the breakdown, to shift from a local kubernetes development to an enterprise scale platfom.

I’ve been posting a ton about LLMs, RAG, and vector search lately, but don’t worry — I haven’t gone totally soft. Infrastructure and cluster environments are still my primary passion. Because at the end of the day, even the smartest AI is just a glorified math model sitting on a worker node that someone has to keep from running out of disk space.

The modern container lifecycle spans two distinct operational realms: local developer desktop prototyping and enterprise production execution.

Rancher Desktop runs locally on developer workstations (macOS, Windows, Linux) by encapsulating a single-node K3s or containerd runtime inside a desktop hypervisor (Lima VM / WSL2). It accelerates local iteration without cloud infrastructure costs.

Developer Laptop (macOS / Windows / Linux)
└── Rancher Desktop (Electron App)
    └── Virtual Machine (Lima VM / WSL2)
        └── Single-Node K3s Cluster
            ├── Control Plane (same node as worker)
            │   ├── Kubernetes API Server
            │   ├── etcd (or SQLite for K3s lite mode)
            │   ├── Scheduler
            │   └── Controller Manager
            │
            └── Worker (same node)
                ├── App Pods (nginx-demo)
                ├── containerd / dockerd
                ├── Local Storage (hostPath)
                └── Traefik Ingress (built-in)

Developer Tooling (Host OS)
├── Rancher Desktop GUI
├── kubectl / helm (bundled)
├── docker / nerdctl (bundled)
└── Port Forwarding (localhost)

⚠️ Constraints:
   - No external load balancer provisioner
   - No IAM / no enterprise RBAC
   - No managed TLS certificates
   - No cluster autoscaler
   - Constrained by laptop CPU/RAM

Red Hat OpenShift on IBM Cloud (ROKS): ROKS is a jointly engineered managed service by IBM and Red Hat. IBM manages the OpenShift Container Platform (OCP 4.x) master nodes while providing:

Auto-patching of the OCP control plane (OS, OCP version, container runtime CRI-O)
High availability across up to 3 availability zones within an IBM Cloud region
99.99% SLA for the OpenShift master
Native integration with the IBM Cloud ecosystem: IAM, Key Protect, Secrets Manager, Container Registry, VPC Load Balancers, Block/File/Object Storage, IBM Cloud Logs, Monitoring
The full OpenShift feature set: Web Console (Developer + Admin), OperatorHub, OLM, Source-to-Image (S2I), OpenShift Pipelines (Tekton), OpenShift Dev Spaces (formerly CodeReady Workspaces), Security Context Constraints (SCC)

GPU node pools: NVIDIA A100, L40S, H100 with GPU Operator and MIG support

IBM Cloud (VPC Region)
├── Managed Control Plane (IBM + Red Hat managed, HA)
│   ├── OpenShift API Server (HA, multi-zone)
│   ├── etcd (HA, encrypted via IBM Key Protect)
│   ├── OpenShift Scheduler
│   ├── Controller Manager
│   └── OAuth Server (RBAC + SCC engine)
│
├── Worker Node Pool (User-managed, VPC VSIs)
│   ├── Worker Node 1 — Zone A (App pods, SCC enforced)
│   ├── Worker Node 2 — Zone B (App pods, SCC enforced)
│   └── GPU Worker Node — Zone C (NVIDIA A100/L40S/H100, AI/ML pods)
│
├── OpenShift Platform Services (Built-in)
│   ├── OpenShift Web Console (Developer + Admin)
│   ├── OperatorHub (OLM — Operator Lifecycle Manager)
│   ├── Source-to-Image (S2I) / Tekton Pipelines
│   ├── HAProxy Router (Routes + TLS)
│   ├── OpenShift Internal Registry
│   └── Security Context Constraints (SCC)
│
├── IBM Cloud Services (Native Integration)
│   ├── IBM Cloud IAM + RBAC Federation
│   ├── IBM Key Protect (KMS — etcd encryption)
│   ├── IBM Container Registry (private + CVE scan)
│   ├── IBM Cloud Logs (centralized logging)
│   ├── IBM Cloud Monitoring / Sysdig
│   ├── IBM Secrets Manager (TLS auto-renew)
│   └── VPC Block / File / Object Storage (CSI)
│
└── VPC Networking (Secure by Default)
    ├── VPC Application Load Balancer (TLS termination)
    ├── Security Groups (worker-node level)
    ├── Network ACLs (subnet level)
    ├── Private Service Endpoint (API server off public internet)
    ├── WireGuard (encrypted worker-to-worker traffic)
    ├── Context-Based Restrictions (CBR)
    └── Multi-Zone High Availability (3 AZs)

Comparison using a sample Deployment: ‘nginx-demo’ (illustration purpose)

| Aspect                   | Local Development (Rancher Desktop)                  | Production / Managed Cloud (IBM ROKS)                        |
| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
| **Cluster Scope**        | Single-node (K3s)                                    | Multi-node enterprise cluster                                |
| **Workload Scale**       | Single replica (1 pod, non-HA)                       | Multi-replica with horizontal autoscaling (HPA)              |
| **Ingress Access**       | Standard Kubernetes `Ingress` (Traefik) / `NodePort` | OpenShift `Route` (HAProxy Router)                           |
| **Storage Engine**       | Local machine disk (`hostPath`)                      | Encrypted VPC Block Storage via StorageClass                 |
| **Security Controls**    | Basic `runAsNonRoot` / standard K8s defaults         | Restricted SCCs, dropped Linux capabilities, seccomp profiles |
| **Specialized Hardware** | N/A                                                  | Dedicated GPU Node Pools (NVIDIA A100 / H100)                |

External Ingress & Routing

Rancher Desktop (ingress.yaml & service.yaml) Local access relies on standard K8s Ingress mapped to local hostnames (or NodePorts exposed on high port numbers) over unencrypted HTTP:

# Ingress using Traefik on Rancher Desktop
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-demo-ingress
  annotations:
    kubernetes.io/ingress.class: traefik
spec:
  rules:
    - host: nginx-demo.localhost
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nginx-demo
                port:
                  number: 80

IBM ROKS (route.yaml) ROKS uses OpenShift’s native Route CRD, which automatically leverages IBM Cloud's wildcard TLS certificates and handles edge TLS termination via HAProxy:

# OpenShift Route on ROKS
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: nginx-demo
spec:
  host: nginx-demo-nginx-demo.<YOUR-CLUSTER-NAME>.<REGION>.containers.appdomain.cloud
  to:
    kind: Service
    name: nginx-demo
  tls:
    termination: edge                           # Managed TLS termination at HAProxy
    insecureEdgeTerminationPolicy: Redirect   # Forces HTTP -> HTTPS

Persistent Storage

Rancher Desktop (deployment.yaml) Data is bound directly to the local host filesystem, making it non-portable and vulnerable if the local cluster state is reset:

# HostPath Volume Mount (Local Machine)
volumes:
  - name: nginx-html
    hostPath:
      path: /tmp/nginx-html
      type: DirectoryOrCreate

IBM ROKS (pvc.yaml) ROKS requests persistent storage dynamically using IBM Cloud VPC Block Storage with encryption at rest:

# PersistentVolumeClaim utilizing IBM Cloud VPC Block Storage
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: nginx-demo-storage
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: ibmc-vpc-block-10iops-tier  # IBM Key Protect encrypted tier
  resources:
    requests:
      storage: 10Gi

Scaling & High Availability

Rancher Desktop (deployment.yaml) Configured with a single static replica suitable only for low-overhead local testing:

spec:
  replicas: 1  # Fixed single instance

IBM ROKS (hpa.yaml) Configured for automated, elastic scaling based on real-time CPU and Memory utilization thresholds:

# HorizontalPodAutoscaler on ROKS
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-demo-hpa
spec:
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Hardware Acceleration & Specialized Workloads (ROKS Exclusive)

IBM ROKS (gpu-deployment.yaml) While local environments typically lack direct Kubernetes GPU passthrough, ROKS schedules compute-intensive ML/AI jobs to specific node pools using node selectors, tolerations, and resource limits:

# GPU Acceleration Config on ROKS
spec:
  nodeSelector:
    nvidia.com/gpu.present: "true"
  tolerations:
    - key: nvidia.com/gpu
      operator: Exists
      effect: NoSchedule
  containers:
    - name: gpu-workload
      resources:
        limits:
          nvidia.com/gpu: "1"  # Allocated via NVIDIA GPU Operator

IBM Cloud VPC Security Advantages

IBM Cloud Virtual Private Cloud (VPC) is the recommended infrastructure for ROKS clusters. It provides a 7-layer defence-in-depth security model that is simply not possible with a local Rancher Desktop setup.

Layer 1 — Edge & Perimeter Protection

IBM Cloud Internet Services (CIS): DDoS protection, Web Application Firewall (WAF), rate limiting, TLS 1.3
Global Load Balancer: Geo-routing, health-based failover across regions
Anycast Network: IBM’s global Anycast routing absorbs traffic spikes

Layer 2 — VPC Network Perimeter

VPC Security Groups (stateful): Filter ingress/egress traffic at the worker node level. Rules specify allowed protocols, ports, and CIDR ranges. Default deny-all inbound from internet.
Network ACLs (stateless): Applied at subnet level, providing an additional filtering layer before traffic reaches instances. Both inbound and outbound rules required.
Public Gateway: Controlled, one-way egress. Worker nodes have no public IP by default; internet access only through the gateway (egress-only, not inbound).
Flow Logs: Capture all accepted/rejected VPC network flows for security analysis and compliance auditing (stored in IBM Cloud Object Storage).

Layer 3 — Cluster Access Control

Private Service Endpoint: The OpenShift API server is accessible only via private IBM Cloud network (RFC 1918 addresses), never via public internet. Eliminates API server as an internet-facing attack surface.
Context-Based Restrictions (CBR): Define fine-grained access rules — e.g., “only allow access to the cluster from IP range X” or “only from specific IBM Cloud VPCs.” Applied at IBM Cloud IAM level.
VPN Gateway / IBM Cloud Direct Link: Secure on-premise to VPC connectivity without traversing public internet.
Transit Gateway: Private connectivity between VPCs and classic infrastructure.

Layer 4 — Pod Network Security

OVN-Kubernetes / Calico network policies: Namespace-level and pod-level L3/L4 traffic control. Default deny-all between namespaces.
OpenShift NetworkPolicy: Restrict ingress/egress per pod selector.
WireGuard (worker-to-worker): All traffic between worker nodes is encrypted at the VPN/overlay level, protecting pod-to-pod communication even within the VPC.
Egress Firewall: Block external egress from specific namespaces.

Layer 5 — Workload Security

Security Context Constraints (SCC): OpenShift’s advanced security policy (beyond Kubernetes PSA). Controls uid/gid ranges, volume types, capabilities, seccomp, SELinux — enforced cluster-wide. Default SCC restricted-v2 prevents root containers.
IBM Key Protect (KMS): etcd secrets encrypted at rest with customer-managed encryption keys. Key rotation, audit logging, and FIPS 140–2 certified HSMs.
IBM Secrets Manager: Centralized secret storage with automatic TLS cert lifecycle management (creation, renewal, rotation) integrated with OpenShift.
NVIDIA GPU Isolation: Each GPU pod gets dedicated GPU resources with hardware-level isolation.

Layer 6 — Identity & Access Management

IBM Cloud IAM: Centralized identity for all IBM Cloud resources. Users authenticated via IBMid, SAML/LDAP federation, service IDs, trusted profiles, and API keys.
IAM ↔ OpenShift RBAC Federation: IBM Cloud IAM roles map to OpenShift RBAC roles. Manage cluster access through IBM Cloud console without direct kubeconfig management.
Multi-Factor Authentication (MFA): Enforce MFA for all IBM Cloud users accessing the cluster.
Service-to-Service Authorization: Pods authenticate to IBM Cloud services (Key Protect, COS) via trusted profiles — no credentials stored in pods.

Layer 7 — Audit, Compliance & Governance

IBM Cloud Activity Tracker: Immutable audit log of ALL IBM Cloud API calls — cluster creation, node additions, IAM changes, data access. Cannot be deleted or tampered with.
VPC Flow Logs: Network-level audit trail.
CIS Kubernetes Benchmark: IBM publishes per-version CIS benchmark scores for ROKS.
Compliance certifications: SOC 1 Type II, SOC 2 Type II, ISO 27001/27017/27018, PCI DSS, HIPAA, FedRAMP Moderate, C5 (Germany), IRAP (Australia), ISMAP (Japan).

### VPC Security vs Rancher Desktop

| Security Control         | IBM Cloud VPC (ROKS)       | Rancher Desktop            |
| ------------------------ | -------------------------- | -------------------------- |
| Network isolation        | ✅ VPC — private by default | ❌ Host network / localhost |
| DDoS protection          | ✅ CIS (IBM Cloud)          | ❌ None                     |
| Worker firewall          | ✅ Security Groups + ACLs   | ❌ None                     |
| API server exposure      | ✅ Private endpoint only    | ❌ Localhost VM             |
| Pod traffic encryption   | ✅ WireGuard                | ❌ Unencrypted              |
| IAM / MFA                | ✅ IBM Cloud IAM + MFA      | ❌ kubeconfig cert          |
| KMS / secret encryption  | ✅ Key Protect (FIPS HSM)   | ❌ Base64 in local etcd     |
| SCC enforcement          | ✅ Cluster-wide             | ❌ None                     |
| Audit trail              | ✅ Activity Tracker         | ❌ None                     |
| Compliance certification | ✅ SOC2, HIPAA, PCI DSS...  | ❌ None                     |

OpenShift-Specific Advantages

ROKS runs Red Hat OpenShift, which goes significantly beyond vanilla Kubernetes (and K3s):

Security Context Constraints (SCC)

OpenShift’s SCC system is stricter than Kubernetes’ Pod Security Admission (PSA):

| Capability                | SCC (OpenShift)                     | PSA (K8s/K3s)        |
| ------------------------- | ----------------------------------- | -------------------- |
| UID/GID ranges            | ✅ Per-namespace random UID range    | ❌ Only disallow root |
| Volume type restrictions  | ✅ Granular (block hostPath per SCC) | ⚠️ Limited            |
| SELinux labels            | ✅ Required per SCC                  | ❌ Optional           |
| Seccomp profiles          | ✅ Required in restricted-v2         | ⚠️ Optional           |
| Custom SCCs per namespace | ✅ Yes                               | ❌ No                 |
| Service account binding   | ✅ SCC bound to SA                   | ❌ No equivalent      |

OpenShift Web Console

The OpenShift Web Console provides two views:

Developer view: Topology map, build pipeline status, resource monitoring per project, Dev Spaces launcher, application deployment wizards
Administrator view: Cluster-wide resource management, node/machine management,storage, network, OperatorHub, cluster settings, user management

Rancher Desktop has a basic dashboard with no tooling.

OperatorHub & OLM

Over 300 Red Hat certified and community operators available for one-click installation:

Databases: PostgreSQL, MongoDB, Redis, Elasticsearch
Messaging: IBM MQ, Kafka, RabbitMQ
Monitoring: Prometheus Operator, Grafana
Security: Vault, Cert-Manager, Aqua
AI/ML: NVIDIA GPU Operator, OpenShift AI, Kubeflow
Storage: Portworx, OpenShift Data Foundation (ODF)

Source-to-Image (S2I)

S2I builds container images directly from source code without a Dockerfile:

# Deploy a Node.js app directly from Git on ROKS — no Dockerfile needed
oc new-app nodejs~https://github.com/myorg/myapp.git --name=myapp

# ROKS builds the image in-cluster and deploys automatically

OpenShift Routes vs Kubernetes Ingress

| Aspect             | OpenShift Route         | K8s Ingress (Traefik/NGINX) |
| ------------------ | ----------------------- | --------------------------- |
| TLS termination    | ✅ HAProxy, managed cert | ⚠️ Manual                    |
| Passthrough TLS    | ✅ Yes                   | ⚠️ Limited                   |
| Edge/Re-encrypt    | ✅ Both supported        | ❌ Edge only                 |
| IBM subdomain cert | ✅ Auto-provisioned      | ✅ Auto-provisioned (IKS)    |
| Wildcard routes    | ✅ Yes                   | ⚠️ Ingress-class dependent   |

Security

Authentication & Authorization

| Layer          | ROKS                           | Rancher Desktop |
| -------------- | ------------------------------ | --------------- |
| **User Auth**  | IBM Cloud IAM (SAML, SSO, MFA) | kubeconfig cert |
| **RBAC**       | OpenShift RBAC + IAM mapping   | Basic K8s RBAC  |
| **SCC**        | ✅ Enforced (restricted-v2)     | ❌ None          |
| **Audit Logs** | IBM Cloud Activity Tracker     | None            |

Pod Security

| Feature              | ROKS (SCC)                  | K3s/Rancher (PSA) |
| -------------------- | --------------------------- | ----------------- |
| Root prevention      | ✅ SCC assigns random UID    | ⚠️ PSA restricted  |
| Volume control       | ✅ SCC controls volume types | ⚠️ Limited         |
| Privilege escalation | ✅ Blocked by SCC            | ⚠️ PSA             |
| SELinux labels       | ✅ Enforced                  | ❌ Optional        |
| Seccomp              | ✅ Required                  | ⚠️ Optional        |

Data Encryption


| Layer       | ROKS                          | Rancher Desktop         |
| ----------- | ----------------------------- | ----------------------- |
| etcd        | ✅ KMS-encrypted (Key Protect) | ❌ Local disk only       |
| Secrets     | ✅ KMS-wrapped                 | ❌ Base64 only           |
| Worker disk | ✅ IBM-managed VSI encryption  | ⚠️ Host OS               |
| Pod traffic | ✅ WireGuard                   | ❌ Unencrypted           |
| Storage PVC | ✅ VPC Block Storage encrypted | ❌ hostPath, unencrypted |
| TLS Ingress | ✅ Managed, auto-renewed       | ⚠️ Self-signed/manual    |

Networking

| Capability                 | ROKS                          | Rancher Desktop   |
| -------------------------- | ----------------------------- | ----------------- |
| **OpenShift Routes**       | ✅ HAProxy TLS Router          | ❌ Not available   |
| **VPC Load Balancer (L7)** | ✅ ALB with TLS termination    | ❌ Not available   |
| **VPC Load Balancer (L4)** | ✅ NLB (Network Load Balancer) | ❌ Not available   |
| **Private API Endpoint**   | ✅ No public master URL        | ❌ localhost VM    |
| **IBM Cloud DNS**          | ✅ Auto-provisioned subdomain  | ⚠️ /etc/hosts only |
| **Egress control**         | ✅ VPC egress firewall, NAT GW | ❌ None            |
| **Network Policies**       | ✅ OVN-K8s + Calico            | ✅ Flannel (basic) |
| **WireGuard**              | ✅ Worker-to-worker encryption | ❌ No              |
| **Global LB**              | ✅ IBM CIS                     | ❌ N/A             |
| **Transit Gateway**        | ✅ VPC-to-VPC connectivity     | ❌ N/A             |

Storage

| Storage Type                  | ROKS                                    | Rancher Desktop   |
| ----------------------------- | --------------------------------------- | ----------------- |
| **Block Storage (RWO)**       | ✅ VPC Block (CSI, encrypted, snapshots) | ⚠️ local-path      |
| **File Storage (RWX)**        | ✅ VPC File (NFS, CSI)                   | ❌ Not available   |
| **Object Storage**            | ✅ IBM Cloud Object Storage (S3)         | ❌ Not available   |
| **OpenShift Data Foundation** | ✅ Ceph-based (ODF Operator)             | ❌ Not available   |
| **Portworx**                  | ✅ Enterprise storage operator           | ❌ Not available   |
| **Encryption**                | ✅ IBM Key Protect                       | ❌ None            |
| **Volume Snapshots**          | ✅ CSI snapshots                         | ❌ None            |
| **Dynamic Provisioning**      | ✅ CSI (all storage types)               | ✅ local-path only |
| **Multi-Zone Storage**        | ✅ Regional snapshots                    | ❌ N/A             |

Observability: Monitoring & Logs

| Capability               | ROKS                            | Rancher Desktop     |
| ------------------------ | ------------------------------- | ------------------- |
| **Pod Logs**             | ✅ kubectl/oc + IBM Cloud Logs   | ✅ kubectl logs only |
| **Cluster Metrics**      | ✅ IBM Cloud Monitoring (Sysdig) | ❌ Manual Prometheus |
| **OpenShift Monitoring** | ✅ Built-in Prometheus + Grafana | ❌ Manual            |
| **Alerting**             | ✅ IBM Cloud + OCP AlertManager  | ❌ Manual            |
| **Distributed Tracing**  | ✅ IBM Instana / Jaeger (Sysdig) | ❌ Manual            |
| **Audit Logs**           | ✅ IBM Activity Tracker          | ❌ None              |
| **Network Flow Logs**    | ✅ VPC Flow Logs                 | ❌ None              |
| **OpenShift Dashboards** | ✅ Console metrics built-in      | ❌ None              |

Autoscaling

| Type                   | ROKS                                 | Rancher Desktop             |
| ---------------------- | ------------------------------------ | --------------------------- |
| **HPA**                | ✅ CPU, Memory, custom Sysdig metrics | ✅ CPU/Memory only (limited) |
| **VPA**                | ✅ Yes                                | ⚠️ Manual install            |
| **Cluster Autoscaler** | ✅ Provisions/deprovisions VPC VSIs   | ❌ Not possible              |
| **GPU Autoscaling**    | ✅ Scale GPU node pools on demand     | ❌ N/A                       |
| **Scale to Zero**      | ✅ Knative (OpenShift Serverless)     | ❌ No                        |
| **KEDA**               | ✅ Via OperatorHub                    | ⚠️ Manual install            |

High Availability (HA) & Disaster Recovery (DR)

## 

| Aspect                  | ROKS                               | Rancher Desktop          |
| ----------------------- | ---------------------------------- | ------------------------ |
| **Control Plane HA**    | ✅ 3+ replicas, auto-failover       | ❌ Single node            |
| **Multi-Zone Workers**  | ✅ 3 availability zones             | ❌ N/A                    |
| **Auto Node Repair**    | ✅ Replace unhealthy nodes          | ❌ Must restart           |
| **SLA**                 | ✅ 99.99% (master)                  | ❌ None                   |
| **Backup**              | ✅ Portworx Backup, VPC Snapshots   | ❌ Manual                 |
| **Cross-Region DR**     | ✅ Multi-region cluster replication | ❌ N/A                    |
| **etcd Backup**         | ✅ IBM-managed, automated           | ❌ Manual                 |
| **Rolling OCP Updates** | ✅ IBM-managed, zero-downtime       | ❌ Manual Rancher upgrade |

CI/CD & Developer Experience

| Tool                             | ROKS                               | Rancher Desktop  |
| -------------------------------- | ---------------------------------- | ---------------- |
| **OpenShift Pipelines (Tekton)** | ✅ Managed add-on                   | ❌ Manual install |
| **OpenShift GitOps (ArgoCD)**    | ✅ Managed add-on                   | ❌ Manual install |
| **IBM DevSecOps**                | ✅ Native integration               | ❌ N/A            |
| **S2I Builds**                   | ✅ In-cluster, no Dockerfile needed | ❌ N/A            |
| **OpenShift Dev Spaces**         | ✅ Browser-based cloud IDE          | ❌ Not available  |
| **Image Vulnerability Scan**     | ✅ IBM Container Registry + VA      | ❌ None           |
| **OperatorHub (300+ operators)** | ✅ One-click install                | ❌ Not available  |
| **`oc` CLI**                     | ✅ Full OpenShift CLI               | ❌ kubectl only   |
| **GitHub Actions**               | ✅ ibmcloud/oc CLI actions          | ✅ kubectl        |
| **Helm**                         | ✅ Full support                     | ✅ Full support   |
| **GitOps (FluxCD)**              | ✅ Supported                        | ✅ Supported      |

Conclusion

Pros and Cons feature by feature

| Feature                          | ROKS                                 | Rancher Desktop         | Winner  |
| -------------------------------- | ------------------------------------ | ----------------------- | ------- |
| **Kubernetes Distribution**      | ✅ Red Hat OpenShift (OCP 4.x)        | ⚠️ K3s (lightweight K8s) | ROKS    |
| **CNCF Certified**               | ✅ Yes                                | ✅ Yes (K3s)             | Tie     |
| **Control Plane Management**     | ✅ Fully managed by IBM               | ⚠️ Self-managed K3s      | ROKS    |
| **Multi-Node Cluster**           | ✅ Hundreds of nodes                  | ❌ Single node           | ROKS    |
| **Multi-Zone HA**                | ✅ 3+ availability zones              | ❌ No                    | ROKS    |
| **SLA**                          | ✅ 99.99% (master)                    | ❌ None                  | ROKS    |
| **Auto-Patch Control Plane**     | ✅ IBM + Red Hat managed              | ❌ Manual                | ROKS    |
| **OpenShift Web Console**        | ✅ Developer + Admin views            | ❌ Not available         | ROKS    |
| **OperatorHub / OLM**            | ✅ 300+ certified operators           | ❌ Not available         | ROKS    |
| **Source-to-Image (S2I)**        | ✅ Build from source in cluster       | ❌ Not available         | ROKS    |
| **OpenShift Pipelines (Tekton)** | ✅ Managed add-on                     | ❌ Manual install        | ROKS    |
| **OpenShift Dev Spaces**         | ✅ Cloud IDE in browser               | ❌ Not available         | ROKS    |
| **OpenShift GitOps (ArgoCD)**    | ✅ Managed add-on                     | ❌ Manual install        | ROKS    |
| **Security Context Constraints** | ✅ Enforced at cluster level          | ❌ No SCC (PSA only)     | ROKS    |
| **IBM Cloud IAM**                | ✅ Full integration + RBAC            | ❌ kubeconfig only       | ROKS    |
| **Key Protect (KMS)**            | ✅ etcd + secret encryption           | ❌ Base64 only           | ROKS    |
| **VPC Security Groups**          | ✅ Worker-node level                  | ❌ N/A                   | ROKS    |
| **Network ACLs**                 | ✅ Subnet level                       | ❌ N/A                   | ROKS    |
| **Private Service Endpoint**     | ✅ API not on public internet         | ❌ Localhost only        | ROKS    |
| **WireGuard (pod traffic)**      | ✅ Encrypted worker-to-worker         | ❌ No                    | ROKS    |
| **Context-Based Restrictions**   | ✅ IBM Cloud CBR                      | ❌ N/A                   | ROKS    |
| **GPU Node Pools**               | ✅ NVIDIA A100, L40S, H100            | ❌ No GPU passthrough    | ROKS    |
| **NVIDIA GPU Operator**          | ✅ Via OperatorHub                    | ❌ N/A                   | ROKS    |
| **MIG (Multi-Instance GPU)**     | ✅ Supported                          | ❌ N/A                   | ROKS    |
| **Cluster Autoscaler**           | ✅ Yes (VPC VSI provisioning)         | ❌ No                    | ROKS    |
| **HPA**                          | ✅ Yes                                | ✅ Yes (limited)         | ROKS    |
| **VPA**                          | ✅ Yes                                | ⚠️ Manual                | ROKS    |
| **IBM Container Registry**       | ✅ Private + CVE scanning             | ❌ Docker Hub            | ROKS    |
| **OpenShift Route + HAProxy**    | ✅ TLS termination, managed cert      | ❌ Traefik NodePort      | ROKS    |
| **VPC Load Balancer**            | ✅ ALB/NLB (auto-provisioned)         | ❌ Not available         | ROKS    |
| **VPC Block Storage (CSI)**      | ✅ Encrypted, snapshots               | ❌ local-path            | ROKS    |
| **VPC File Storage**             | ✅ RWX (NFS)                          | ❌ N/A                   | ROKS    |
| **IBM Cloud Object Storage**     | ✅ S3-compatible                      | ❌ N/A                   | ROKS    |
| **IBM Cloud Logs**               | ✅ Managed centralized logging        | ❌ kubectl logs only     | ROKS    |
| **IBM Cloud Monitoring**         | ✅ Sysdig (managed)                   | ❌ Manual Prometheus     | ROKS    |
| **Distributed Tracing**          | ✅ Instana / Jaeger (Sysdig)          | ❌ Manual                | ROKS    |
| **Compliance**                   | ✅ SOC2, HIPAA, PCI DSS, ISO, FedRAMP | ❌ None                  | ROKS    |
| **FIPS 140-2**                   | ✅ Supported                          | ❌ No                    | ROKS    |
| **Red Hat Support**              | ✅ Included                           | ❌ Community only        | ROKS    |
| **Cost**                         | 💰 Pay-per-use                        | ✅ Free                  | Rancher |
| **Setup Time**                   | ⏱️ ~20-30 min                         | ✅ ~5 min                | Rancher |
| **Works Offline**                | ❌ Requires IBM Cloud                 | ✅ Works offline         | Rancher |

Transition Strategy

Moving from Rancher Desktop to Red Hat OpenShift represents a shift from local rapid feedback loops to enterprise cloud governance. Developers can iterate rapidly on desktop environments using simplified manifests. However, promoting applications to staging and production requires adopting enterprise security patterns: strict pod security standards, multi-zone anti-affinity, KMS-backed persistent storage, and IBM VPC isolation.

Thanks for reading ✔️

Links and Reference

How Losing My Typora License Led to Building My Own Markdown Editor

Alain Airom (Ayrom) — Sun, 02 Aug 2026 08:11:00 +0000

How Losing My Typora License Led to Building My Own Markdown Editor

Introduction

For years, Typora has been my go-to Markdown editor — it’s affordable, reliable, and powerful. But yesterday, out of nowhere, it asked for my license key and threw an error claiming my usage limit was exhausted. While waiting on support to reply, I browsed free and open-source alternatives, but nothing quite clicked. Frustrated and impatient, I decided to take matters into my own hands last night and tasked Bob with building one from scratch. What started as a quick experiment quickly turned into a fully functional Electron app. Taking it a step further, I had Bob rewrite the entire application in Rust and package distributable builds for both versions. Today, both apps are completely open-source and ready to use — feel free to grab them!

Building the Desktop Foundation (Electron & React)

When building a high-performance desktop editor, selecting an extensible, cross-platform architecture is critical. The first edition of the Markdown editor was built using Electron, React 18, and TypeScript. This architecture decouples the main process handling system events and file storage from the isolated renderer process responsible for live preview rendering, syntax highlighting, and Mermaid diagram execution.

Architectural Layout & Communication

To ensure safety and performance, the application enforces Context Isolation and disables Node Integration in the Chromium renderer process. The renderer interacts with native desktop APIs strictly via an IPC (Inter-Process Communication) context bridge.

┌──────────────────────────────────────────────┐
│            Main Process (Node.js)            │
│  - Window Lifecycle Management               │
│  - System Menu Bar Construction              │
│  - Native Dialogs & File Read/Write (fs)     │
└──────────────────────┬───────────────────────┘
                       │  IPC Channels
                       │  (file:open, file:save, etc.)
┌──────────────────────▼───────────────────────┐
│         Renderer Process (Chromium)          │
│  - React UI & Document State                 │
│  - Real-time Markdown Parsing (markdown-it)  │
│  - Local Mermaid & Highlight.js Rendering    │
└──────────────────────────────────────────────┘

Core Module Implementation

Native Desktop Bridge & File Operations

The main process configures the application window, constructs the system menu, and exposes secure IPC handlers to safely execute disk operations:

// src/main/index.ts
import { app, BrowserWindow, dialog, ipcMain } from 'electron';
import path from 'path';
import fs from 'fs';

let mainWindow: BrowserWindow | null = null;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1400,
    height: 900,
    webPreferences: {
      preload: path.join(__dirname, '../renderer/index.js'),
      contextIsolation: true,
      nodeIntegration: false,
    },
  });

  const startUrl = process.env.NODE_ENV === 'development'
    ? 'http://localhost:3000'
    : `file://${path.join(__dirname, '../renderer/index.html')}`;

  mainWindow.loadURL(startUrl);
}

// IPC Handlers for Native File Dialogs
ipcMain.handle('file:open', async () => {
  const result = await dialog.showOpenDialog(mainWindow!, {
    properties: ['openFile'],
    filters: [
      { name: 'Markdown Files', extensions: ['md'] },
      { name: 'All Files', extensions: ['*'] },
    ],
  });

  if (!result.canceled && result.filePaths.length > 0) {
    const content = fs.readFileSync(result.filePaths[0], 'utf-8');
    return {
      path: result.filePaths[0],
      content,
      name: path.basename(result.filePaths[0]),
    };
  }
  return null;
});

ipcMain.handle('file:save', async (_event, content: string, filePath?: string) => {
  let targetPath = filePath;

  if (!targetPath) {
    const result = await dialog.showSaveDialog(mainWindow!, {
      defaultPath: 'document.md',
      filters: [{ name: 'Markdown Files', extensions: ['md'] }],
    });
    if (result.canceled) return null;
    targetPath = result.filePath;
  }

  if (targetPath) {
    fs.writeFileSync(targetPath, content, 'utf-8');
    return { path: targetPath, name: path.basename(targetPath) };
  }
  return null;
});

Pure Formatting Engine

To keep state changes predictable and completely testable outside of the UI rendering cycle, document manipulations (wrapping selections, prefixing lines, and inserting dynamic blocks) are decoupled into a pure state transformer:

// src/lib/applyAction.ts
export interface TextareaState {
  value: string;
  selectionStart: number;
  selectionEnd: number;
}

export function applyAction(
  textarea: TextareaState,
  action: MenuAction,
  onChange: (v: string) => void
): { newValue: string; newStart: number; newEnd: number } {
  const { selectionStart: start, selectionEnd: end, value } = textarea;

  let newValue = value;
  let newStart = start;
  let newEnd = end;

  if (action.type === 'wrap') {
    const before = action.before ?? '';
    const after = action.after ?? '';
    const selected = value.slice(start, end) || action.placeholder || '';
    const replacement = `${before}${selected}${after}`;

    newValue = value.slice(0, start) + replacement + value.slice(end);
    newStart = start + before.length;
    newEnd = newStart + selected.length;

  } else if (action.type === 'linePrefix') {
    const prefix = action.prefix ?? '';
    const lineStart = value.lastIndexOf('\n', start - 1) + 1;
    const lineEndIdx = value.indexOf('\n', end);
    const effectiveEnd = lineEndIdx === -1 ? value.length : lineEndIdx;

    const block = value.slice(lineStart, effectiveEnd);
    const lines = block.split('\n');
    const allPrefixed = prefix.length > 0 && lines.every((l) => l.startsWith(prefix));

    let newLines: string[];
    if (allPrefixed) {
      // Toggle off prefix
      newLines = lines.map((l) => l.slice(prefix.length));
    } else if (prefix.match(/^#{1,6} /)) {
      // Heading switch: replace old heading level marker
      newLines = lines.map((l) => prefix + l.replace(/^#{1,6} /, ''));
    } else {
      newLines = lines.map((l) => prefix + l);
    }

    const newBlock = newLines.join('\n');
    newValue = value.slice(0, lineStart) + newBlock + value.slice(effectiveEnd);
    newStart = lineStart;
    newEnd = lineStart + newBlock.length;
  }

  if (action.type !== 'custom') {
    onChange(newValue);
  }
  return { newValue, newStart, newEnd };
}

Automated Formatting Verification

The pure formatting logic is thoroughly validated using vitest unit tests to ensure edge cases—such as multi-line prefix toggles or mid-string cursor placements—are handled cleanly:

// tests/applyAction.test.ts
import { describe, it, expect, vi } from 'vitest';
import { applyAction } from './applyAction';

describe('applyAction – linePrefix & wrap', () => {
  it('wraps selected text with bold markers', () => {
    const state = { value: 'hello world', selectionStart: 6, selectionEnd: 11 };
    const onChange = vi.fn();

    const { newValue, newStart, newEnd } = applyAction(
      state,
      { type: 'wrap', before: '**', after: '**', placeholder: 'text' },
      onChange
    );

    expect(newValue).toBe('hello **world**');
    expect(onChange).toHaveBeenCalledWith('hello **world**');
    expect(newStart).toBe(8);
    expect(newEnd).toBe(13);
  });

  it('switches heading level, removing old marker', () => {
    const state = { value: '# Old heading', selectionStart: 0, selectionEnd: 13 };
    const onChange = vi.fn();

    const { newValue } = applyAction(
      state,
      { type: 'linePrefix', prefix: '## ', placeholder: 'Heading 2' },
      onChange
    );

    expect(newValue).toBe('## Old heading');
  });
});

Rewriting with Rust & Tauri for Maximum Performance

While Electron allowed us to prototype a fully featured Markdown editor rapidly, bundling a ~150 MB Chromium binary and consuming ~200 MB of RAM at idle felt unnecessarily heavy. To create a lightweight, blazingly fast alternative, we rebuilt the application core using Rust and Tauri v2.

By leveraging Tauri, the application delegates rendering to the OS’s built-in web engine (WKWebView on macOS) while handing off high-performance logic, native menu creation, and non-blocking disk I/O entirely to a compiled Rust backend.

Architectural Overview

In the Tauri edition, the React UI runs inside the native WebKit window, while all system integrations and file mutations happen on asynchronously spawned Rust tasks.

┌──────────────────────────────────────────────────────────┐
│              Native Desktop Window (Rust)                │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │           WKWebView (OS Native Engine)             │  │
│  │  - React 18 UI / Live Preview / Local Mermaid      │  │
│  └─────────────────────────┬──────────────────────────┘  │
│                            │                             │
│                  IPC Channels (invoke / listen)          │
│                            │                             │
│  ┌─────────────────────────▼──────────────────────────┐  │
│  │                 Compiled Rust Backend              │  │
│  │  - Non-blocking File Dialogs (oneshot channels)    │  │
│  │  - Async Disk Write Operations                     │  │
│  │  - Native macOS System Menu Construction           │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Core Rust Implementation Details

Application Entry Point & Plugin Initializer

The main entry point sets up system-level plugins (file dialogs, shell handling, filesystem access), mounts custom commands, and constructs the native application menu during setup.

// src-tauri/src/main.rs
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

mod commands;
mod menu;

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_dialog::init())
        .plugin(tauri_plugin_fs::init())
        .plugin(tauri_plugin_shell::init())
        .invoke_handler(tauri::generate_handler![
            commands::file_open,
            commands::file_save,
            commands::file_save_as,
            commands::file_export_html,
        ])
        .setup(|app| {
            menu::build_menu(app)?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Non-Blocking File Dialogs & Async Disk Operations

To prevent blocking the Tokio runtime thread or freezing UI animations while waiting for a user to choose a file path, custom pickers utilize asynchronous oneshot channels to yield execution back to the event loop.

// src-tauri/src/commands.rs
use std::path::PathBuf;
use tauri::AppHandle;
use tauri_plugin_dialog::{DialogExt, FilePath};
use tokio::sync::oneshot;

#[derive(serde::Serialize)]
pub struct FileResult {
    pub path: String,
    pub name: String,
    pub content: Option<String>,
}

/// Asynchronous, non-blocking native file picker using Tokio oneshot channels
async fn pick_open_file(app: &AppHandle) -> Option<PathBuf> {
    let (tx, rx) = oneshot::channel();
    app.dialog()
        .file()
        .add_filter("Markdown Files", &["md"])
        .add_filter("All Files", &["*"])
        .pick_file(move |fp| {
            let _ = tx.send(fp);
        });
    match rx.await.ok()? {
        Some(FilePath::Path(p)) => Some(p),
        _ => None,
    }
}

/// Open a Markdown file and return its metadata + content
#[tauri::command]
pub async fn file_open(app: AppHandle) -> Result<Option<FileResult>, String> {
    let Some(path) = pick_open_file(&app).await else {
        return Ok(None);
    };

    let content = std::fs::read_to_string(&path).map_err(|e| e.to_string())?;
    let name = path
        .file_name()
        .unwrap_or_default()
        .to_string_lossy()
        .to_string();

    Ok(Some(FileResult {
        path: path.to_string_lossy().to_string(),
        name,
        content: Some(content),
    }))
}

/// Export live-rendered HTML output as a standalone file
#[tauri::command]
pub async fn file_export_html(
    app: AppHandle,
    html_content: String,
    title: String,
) -> Result<Option<FileResult>, String> {
    let default_name = format!("{}.html", title);
    let Some(p) = pick_save_file(&app, &default_name, "html", "HTML Document").await else {
        return Ok(None);
    };

    let document = format!(
        "<!DOCTYPE html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>{}</title>\n</head>\n<body>\n{}\n</body>\n</html>",
        title, html_content
    );

    std::fs::write(&p, document).map_err(|e| e.to_string())?;
    let name = p.file_name().unwrap_or_default().to_string_lossy().to_string();

    Ok(Some(FileResult {
        path: p.to_string_lossy().to_string(),
        name,
        content: None,
    }))
}

Native macOS Menu Routing & Event Dispatch

Tauri constructs native OS dropdown menus and maps native accelerator keys (such as Cmd+N, Cmd+S, Cmd+Shift+P) directly to event channels that emit clean messages directly into the React UI.

// src-tauri/src/menu.rs
use tauri::{
    menu::{Menu, MenuItem, PredefinedMenuItem, Submenu},
    App, Emitter,
};

pub fn build_menu(app: &mut App) -> tauri::Result<()> {
    let h = app.handle();

    // File Submenu
    let file_menu = Submenu::with_items(h, "File", true, &[
        &MenuItem::with_id(h, "file_new", "New", true, Some("CmdOrCtrl+N"))?,
        &MenuItem::with_id(h, "file_open", "Open…", true, Some("CmdOrCtrl+O"))?,
        &PredefinedMenuItem::separator(h)?,
        &MenuItem::with_id(h, "file_save", "Save", true, Some("CmdOrCtrl+S"))?,
        &MenuItem::with_id(h, "file_save_as", "Save As…", true, Some("CmdOrCtrl+Shift+S"))?,
        &PredefinedMenuItem::separator(h)?,
        &MenuItem::with_id(h, "file_export", "Export as HTML…", true, Some("CmdOrCtrl+E"))?,
        &PredefinedMenuItem::separator(h)?,
        &PredefinedMenuItem::close_window(h, Some("Close"))?,
    ])?;

    let menu = Menu::with_items(h, &[&file_menu])?;
    app.set_menu(menu)?;

    // Global Menu Event Handler
    app.on_menu_event(move |app_handle, event| {
        let id = event.id().0.as_str();
        let payload_channel = match id {
            "file_new" => "menu:new",
            "file_open" => "menu:open",
            "file_save" => "menu:save",
            "file_save_as" => "menu:saveAs",
            "file_export" => "menu:exportHtml",
            _ => return,
        };

        // Emit native event directly into WKWebView JS context
        let _ = app_handle.emit(payload_channel, ());
    });

    Ok(())
}

Both applications have the same exact UI

And once the build is made, either app could be launched through an icon!

Conclusion

What started as a sudden licensing headache turned into one of the most rewarding weekend projects I’ve tackled in a while. Having an AI partner like Bob made bridging the gap from concept to a native, dual-architecture desktop app surprisingly fast — and now I have a lightweight, tailored editor that fits my workflow perfectly. Both the Electron and Rust/Tauri versions are completely open-source, so feel free to explore the repository, grab the latest builds, or even customize the code for your own setup. Happy writing, and may your Markdown files always render smoothly!

Thanks for reading 🎴

Kubernetes Architectural Shift: Moving Workloads from Rancher Desktop (K3s) to Managed Cluster (part 1)

Alain Airom (Ayrom) — Fri, 31 Jul 2026 16:21:31 +0000

Enterprise Production vs. Local Prototyping: IBM Kubernetes Service (IKS) vs. Rancher Desktop!

Introduction and context

Following a recent technical discussion regarding the tradeoffs between managed cloud services — such as IBM Kubernetes Service (IKS) — and local development environments like Rancher Desktop, I put together a detailed comparison framework. Here is the breakdown, to shift from a local kubernetes development to an enterprise scale platfom.

I’ve been posting a ton about LLMs, RAG, and vector search lately, but don’t worry — I haven’t gone totally soft. Infrastructure and cluster environments are still my primary passion. Because at the end of the day, even the smartest AI is just a glorified math model sitting on a worker node that someone has to keep from running out of disk space.

The modern container lifecycle spans two distinct operational realms: local developer desktop prototyping and enterprise production execution.

Rancher Desktop **runs locally on developer workstations (macOS, Windows, Linux) by encapsulating a single-node **K3s or containerd runtime inside a desktop hypervisor (Lima VM / WSL2). It accelerates local iteration without cloud infrastructure costs.

Developer Laptop (macOS / Windows / Linux)
└── Rancher Desktop (Electron App)
    └── Virtual Machine (Lima VM / WSL2)
        └── Single-Node K3s Cluster
            ├── Control Plane (same node as worker)
            │   ├── Kubernetes API Server
            │   ├── etcd (or SQLite for K3s lite mode)
            │   ├── Scheduler
            │   └── Controller Manager
            │
            └── Worker (same node)
                ├── App Pods (nginx-demo)
                ├── containerd / dockerd
                ├── Local Storage (hostPath)
                └── Traefik Ingress (built-in)

Developer Tooling (Host OS)
├── Rancher Desktop GUI
├── kubectl / helm (bundled)
├── docker / nerdctl (bundled)
└── Port Forwarding (localhost)

⚠️ Constraints:
   - No external load balancer provisioner
   - No IAM / no enterprise RBAC
   - No managed TLS certificates
   - No cluster autoscaler
   - Constrained by laptop CPU/RAM

IBM Kubernetes Service (IKS) is a fully managed enterprise cloud platform operating across multi-zone availability regions on IBM Cloud Virtual Private Cloud (VPC). The control plane is fully managed by IBM SREs with a 99.99% SLA, delivering zero-trust networking, hardware security, automated patching, and compliance capabilities.

IBM Cloud (VPC Region)
├── Managed Control Plane (IBM-managed, HA)
│   ├── Kubernetes API Server (HA, multi-zone)
│   ├── etcd (HA cluster, encrypted)
│   ├── Scheduler
│   ├── Controller Manager
│   └── Admission Controllers (Pod Security, OPA)
│
├── Worker Node Pool (User-managed, VPC VSIs)
│   ├── Worker Node 1 (Zone A) ──► App Pods
│   ├── Worker Node 2 (Zone B) ──► App Pods
│   └── Worker Node 3 (Zone C) ──► App Pods
│
├── IBM Cloud Services (Native Integrations)
│   ├── IBM Cloud IAM (authentication & authorization)
│   ├── IBM Container Registry (private, CVE-scanned)
│   ├── IBM Key Protect (KMS, secrets encryption)
│   ├── IBM Cloud Logs (centralized logging)
│   ├── IBM Cloud Monitoring / Sysdig (metrics)
│   ├── VPC Load Balancers (ALB / NLB)
│   └── VPC Block / File / Object Storage (CSI)
│
└── VPC Networking
    ├── VPC Security Groups
    ├── Network ACLs
    ├── Calico network policies
    └── Ingress (Traefik / NGINX ALB)

Comparison using a sample Deployment: ‘nginx-demo’ (illustration purpose)

| Aspect                | IKS (`deployments/iks/`)                                     | Rancher Desktop (`deployments/rancher/`) |
| --------------------- | ------------------------------------------------------------ | ---------------------------------------- |
| **Replicas**          | 3 (spread across zones)                                      | 1 (single node)                          |
| **Pod Anti-Affinity** | ✅ topology.kubernetes.io/zone                                | ❌ Not applicable                         |
| **Image Pull**        | IBM Container Registry (private)                             | Docker Hub (public)                      |
| **Security Context**  | runAsNonRoot, readOnlyRootFilesystem, capabilities: drop ALL | Basic                                    |
| **Service Type**      | `LoadBalancer` → VPC ALB provisioned                         | `NodePort` → localhost:30080             |
| **Ingress TLS**       | Managed cert (IBM Secrets Manager)                           | Self-signed / manual                     |
| **Storage**           | VPC Block Storage (10 IOPS/GB, encrypted)                    | hostPath (local dir)                     |
| **HPA**               | 3–10 replicas, CPU+Memory metrics                            | N/A                                      |

Namespace Configuration

Rancher Desktop (namespace.yaml): Local environments focus on environment separation for quick developer isolation.

apiVersion: v1
kind: Namespace
metadata:
  name: nginx-demo
  labels:
    app.kubernetes.io/name: nginx-demo
    environment: development
    platform: rancher-desktop

*IBM Kubernetes Service *(namespace.yaml): Production namespaces integrate with IBM Cloud IAM policies and enterprise environment governance.

apiVersion: v1
kind: Namespace
metadata:
  name: nginx-demo
  labels:
    app.kubernetes.io/name: nginx-demo
    environment: production
    platform: iks

Deployment Configuration

Rancher Desktop (deployment.yaml): Designed for single-replica execution with simple resource boundaries and local host path volumes.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
  namespace: nginx-demo
  labels:
    app: nginx-demo
    version: "1.0"
    platform: rancher-desktop
spec:
  replicas: 1                          # ⚠️ Single replica — no High Availability
  selector:
    matchLabels:
      app: nginx-demo
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: nginx-demo
        version: "1.0"
    spec:
      # No imagePullSecrets needed — uses local image cache or Docker Hub
      containers:
        - name: nginx-demo
          image: nginx:1.25-alpine
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi
          livenessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 10
            periodSeconds: 20
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 10
          volumeMounts:
            - name: nginx-html
              mountPath: /usr/share/nginx/html
      volumes:
        # ⚠️ hostPath volume — tightly coupled to local workstation storage
        - name: nginx-html
          hostPath:
            path: /tmp/nginx-html
            type: DirectoryOrCreate

IBM Kubernetes Service (deployment.yaml): Designed for zero-downtime, multi-zone resiliency, non-root execution, dropped Linux capabilities, and private container registry integration.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
  namespace: nginx-demo
  labels:
    app: nginx-demo
    version: "1.0"
    platform: iks
spec:
  replicas: 3                          # Replicas spread across worker nodes/zones
  selector:
    matchLabels:
      app: nginx-demo
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0                # Zero-downtime rolling updates
  template:
    metadata:
      labels:
        app: nginx-demo
        version: "1.0"
    spec:
      # Pull from IBM Cloud Container Registry (private, scanned for CVEs)
      imagePullSecrets:
        - name: icr-secret

      # Pod Anti-Affinity: Force pod distribution across availability zones
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values:
                        - nginx-demo
                topologyKey: topology.kubernetes.io/zone

      # Pod-level security context
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 2000

      containers:
        - name: nginx-demo
          image: icr.io/your-namespace/nginx-demo:1.0.0
          ports:
            - containerPort: 8080
              protocol: TCP

          # Container-level hardened security context
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

          livenessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 20
            failureThreshold: 3

          readinessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
            successThreshold: 1

          volumeMounts:
            - name: nginx-cache
              mountPath: /var/cache/nginx
            - name: nginx-run
              mountPath: /var/run
      volumes:
        - name: nginx-cache
          emptyDir: {}
        - name: nginx-run
          emptyDir: {}

Service & Exposure

Rancher Desktop (service.yaml): Exposes services using NodePort on host loopback interfaces.

apiVersion: v1
kind: Service
metadata:
  name: nginx-demo
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: rancher-desktop
spec:
  type: NodePort               # ⚠️ No cloud LoadBalancer available locally
  selector:
    app: nginx-demo
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 80
      nodePort: 30080           # Exposed at http://localhost:30080

IBM Kubernetes Service (service.yaml): Automatically triggers the provisioning of an IBM Cloud VPC Application Load Balancer (ALB).

apiVersion: v1
kind: Service
metadata:
  name: nginx-demo
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: iks
  annotations:
    # Provisions an IBM Cloud VPC Application Load Balancer (ALB)
    service.beta.kubernetes.io/ibm-load-balancer-cloud-provider-enable-features: "proxy-protocol"
spec:
  type: LoadBalancer           # Triggers VPC Load Balancer creation
  selector:
    app: nginx-demo
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 8080
    - name: https
      protocol: TCP
      port: 443
      targetPort: 8080

Ingress & TLS Termination

Rancher Desktop (ingress.yaml): Uses local embedded Traefik ingress controller without managed TLS certificates.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-demo-ingress
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: rancher-desktop
  annotations:
    kubernetes.io/ingress.class: traefik
spec:
  rules:
    - host: nginx-demo.localhost         # Managed locally via /etc/hosts
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nginx-demo
                port:
                  number: 80

IBM Kubernetes Service (ingress.yaml): Integrates directly with managed public cluster subdomains and IBM Secrets Manager for TLS certificate lifecycle management.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-demo-ingress
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: iks
  annotations:
    kubernetes.io/ingress.class: "public-iks-k8s-nginx"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    ingress.bluemix.net/redirect-to-https: "True"
spec:
  tls:
    - hosts:
        - nginx-demo.<YOUR-CLUSTER-NAME>.<REGION>.containers.appdomain.cloud
      secretName: nginx-demo-tls  # Automated TLS cert via IBM Secrets Manager
  rules:
    - host: nginx-demo.<YOUR-CLUSTER-NAME>.<REGION>.containers.appdomain.cloud
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nginx-demo
                port:
                  number: 80

Persistent Storage

Rancher Desktop Storage: Local storage uses direct host path mounts or default local path provisioners without encryption.
IBM Kubernetes Service (pvc.yaml): Integrates with the IBM Cloud VPC Block Storage CSI driver, leveraging tier-based IOPS and encryption at rest with IBM Key Protect.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: nginx-demo-storage
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: iks
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: ibmc-vpc-block-10iops-tier   # Dynamic VPC Block CSI (10 IOPS/GB)
  resources:
    requests:
      storage: 10Gi

Autoscaling (HPA)

Rancher Desktop Autoscaling: While the Kubernetes HPA controller can run locally, scaling is bounded by the developer workstation’s CPU and RAM allocation.
IBM Kubernetes Service (hpa.yaml): Enables dynamic pod scaling alongside Cluster Autoscaler integration for expanding physical worker nodes in response to load spikes.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-demo-hpa
  namespace: nginx-demo
  labels:
    app: nginx-demo
    platform: iks
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-demo
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300    # 5-minute cooldown before scale-down
      policies:
        - type: Pods
          value: 1
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Pods
          value: 2
          periodSeconds: 30

Security Comparison

Authentication & Authorization

| Layer            | IKS                                | Rancher Desktop        |
| ---------------- | ---------------------------------- | ---------------------- |
| **User Auth**    | IBM Cloud IAM (SAML, SSO, MFA)     | kubeconfig certificate |
| **Service Auth** | Trusted Profiles, Service IDs      | ServiceAccount tokens  |
| **RBAC**         | Full Kubernetes RBAC + IAM mapping | Basic Kubernetes RBAC  |
| **Audit Logs**   | ✅ IBM Cloud Activity Tracker       | ❌ Limited              |

Data Encryption

| Layer                        | IKS                                   | Rancher Desktop                         |
| ---------------------------- | ------------------------------------- | --------------------------------------- |
| **etcd**                     | ✅ Encrypted at rest (IBM Key Protect) | ⚠️ Local disk (OS-level encryption only) |
| **Secrets**                  | ✅ KMS-wrapped via IBM Key Protect     | ❌ Base64 only (plaintext in etcd)       |
| **Worker Node Disk**         | ✅ IBM-managed encrypted VSI disk      | ⚠️ Host OS encryption                    |
| **Worker-to-Worker Traffic** | ✅ WireGuard VPN encryption            | ❌ Unencrypted intra-VM                  |
| **Storage (PVC)**            | ✅ IBM VPC Block Storage encrypted     | ❌ Local hostPath, unencrypted           |
| **TLS (Ingress)**            | ✅ Managed, auto-renewed certificates  | ⚠️ Manual self-signed                    |

Network Security

| Layer                          | IKS                               | Rancher Desktop   |
| ------------------------------ | --------------------------------- | ----------------- |
| **Network Policies**           | ✅ Calico (full L3/L4 policies)    | ✅ Flannel (basic) |
| **VPC Security Groups**        | ✅ Worker node level               | ❌ N/A             |
| **Network ACLs**               | ✅ VPC subnet level                | ❌ N/A             |
| **Private Endpoint**           | ✅ API server accessible privately | ❌ Only localhost  |
| **Context-Based Restrictions** | ✅ IBM Cloud CBR                   | ❌ N/A             |

Compliance

IKS is certified and compliant with:

SOC 1 Type II, SOC 2 Type II
ISO 27001, ISO 27017, ISO 27018
PCI DSS (Payment Card Industry)
HIPAA (Healthcare)
FedRAMP (US Government)
C5 (Germany)
CIS Kubernetes Benchmark (score published per version)

Rancher Desktop has no compliance certifications — it is a local development tool.

Security Summary: Why Rancher Desktop Cannot Replace IKS

| Security Control                 | IKS                           | Rancher Desktop    | Risk Without It                                  |
| -------------------------------- | ----------------------------- | ------------------ | ------------------------------------------------ |
| Enterprise identity (IAM/MFA)    | ✅ IBM Cloud IAM               | ❌ kubeconfig only  | Credential theft gives full cluster access       |
| Secrets encrypted in etcd        | ✅ IBM Key Protect (KMS)       | ❌ Base64 plaintext | Secrets exposed if etcd volume is compromised    |
| Pod-to-pod traffic encryption    | ✅ WireGuard VPN               | ❌ Unencrypted      | Lateral movement / eavesdropping in-cluster      |
| Network segmentation             | ✅ VPC Security Groups + ACLs  | ❌ Flat VM network  | Any compromised pod can reach all other services |
| Image vulnerability scanning     | ✅ ICR + Vulnerability Advisor | ❌ None             | Undetected CVEs deployed to workloads            |
| Pod Security Admission enforced  | ✅ Yes (block privileged pods) | ⚠️ Not enforced     | Privileged container escape possible             |
| Audit trail (who did what, when) | ✅ IBM Cloud Activity Tracker  | ❌ None             | No forensics capability after incident           |
| Compliance evidence              | ✅ IBM-managed audit reports   | ❌ None             | Cannot satisfy regulator or auditor requirements |

IKS on VPC — The Secure Deployment Model

IBM Cloud VPC (Virtual Private Cloud) is the recommended and most secure infrastructure type for IKS clusters. Deploying IKS on VPC transforms the cluster from an internet-connected compute cluster into a network-isolated, privately governed Kubernetes environment.

What VPC Adds to IKS Security?

Rancher Desktop operates inside a single VM on a developer laptop — there is no concept of network perimeter, subnet segregation, or infrastructure-level firewall. IKS on VPC introduces multiple independent security layers at the infrastructure level, before a single Kubernetes packet is processed:

Internet
    │
    ▼
IBM Cloud Internet Services (CIS)
    │  DDoS Protection, WAF, Rate Limiting, TLS Offload
    ▼
VPC Public Gateway / Floating IP
    │
    ▼
VPC Application Load Balancer (ALB)
    │  TLS Termination, Managed Certificate, L7 Routing
    ▼
VPC Subnet (Public)
    │  Network ACL — stateless L3/L4 filter
    ▼
VPC Security Group (Worker Node level)
    │  Stateful L4 filter — port-level allow/deny per VSI
    ▼
IKS Worker Node (VSI — encrypted disk)
    │
    ├── Calico Network Policies (pod-level L3/L4)
    ├── WireGuard (encrypted pod-to-pod traffic)
    └── Kubernetes API Server (private endpoint only)

VPC Network Architecture for IKS

A production-grade IKS-on-VPC deployment uses a tiered subnet model:

| Subnet Tier               | Purpose                               | Internet Access             | Examples                            |
| ------------------------- | ------------------------------------- | --------------------------- | ----------------------------------- |
| **Public Subnet**         | Edge / Load Balancer tier             | Inbound via ALB only        | VPC ALB                             |
| **Private Subnet (App)**  | Worker nodes running application pods | Outbound via Public Gateway | App pods, nginx-demo                |
| **Private Subnet (Data)** | Databases, object storage endpoints   | Outbound only               | IBM Cloud Object Storage endpoint   |
| **Private Subnet (Mgmt)** | Kubernetes API server, bastion host   | Outbound only               | `kubectl` API endpoint, VPN Gateway |

Worker nodes are placed exclusively on private subnets — they have no public IP addresses. All inbound traffic flows through the VPC ALB on the public subnet. The Kubernetes API server is reachable only via a private service endpoint or through a VPN/Direct Link connection.

VPC Security Groups — Worker Node Firewall

Every IKS worker node VSI is governed by a VPC Security Group that acts as a stateful firewall. IBM automatically provisions and manages the required rules; additional rules can be applied per workload

| Direction    | Protocol | Port        | Purpose                            |
| ------------ | -------- | ----------- | ---------------------------------- |
| Inbound      | TCP      | 30000–32767 | NodePort services (internal only)  |
| Inbound      | TCP      | 443         | Kubernetes API server              |
| Inbound      | TCP      | 10250       | Kubelet API (internal VPC only)    |
| Outbound     | TCP      | 443         | IBM Cloud services (ICR, KP, Logs) |
| Outbound     | All      | All         | Pod egress (controlled by Calico)  |
| **Deny All** | *        | *           | Default deny all other traffic     |

Rancher Desktop has no equivalent — the Lima VM has a flat network with no firewall or security group concept.

VPC Network ACLs — Subnet-Level Firewall

In addition to Security Groups (instance-level), VPC Network ACLs provide stateless subnet-level filtering — the equivalent of a traditional network firewall rule set applied at the subnet boundary:

Block all traffic between subnets unless explicitly permitted
Enforce east-west isolation between application tiers (app ↔ data subnet restricted)
Provide an additional defence layer even if a Security Group is misconfigured

Private Kubernetes API Server Endpoint

On IKS VPC clusters, the Kubernetes API server can be made accessible only via private VPC endpoints. This means:

kubectl commands must originate from within the VPC, a VPN tunnel, or IBM Cloud Direct Link
The API server is not exposed to the public internet at any IP address
Eliminates an entire class of API server brute-force / credential-stuffing attacks

# Enable private-only endpoint on an IKS VPC cluster
ibmcloud ks cluster master private-service-endpoint enable --cluster <cluster-name>
ibmcloud ks cluster master refresh --cluster <cluster-name>

# Verify
ibmcloud ks cluster get --cluster <cluster-name> | grep 'Private Service Endpoint'
# → Private Service Endpoint URL: https://c1.private.us-south.containers.cloud.ibm.com:xxxx

Rancher Desktop’s API server is accessible only on 127.0.0.1 (localhost) — this provides isolation by default, but that isolation is purely because it runs on a single laptop, not because of any security design.

IBM Cloud Context-Based Restrictions (CBR)

IKS VPC clusters support IBM Cloud Context-Based Restrictions (CBR), which enforce zero-trust access policies at the IBM Cloud control plane level — before a request ever reaches the Kubernetes API:

Restrict ibmcloud ks API calls to specific IP ranges (e.g., corporate network CIDRs)
Restrict access to the Kubernetes API server based on network zone membership
Combine with IAM policies for multi-factor access control: who (IAM) + from where (CBR)

Traditional security:   WHO can do WHAT  (IAM)
Zero-trust with CBR:    WHO + FROM WHERE can do WHAT  (IAM + CBR)

Rancher Desktop has no equivalent — there is no control plane access restriction mechanism.

VPC Flow Logs for Security Auditing

VPC Flow Logs capture all accepted and rejected network traffic at the VPC subnet level and ship them to IBM Cloud Object Storage for forensic analysis:

# Enable VPC flow logs for the IKS worker subnet
ibmcloud is flow-log-create \
  --name iks-worker-flowlogs \
  --target <subnet-id> \
  --storage-bucket <cos-bucket-name>

This provides a full network audit trail — which source IPs connected to which worker node ports, when, and whether the connection was allowed or blocked. This data is essential for security incident response and compliance evidence (PCI DSS, HIPAA).

Rancher Desktop produces no network flow data at all.

IBM Cloud Key Protect — Encryption Architecture on VPC

When IKS runs on VPC, IBM Key Protect (or Hyper Protect Crypto Services for FIPS 140–2 Level 4) manages the encryption key hierarchy:

IBM Key Protect (HSM-backed)
    │
    ├── Root Key (customer-controlled, never leaves HSM)
    │       │
    │       ▼
    │   Data Encryption Keys (DEK) — envelope encryption
    │       │
    │       ├── etcd volume encryption (Kubernetes secrets at rest)
    │       ├── VPC Block Storage encryption (PVC data at rest)
    │       └── IBM Container Registry image layer encryption
    │
    └── Key Rotation: automatic (90-day policy) or manual

If a Key Protect root key is revoked, the associated etcd and storage volumes become immediately unreadable — a critical capability for regulated environments where data must be rendered permanently inaccessible on contract termination or incident response.

Rancher Desktop has no key management: Kubernetes secrets are stored as Base64-encoded plaintext in a local SQLite/etcd file on the developer’s laptop disk.

What IKS Gives You Automatically (vs Rancher)?

When deploying on IKS, the following happen automatically — none of these are available on Rancher Desktop without significant manual effort:

| Automatic IKS Feature                            | Equivalent Manual Effort on Rancher Desktop                  |
| ------------------------------------------------ | ------------------------------------------------------------ |
| VPC Load Balancer provisioned with external IP   | Manually configure NodePort + external LoadBalancer (unsupported locally) |
| TLS certificate from Secrets Manager             | Generate self-signed cert, manually create k8s Secret        |
| Pods spread across availability zones            | Not possible (single node)                                   |
| IBM Container Registry pull credentials injected | Manually handle Docker Hub rate limiting                     |
| VPC Block Storage dynamically provisioned        | Manually configure hostPath or local-path-provisioner        |
| IBM Cloud Logs captures pod logs                 | Set up EFK/PLG stack manually                                |
| IBM Cloud Monitoring scrapes metrics             | Install Prometheus + Grafana manually                        |
| HPA scales pods on CPU/Memory                    | Works but constrained by host laptop RAM/CPU                 |
| Node auto-repair (replace unhealthy nodes)       | Restart Rancher Desktop or VM                                |
| Worker node security updates applied             | Manually update Rancher Desktop version                      |

IKS on VPC vs Rancher Desktop — Security Summary

| Security Dimension          | IKS on VPC                 | IKS on Classic | Rancher Desktop  |
| --------------------------- | -------------------------- | -------------- | ---------------- |
| Network perimeter (VPC)     | ✅ Full VPC isolation       | ⚠️ VLAN-based   | ❌ None           |
| Subnet segmentation         | ✅ Public/Private subnets   | ⚠️ Limited      | ❌ None           |
| Worker node firewall        | ✅ VPC Security Groups      | ⚠️ IKS-managed  | ❌ None           |
| Subnet firewall             | ✅ VPC Network ACLs         | ❌ N/A          | ❌ None           |
| Private API server          | ✅ Private service endpoint | ✅ Yes          | ⚠️ localhost only |
| VPC Flow Logs               | ✅ Full capture             | ❌ N/A          | ❌ None           |
| Context-Based Restrictions  | ✅ Full support             | ✅ Yes          | ❌ None           |
| KMS (Key Protect)           | ✅ Yes                      | ✅ Yes          | ❌ None           |
| FIPS 140-2 Level 4 (HPCS)   | ✅ Available                | ✅ Available    | ❌ None           |
| Worker-to-worker encryption | ✅ WireGuard                | ✅ WireGuard    | ❌ None           |
| Pod Security Admission      | ✅ Enforced                 | ✅ Enforced     | ⚠️ Not enforced   |
| Calico network policies     | ✅ Full L3/L4               | ✅ Full L3/L4   | ✅ Basic only     |
| Image vulnerability scan    | ✅ ICR + VA                 | ✅ ICR + VA     | ❌ None           |
| Compliance certifications   | ✅ SOC2/HIPAA/PCI/FedRAMP   | ✅ Yes          | ❌ None           |

Management Advantages of IKS over Rancher Desktop

Managed Control Plane — Zero Operator Burden

The single largest management difference: IBM fully manages the Kubernetes control plane.

| Management Task                             | IKS                              | Rancher Desktop                     |
| ------------------------------------------- | -------------------------------- | ----------------------------------- |
| Kubernetes version upgrades (control plane) | ✅ IBM-managed, one-click upgrade | ❌ Manual: reinstall Rancher Desktop |
| etcd backup & restore                       | ✅ IBM-managed (automated)        | ❌ Manual or none                    |
| API server certificate rotation             | ✅ Automatic                      | ❌ Manual                            |
| Control plane OS patching                   | ✅ IBM-managed                    | ❌ Tied to desktop OS update         |
| Control plane HA failover                   | ✅ Automatic (3+ replicas)        | ❌ Not available                     |
| Control plane monitoring                    | ✅ IBM SRE team monitors 24/7     | ❌ None                              |

In practice, a team running a self-managed Kubernetes control plane requires dedicated SRE engineers for etcd management alone. IKS eliminates this entirely.

Worker Node Lifecycle Management

| Management Task                       | IKS                                     | Rancher Desktop            |
| ------------------------------------- | --------------------------------------- | -------------------------- |
| Worker node OS security patches       | ✅ `ibmcloud ks worker update` (rolling) | ❌ Full reinstall           |
| Worker node replacement (failed node) | ✅ Automatic detection + replacement     | ❌ Restart app or reinstall |
| Worker node version upgrades          | ✅ Rolling upgrade across worker pools   | ❌ Full reinstall           |
| Worker node disk encryption           | ✅ IBM-managed (always on)               | ⚠️ Host OS dependent        |
| GPU driver management                 | ✅ IBM-managed NVIDIA drivers            | ❌ Manual                   |
| Custom machine types                  | ✅ Full VSI catalog (bx2, mx2, cx2, gx2) | ❌ Fixed laptop specs       |

Add-Ons and Managed Integrations

IKS provides a curated set of managed add-ons that IBM versions, patches, and monitors. Each add-on would otherwise require the team to install, configure, and maintain it themselves:

| Add-On                        | IKS Managed                                             | Manual equivalent for Rancher |
| ----------------------------- | ------------------------------------------------------- | ----------------------------- |
| Cluster Autoscaler            | ✅ `ibmcloud ks cluster addon enable cluster-autoscaler` | Not possible                  |
| Managed Istio                 | ✅ `ibmcloud ks cluster addon enable istio`              | Manual Helm + complex config  |
| Knative (Serverless)          | ✅ One-click enable                                      | Manual Helm                   |
| IBM Cloud Monitoring (Sysdig) | ✅ Managed agent                                         | Manual Prometheus + Grafana   |
| IBM Cloud Logs (Fluent Bit)   | ✅ Managed agent                                         | Manual EFK/PLG stack          |
| VPC Block Storage CSI         | ✅ Pre-installed                                         | Not available                 |
| Image Key Enforcer            | ✅ Policy: only signed images allowed                    | Manual OPA/Kyverno            |
| ALB Ingress Controller        | ✅ IBM-managed NGINX ALB                                 | Manual Helm + manual cert     |
| Tekton Pipelines              | ✅ Managed add-on                                        | Manual Helm install           |

Integrated Observability (No Setup Required)

One of the most significant hidden costs of Rancher Desktop for production use is the absence of any managed observability stack. Everything must be manually installed, configured, and maintained.

| Observability Capability | IKS                                | Rancher Desktop      | Setup Cost (Rancher)       |
| ------------------------ | ---------------------------------- | -------------------- | -------------------------- |
| Pod & container logs     | ✅ IBM Cloud Logs (auto-forwarded)  | `kubectl logs` only  | ~2–4 days (EFK stack)      |
| Node & cluster metrics   | ✅ IBM Cloud Monitoring             | None                 | ~1–2 days (Prometheus)     |
| Pre-built dashboards     | ✅ Sysdig IKS dashboards            | None                 | ~1 day (Grafana)           |
| Alerting                 | ✅ Managed alerts (PagerDuty/email) | None                 | ~1 day                     |
| Distributed tracing      | ✅ IBM Cloud Tracing                | None                 | ~2 days (Jaeger)           |
| Kubernetes events        | ✅ Activity Tracker + Cloud Logs    | `kubectl get events` | ~1 day                     |
| **Total setup**          | **0 days**                         | —                    | **~7–12 engineering days** |

For a small team, the observability setup alone can represent weeks of engineering effort that IKS eliminates.

RBAC and Multi-Team Access Management

| Scenario                       | IKS                                                   | Rancher Desktop                            |
| ------------------------------ | ----------------------------------------------------- | ------------------------------------------ |
| New developer onboards         | Add to IBM Cloud IAM group → automatic cluster access | Generate new kubeconfig manually           |
| Developer leaves team          | Remove from IAM group → access revoked cluster-wide   | Manually rotate cluster certificates       |
| Team-level namespace isolation | IAM role → Kubernetes RBAC binding (automated)        | Manually create RoleBindings per namespace |
| Service account for CI/CD      | IBM Cloud Service ID + API key + IAM policy           | Manually create SA + kubeconfig            |
| MFA enforcement                | ✅ IBM Cloud IAM MFA                                   | ❌ Not possible                             |
| SSO (SAML, OIDC)               | ✅ IBM Verify, Active Directory                        | ❌ Not possible                             |

IKS ties Kubernetes RBAC directly to IBM Cloud IAM. When a user’s IAM access is revoked (e.g., employee offboarding), their Kubernetes access is revoked simultaneously — no manual certificate rotation required.

IBM Cloud Console — Single Pane of Glass

IKS integrates with the IBM Cloud console to provide a single management interface across all cluster resources:

Visual cluster health dashboard (nodes, pods, events)
Worker pool management (add/remove nodes, resize)
Add-on management (enable/disable/upgrade)
Logging and monitoring links (direct to Sysdig/IBM Cloud Logs)
Cost breakdown per cluster, per worker pool
VPC topology visualization

Rancher Desktop’s built-in UI is limited to the K3s dashboard — no cloud integration, no cost data, no infrastructure view.

Automated Cluster Versioning and Upgrade Path

IBM publishes a clear Kubernetes version support lifecycle for IKS:

IKS Kubernetes Version Lifecycle:
  Supported: 1.33, 1.34, 1.35, 1.36
  Each version supported for ~14 months after release

Upgrade process (control plane + workers):
  ibmcloud ks cluster master update --cluster <name> --version 1.35
  ibmcloud ks worker update --cluster <name> --worker <id>

  → Rolling update: zero-downtime if pods have PodDisruptionBudgets
  → IBM runs preflight checks before upgrade begins
  → Rollback window: 24h if issues detected

Rancher Desktop upgrades are done by the developer installing a new version of the desktop application — there is no rolling upgrade, no preflight check, and no rollback.

Networking Comparison

Load Balancing

| Capability                         | IKS                                 | Rancher Desktop          |
| ---------------------------------- | ----------------------------------- | ------------------------ |
| **Cloud Load Balancer (L4)**       | ✅ VPC NLB (Network LB)              | ❌ Not available          |
| **Application Load Balancer (L7)** | ✅ VPC ALB with SSL termination      | ❌ Not available          |
| **Ingress Controller**             | ✅ Traefik or NGINX (managed)        | ✅ Traefik (K3s built-in) |
| **External DNS**                   | ✅ IBM Cloud DNS Services            | ⚠️ /etc/hosts only        |
| **Global Load Balancer**           | ✅ IBM Cloud Internet Services (CIS) | ❌ N/A                    |

DNS

IKS: IBM automatically provisions an Ingress subdomain (<cluster>.<region>.containers.appdomain.cloud) with wildcard DNS. Custom domains supported via IBM Cloud DNS.
Rancher Desktop: DNS resolves only within the VM and on localhost. Must manually edit /etc/hosts for custom hostnames.

Storage

| Storage Type             | IKS                                                       | Rancher Desktop                         |
| ------------------------ | --------------------------------------------------------- | --------------------------------------- |
| **Block Storage (RWO)**  | ✅ IBM VPC Block Storage (CSI), encrypted, snapshotable    | ⚠️ local-path-provisioner, no encryption |
| **File Storage (RWX)**   | ✅ IBM VPC File Storage (NFS)                              | ❌ Not available                         |
| **Object Storage**       | ✅ IBM Cloud Object Storage (S3-compatible)                | ❌ Not available                         |
| **StorageClass**         | `ibmc-vpc-block-10iops-tier`, `ibmc-vpc-block-5iops-tier` | `local-path` (default)                  |
| **Dynamic Provisioning** | ✅ Yes (CSI driver)                                        | ✅ Yes (local-path only)                 |
| **Volume Snapshots**     | ✅ Yes                                                     | ❌ No                                    |
| **Encryption at Rest**   | ✅ Yes (IBM Key Protect)                                   | ❌ No                                    |
| **Multi-Zone Storage**   | ✅ Regional snapshots                                      | ❌ N/A                                   |
| **Portworx**             | ✅ Enterprise storage add-on                               | ❌ N/A                                   |

Observability & Monitoring

Logging

| Capability             | IKS                                   | Rancher Desktop     |
| ---------------------- | ------------------------------------- | ------------------- |
| **Pod Logs**           | ✅ kubectl + IBM Cloud Logs forwarding | ✅ kubectl logs only |
| **Cluster Audit Logs** | ✅ IBM Cloud Activity Tracker          | ❌ Limited           |
| **Node Logs**          | ✅ Forwarded to IBM Cloud Logs         | ❌ Manual journalctl |
| **Log Retention**      | ✅ Configurable (days/months)          | N/A                 |
| **Log Search**         | ✅ IBM Cloud Logs (Lucene queries)     | ❌ No                |

Metrics

| Capability            | IKS                             | Rancher Desktop       |
| --------------------- | ------------------------------- | --------------------- |
| **Container Metrics** | ✅ IBM Cloud Monitoring (Sysdig) | ❌ Manual (Prometheus) |
| **Node Metrics**      | ✅ Yes                           | ❌ Manual              |
| **Custom Metrics**    | ✅ Yes (Sysdig PromQL)           | ❌ Manual              |
| **Alerting**          | ✅ IBM Cloud Monitoring alerts   | ❌ Manual              |
| **Dashboard**         | ✅ Pre-built Sysdig dashboards   | ❌ Manual Grafana      |

Tracing

| Capability              | IKS                                  | Rancher Desktop  |
| ----------------------- | ------------------------------------ | ---------------- |
| **Distributed Tracing** | ✅ IBM Cloud Tracing (Instana/Jaeger) | ❌ Manual install |
| **Istio Integration**   | ✅ Managed Istio add-on + Kiali       | ❌ Manual         |

Autoscaling

Horizontal Pod Autoscaler (HPA)

Both platforms support HPA, but with key differences:

| Aspect              | IKS                            | Rancher Desktop          |
| ------------------- | ------------------------------ | ------------------------ |
| **Available**       | ✅ Yes                          | ✅ Yes (but limited)      |
| **Metrics Sources** | CPU, Memory, custom (Sysdig)   | CPU, Memory only         |
| **Scale Range**     | 1 to hundreds (cloud capacity) | 1 to few (laptop memory) |
| **Scaling Speed**   | Fast (cloud VSI provisioning)  | Fast (same node)         |

Vertical Pod Autoscaler (VPA)

IKS: Supported, recommends right-sized resource requests.
Rancher Desktop: Available but must be manually installed; constrained by host resources.

Cluster Autoscaler (Worker Node Scaling)

This is a critical IKS advantage — IKS can automatically provision and deprovision VPC Virtual Server Instances (worker nodes) based on pending pod requests.

| Aspect           | IKS                                     | Rancher Desktop |
| ---------------- | --------------------------------------- | --------------- |
| **Available**    | ✅ Yes (managed add-on)                  | ❌ Not possible  |
| **Scale-Out**    | New worker nodes provisioned in minutes | N/A             |
| **Scale-In**     | Drain + terminate idle nodes            | N/A             |
| **Cost Savings** | Automatically scales down at night      | N/A             |

High Availability (HA) & Disaster Recovery (DR)

| Aspect                    | IKS                              | Rancher Desktop    |
| ------------------------- | -------------------------------- | ------------------ |
| **Control Plane HA**      | ✅ 3+ replicas, auto-failover     | ❌ Single node      |
| **Worker Node HA**        | ✅ Multi-zone worker pools        | ❌ N/A              |
| **Auto Node Repair**      | ✅ Unhealthy nodes auto-replaced  | ❌ Must restart app |
| **Multi-Zone Deployment** | ✅ Pods spread across 3 AZs       | ❌ Single zone      |
| **Backup**                | ✅ Portworx Backup, VPC Snapshots | ❌ Manual           |
| **Disaster Recovery**     | ✅ Cross-region replication       | ❌ N/A              |
| **RTO / RPO**             | Minutes (defined SLA)            | N/A                |
| **Uptime SLA**            | 99.99% (master)                  | None               |

CI/CD Integration

| Tool                    | IKS                                    | Rancher Desktop     |
| ----------------------- | -------------------------------------- | ------------------- |
| **Tekton**              | ✅ Managed add-on (Tekton on IBM Cloud) | ⚠️ Manual install    |
| **IBM Cloud DevSecOps** | ✅ Native integration                   | ❌ N/A               |
| **GitHub Actions**      | ✅ ibmcloud CLI actions                 | ✅ kubectl deploy    |
| **GitLab CI**           | ✅ Native                               | ✅ Manual kubeconfig |
| **ArgoCD / FluxCD**     | ✅ GitOps ready                         | ✅ Works locally     |
| **Helm**                | ✅ Full support                         | ✅ Full support      |
| **Kustomize**           | ✅ Full support                         | ✅ Full support      |
| **IBM ICR Scanning**    | ✅ Auto-scan on push                    | ❌ N/A               |

Conclusion

Pros and Cons feature by feature

| Feature                           | IKS                                   | Rancher Desktop                   | Winner  |
| --------------------------------- | ------------------------------------- | --------------------------------- | ------- |
| **Kubernetes Version**            | 1.33–1.36 (IBM managed)               | K3s (latest stable)               | Tie     |
| **CNCF Certified**                | ✅ Yes                                 | ✅ Yes (K3s)                       | Tie     |
| **Control Plane Management**      | ✅ Fully managed by IBM                | ⚠️ Self-managed                    | IKS     |
| **Multi-Node Cluster**            | ✅ Yes (up to hundreds of nodes)       | ❌ No (single node only)           | IKS     |
| **Multi-Zone HA**                 | ✅ Yes (3+ availability zones)         | ❌ No                              | IKS     |
| **SLA**                           | ✅ 99.99%                              | ❌ None                            | IKS     |
| **Auto-Patch Control Plane**      | ✅ Yes                                 | ❌ Manual                          | IKS     |
| **Worker Node Auto-Update**       | ✅ Yes (configurable)                  | ❌ Manual                          | IKS     |
| **Cluster Autoscaler**            | ✅ Yes (worker pools)                  | ❌ No                              | IKS     |
| **HPA**                           | ✅ Yes                                 | ✅ Yes (resource-limited)          | IKS     |
| **VPA**                           | ✅ Yes                                 | ⚠️ Manual install                  | IKS     |
| **Private Container Registry**    | ✅ IBM Container Registry              | ⚠️ Local cache / DockerHub         | IKS     |
| **Image Vulnerability Scanning**  | ✅ Yes (ICR + VA)                      | ❌ No                              | IKS     |
| **IAM Integration**               | ✅ IBM Cloud IAM + RBAC                | ❌ No                              | IKS     |
| **Enterprise RBAC**               | ✅ Full RBAC + Trusted Profiles        | ⚠️ Basic kubeconfig                | IKS     |
| **Pod Security Admission**        | ✅ Enforced                            | ⚠️ Available, not enforced         | IKS     |
| **Network Policies**              | ✅ Calico (full)                       | ✅ Flannel (basic)                 | IKS     |
| **VPC Security Groups**           | ✅ Yes                                 | ❌ N/A                             | IKS     |
| **Network ACLs**                  | ✅ VPC subnet level                    | ❌ N/A                             | IKS     |
| **VPC Private Subnets**           | ✅ Workers on private subnets          | ❌ N/A                             | IKS     |
| **Private API Endpoint**          | ✅ VPC private endpoint                | ❌ Only localhost                  | IKS     |
| **Context-Based Restrictions**    | ✅ IBM Cloud CBR                       | ❌ N/A                             | IKS     |
| **VPC Flow Logs**                 | ✅ Full network audit trail            | ❌ None                            | IKS     |
| **Managed TLS Certificates**      | ✅ IBM Secrets Manager + Let's Encrypt | ❌ Manual / Self-signed            | IKS     |
| **Cloud Load Balancer (ALB/NLB)** | ✅ VPC ALB / NLB                       | ❌ No (NodePort only)              | IKS     |
| **Ingress Controller**            | ✅ Traefik or NGINX (managed)          | ✅ Traefik (built-in K3s)          | IKS     |
| **Managed Block Storage (CSI)**   | ✅ IBM VPC Block Storage               | ⚠️ hostPath / local-path           | IKS     |
| **Managed File Storage (CSI)**    | ✅ IBM VPC File Storage (NFS)          | ❌ No                              | IKS     |
| **Object Storage**                | ✅ IBM Cloud Object Storage (S3)       | ❌ No                              | IKS     |
| **Centralized Logging**           | ✅ IBM Cloud Logs (managed)            | ❌ kubectl logs only               | IKS     |
| **Metrics / Monitoring**          | ✅ IBM Cloud Monitoring / Sysdig       | ❌ Manual Prometheus/Grafana       | IKS     |
| **Distributed Tracing**           | ✅ IBM Cloud Tracing                   | ❌ Manual                          | IKS     |
| **Secrets Encryption**            | ✅ IBM Key Protect (KMS)               | ❌ Base64 only (plaintext in etcd) | IKS     |
| **Disk Encryption (Worker)**      | ✅ IBM-managed encrypted VSI disk      | ⚠️ Host OS dependent               | IKS     |
| **WireGuard Worker-to-Worker**    | ✅ Yes (encrypted pod traffic)         | ❌ No                              | IKS     |
| **Managed Istio**                 | ✅ Yes (add-on)                        | ❌ Manual install                  | IKS     |
| **GPU Support**                   | ✅ NVIDIA A100, L40S, H100             | ⚠️ Limited by laptop               | IKS     |
| **Compliance (SOC2, ISO, HIPAA)** | ✅ Yes                                 | ❌ No                              | IKS     |
| **Cost**                          | 💰 Pay-per-use                         | ✅ Free                            | Rancher |
| **Setup Time**                    | ⏱️ ~20 min                             | ✅ ~5 min                          | Rancher |
| **Offline / Air-gap**             | ❌ Requires IBM Cloud                  | ✅ Works offline                   | Rancher |
| **IDE Integration**               | ✅ VS Code, IntelliJ                   | ✅ VS Code, IntelliJ               | Tie     |

---

Transition Strategy

Moving from Rancher Desktop to IBM Kubernetes Service represents a shift from local rapid feedback loops to enterprise cloud governance. Developers can iterate rapidly on desktop environments using simplified manifests. However, promoting applications to staging and production requires adopting enterprise security patterns: strict pod security standards, multi-zone anti-affinity, KMS-backed persistent storage, and IBM VPC isolation.

Thanks for reading ✔️

Links and Reference

Decoupled User Management in Python

Alain Airom (Ayrom) — Tue, 28 Jul 2026 15:40:32 +0000

Hands-On tests with 'UserHarbor' and IBM Bob: A Modular Approach to Python User Authentication and Permissions

Introduction

When evaluating open-source libraries for core application infrastructure - such as authentication, session management, and fine-grained Role-Based Access Control (RBAC) - getting hands-on with a complete reference application is invaluable. This is especially true for libraries aiming to be framework-agnostic, promising flexibility but requiring more explicit wiring. Recently, I wanted to explore UserHarbor (github.com/userharbor/userharbor), a lightweight Python user-management library designed without direct coupling to any web framework or database toolkit.
Rather than manually bootstrapping a new project, setting up the SQLite database, and writing boilerplate code to explore every edge of the library, I used IBM Bob, to scaffold and implement an end-to-end reference demonstration integrated with FastAPI, SQLAlchemy for persistence, and SMTP (or a local console fallback) for transactional emails.
The goal was to rapidly test UserHarbor's entire feature lifecycle - registration, email verification, session tokens, optional authentication, RBAC guards, password resets, and account deletion, which I personally find really useful. These capacities could be implemented in many applications and ease the phase of user registration, email validation etc…
This post details the architecture built, highlights the key implementation logic, and illustrates how easily a decoupled core can be integrated into a modern web stack.

UserHabor (from official GitHub repostory)

Image from official project's repository

Project status: UserHarbor is currently in an early stage of development. The API may change frequently. The library is not ready for production use yet.

UserHarbor is a framework-agnostic Python library for user account management.
Its goal is to provide a simple, stable, and framework-independent interface for common user-related operations:

user registration
email verification
login
session management
logout from one or all sessions
password change
password reset
account deletion
role and permission checks

UserHarbor is not a web framework. It does not provide routers, views, or HTTP endpoints. Instead, it exposes a simple domain-level API that can be integrated with FastAPI, Flask, Django, Litestar, CLI applications, or any other environment.

Implementation: System Architecture & Component Design

The application architecture is based on the idea to demonstrate decoupling core business logic(s) from framework adapters, database persistence, and external service gateways, in a universal way.

Component Overview

UserHarbor Core (userharbor): Manages business logic including user registration, session management, role/permission logic, and password flows.
Official Adapters:
userharbor-fastapi: Handles routing integration and FastAPI Depends() dependency guards.
userharbor-sqlalchemy: Provides persistence via SQLAlchemyUserStore mapped to SQLite.
userharbor-smtp: Handles email dispatching with a local console fallback when SMTP credentials are not present.
FastAPI Web Shell (app/): Provides the REST API endpoints and static file serving for a lightweight Single Page Application (SPA).

Implementation Key Highlights

Modular Bootstrapping and Pre-seeding Roles (main.py)

In main.py, IBM Bob established the foundation of the modular design. The application factory bootstraps the SQLite engine, configures UserHarbor with the SQLite store and email factory, pre-seeds initial RBAC permissions, and attaches the authentication routers.

# app/main.py
"""
UserHarbor Demo – FastAPI application entry point.

Stack
─────
* userharbor         – core user-management domain logic
* userharbor-sqlalchemy – SQLite-backed UserStore
* userharbor-fastapi – FastAPI router adapter with bearer-token auth
* ConsoleEmailSender / SMTPEmailSender – from app/email.py

Environment variables (copy .env.example → .env):
  SECRET_KEY     – signing key for session tokens
  DATABASE_URL   – SQLAlchemy URL          (default: sqlite:///./users.db)
  SMTP_*         – optional SMTP credentials; falls back to console logging
"""
from __future__ import annotations

import os
from pathlib import Path

from dotenv import load_dotenv
from fastapi import FastAPI
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI
from userharbor_sqlalchemy import SQLAlchemyUserStore

from app.email import get_email_sender
from app.routes import build_demo_router

FRONTEND_DIR = Path(__file__).parent.parent / "frontend"

load_dotenv()

# ── Database ───────────────────────────────────────────────────────────────
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./users.db")
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(bind=engine)

# ── UserHarbor setup ───────────────────────────────────────────────────────
store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)  # create tables if they don't exist

harbor = UserHarbor(
    secret_key=os.getenv("SECRET_KEY", "demo-secret-key-change-in-production"),
    store=store,
    email_sender=get_email_sender(),
)

# Pre-seed roles and permissions so the demo endpoints work out of the box.
try:
    harbor.roles.create("admin")
    harbor.roles.create("editor")
    harbor.permissions.create("articles.write")
    harbor.permissions.create("users.manage")
    harbor.roles.grant_permission("admin", "articles.write")
    harbor.roles.grant_permission("admin", "users.manage")
    harbor.roles.grant_permission("editor", "articles.write")
except Exception:
    pass  # roles/permissions already exist from a previous run

# ── FastAPI adapter ────────────────────────────────────────────────────────
auth = UserHarborFastAPI(harbor)

# ── Application ────────────────────────────────────────────────────────────
app = FastAPI(
    title="UserHarbor Demo",
    description=(
        "End-to-end demonstration of UserHarbor with FastAPI + SQLAlchemy + SMTP.\n\n"
        "Workflow:\n"
        "1. `POST /auth/register` – create an account\n"
        "2. `POST /auth/verify-email` – verify your email with the token printed to console\n"
        "3. `POST /auth/login` – obtain a bearer token\n"
        "4. Use the **Authorize** button (🔒) to paste the token\n"
        "5. Try the protected `/demo/*` endpoints\n"
    ),
    version="1.0.0",
)

# Built-in auth routes: /auth/register, /auth/login, /auth/me, etc.
app.include_router(auth.router, prefix="/auth", tags=["Authentication"])

# Demo application routes that showcase role/permission guards.
app.include_router(
    build_demo_router(auth, harbor),
    prefix="/demo",
    tags=["Demo – Protected Routes"],
)

# Serve the SPA frontend
app.mount("/static", StaticFiles(directory=str(FRONTEND_DIR)), name="static")

@app.get("/", tags=["Root"], include_in_schema=False)
def serve_ui():
    """Serve the SPA shell."""
    return FileResponse(str(FRONTEND_DIR / "index.html"))

if __name__ == "__main__":
    import uvicorn

    uvicorn.run("app.main:app", host="0.0.0.0", port=8080, reload=True)

Dev-Friendly Console Email Fallback (email.py)

To remove dependencies during exploration, an email factory tis configured, that switches to logging transactional email tokens directly to stdout during development, rather than requiring real SMTP credentials.

"""
Email sender implementations for the demo.

* ConsoleEmailSender – prints tokens to stdout; ideal for development when no
  SMTP server is available.
* get_email_sender()  – factory that returns an SMTPEmailSender when SMTP
  credentials are present, otherwise falls back to the console sender.
"""
from __future__ import annotations

import os

class ConsoleEmailSender:
    """Prints email content to the console instead of sending real mail."""

    def send_verification(
        self,
        username: str,
        email: str,
        verification_token: str,
    ) -> None:
        print(
            f"\n[EMAIL] Verification token for {username} ({email}):\n"
            f"  Token: {verification_token}\n"
        )

    def send_password_reset(
        self,
        username: str,
        email: str,
        reset_token: str,
    ) -> None:
        print(
            f"\n[EMAIL] Password-reset token for {username} ({email}):\n"
            f"  Token: {reset_token}\n"
        )

    def send_email_verified(self, username: str, email: str) -> None:
        print(f"\n[EMAIL] Email verified – {username} ({email})\n")

    def send_password_changed(self, username: str, email: str) -> None:
        print(f"\n[EMAIL] Password changed – {username} ({email})\n")

    def send_account_deleted(self, username: str, email: str) -> None:
        print(f"\n[EMAIL] Account deleted – {username} ({email})\n")

def get_email_sender():
    """Return an SMTPEmailSender when credentials are available, else console."""
    host = os.getenv("SMTP_HOST", "")
    username = os.getenv("SMTP_USERNAME", "")
    password = os.getenv("SMTP_PASSWORD", "")
    from_email = os.getenv("SMTP_FROM_EMAIL", "")

    if host and username and password and from_email:
        from userharbor_smtp import SMTPEmailSender  # type: ignore

        return SMTPEmailSender(
            host=host,
            port=int(os.getenv("SMTP_PORT", "587")),
            username=username,
            password=password,
            from_email=from_email,
            from_name=os.getenv("SMTP_FROM_NAME", "UserHarbor Demo"),
        )

    print("[INFO] No SMTP credentials found – using ConsoleEmailSender.")
    return ConsoleEmailSender()

Fine-Grained Authorization Guards (routes.py)

The application router exercises the complete RBAC and permission guards provided by userharbor-fastapi. The pre-built dependencies (Depends()) can enforce authentication, specific role requirements, or granular permissions.

"""
Demo application routes that showcase every UserHarbor feature:

Route                     Auth required    Extra guard
─────────────────────────────────────────────────────
GET  /demo/public          none            –
GET  /demo/profile         session token   –
GET  /demo/optional        optional        –
POST /demo/assign-admin    session token   – (grant admin role to a user)
GET  /demo/articles/write  session token   permission: articles.write
GET  /demo/admin/users     session token   role: admin
"""
from __future__ import annotations

from fastapi import APIRouter, Depends
from pydantic import BaseModel
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI

# ── Request / response models ──────────────────────────────────────────────

class AssignRoleRequest(BaseModel):
    username: str
    role: str

# ── Router factory ─────────────────────────────────────────────────────────

def build_demo_router(auth: UserHarborFastAPI, harbor: UserHarbor) -> APIRouter:
    router = APIRouter()

    # ── Public route – no authentication ──────────────────────────────────
    @router.get("/public")
    def public():
        """Anyone can call this endpoint – no token required."""
        return {
            "message": "This is a public endpoint. No authentication needed.",
            "hint": "Call POST /auth/register to create an account, then POST /auth/login.",
        }

    # ── Optional auth – behaves differently for guests vs. logged-in users ─
    @router.get("/optional")
    def optional(user=Depends(auth.optional_user)):
        """Shows personalised content when a valid token is present."""
        if user is None:
            return {"authenticated": False, "message": "Hello, anonymous visitor!"}
        return {
            "authenticated": True,
            "message": f"Hello, {user.username}! You are verified: {user.verified}",
        }

    # ── Protected – requires a valid session token ─────────────────────────
    @router.get("/profile")
    def profile(user=Depends(auth.current_user)):
        """Requires a valid session token (Authorization: Bearer <token>)."""
        return {
            "username": user.username,
            "email": user.email,
            "verified": user.verified,
        }

    # ── Assign a role to any user (admin can do this) ──────────────────────
    @router.post("/assign-role")
    def assign_role(
        body: AssignRoleRequest,
        user=Depends(auth.current_user),
    ):
        """
        Grant a role to a user. Requires a valid session.

        Useful for promoting someone to 'admin' or 'editor' so you can
        test the role-restricted endpoints below.
        """
        harbor.grant_role(body.username, body.role)
        return {
            "message": f"Role '{body.role}' granted to '{body.username}'.",
            "granted_by": user.username,
        }

    # ── Permission-restricted route ────────────────────────────────────────
    @router.get("/articles/write")
    def write_articles(user=Depends(auth.require_permission("articles.write"))):
        """
        Requires the **articles.write** permission.

        Roles that have this permission: `admin`, `editor`.
        Grant one with POST /demo/assign-role.
        """
        return {
            "message": f"Welcome, {user.username}! You can write articles.",
            "permission": "articles.write",
        }

    # ── Role-restricted route ──────────────────────────────────────────────
    @router.get("/admin/users")
    def admin_users(user=Depends(auth.require_role("admin"))):
        """
        Requires the **admin** role.

        Grant with: POST /demo/assign-role  { "username": "...", "role": "admin" }
        """
        return {
            "message": f"Welcome, admin {user.username}!",
            "note": "In a real app you would return a paginated user list here.",
        }

    return router

Overall Features demonstrated

I find this library really promissing, and so far in this demo, the following features are provided;

| Feature                 | UserHarbor API                                               |
| ----------------------- | ------------------------------------------------------------ |
| User registration       | `harbor.register()`                                          |
| Email verification      | `harbor.verify_email()`                                      |
| Login / bearer token    | `harbor.login()`                                             |
| Session validation      | `harbor.verify_session()`                                    |
| Current user            | `harbor.get_current_user()`                                  |
| Optional authentication | `auth.optional_user` dependency                              |
| Role management         | `harbor.roles.create()` / `harbor.grant_role()`              |
| Permission management   | `harbor.permissions.create()` / `harbor.roles.grant_permission()` |
| Role guard              | `auth.require_role("admin")` dependency                      |
| Permission guard        | `auth.require_permission("articles.write")` dependency       |
| Password change         | `harbor.change_password()`                                   |
| Password reset flow     | `harbor.send_password_reset()` / `harbor.reset_password()`   |
| Logout                  | `harbor.logout()`                                            |
| Logout all sessions     | `harbor.logout_all()`                                        |
| Account deletion        | `harbor.delete_account()`                                    |

---

Conclusion and Key Learnings

Testing UserHarbor proved to be a powerful exercise in building a modular application foundation. By keeping the authentication domain decoupled from the delivery framework and persistence logic, it achieves a clean separation of concerns without introducing significant architectural overhead.

Partnering with IBM Bob allowed for rapid exploration and integration, making it straightforward to validate that framework-agnostic approaches to core infrastructure are highly viable for modern web applications.

Thanks for reading 👨‍🏭

Planning Modernizing Legacy Micro Focus COBOL to .Net? Listen to Bob Advices First

Alain Airom (Ayrom) — Tue, 28 Jul 2026 08:57:42 +0000

Modernization of legacy code needs a strong plan!

Introduction

In a recent discussion with a partner, we talked about a customer (running some application on Azure) case that wants to migrate legacy Micro Focus COBOL to .NET. Impressively, Bob came up with this plan:

Structural Analysis
Call Hierarchy
Data structures
Micro Focus specific extensions

The Big Picture

Migrating 60,000 lines of Micro Focus COBOL to .NET 8 / C# 12 is a strategically sound choice — particularly for organizations already operating in a Windows/Azure ecosystem or leveraging Microsoft’s enterprise toolchain.

The migration combines:

Static analysis tooling (Micro Focus Enterprise Analyzer, CAST Highlight, NDepend post-migration) for full-codebase intelligence
AI-assisted translation (Bob, per module) for business rule extraction, C# code generation, and xUnit test scaffolding
Incremental Strangler Fig pattern — replacing COBOL modules one at a time via an API gateway, with the legacy system as fallback
Automated parallel testing — running identical inputs through both COBOL and new C# code, comparing outputs record-by-record
Azure-native deployment using .NET 8 on Azure App Service, Azure Container Apps, or on-premises IIS/Windows Server

⚠️ A “big bang” full rewrite is the highest-risk path and is explicitly not recommended.

Why .NET over Java for Micro Focus COBOL?

Micro Focus COBOL has historically had deep integration with the Windows ecosystem and Microsoft tooling. Organizations already using Visual Studio, Azure DevOps, SQL Server, and Active Directory gain a natural convergence advantage by targeting .NET rather than the JVM stack.

Key Considerations

The 60k-Line Challenge: Why “Big Bang” rewrites fail and why Micro Focus COBOL extensions (SCREEN SECTION, COMP-3, proprietary APIs) require precise upfront intelligence.
Phase 1 Static Discovery: Using tools like Micro Focus Enterprise Analyzer alongside IBM Bob to build dependency maps, flag dead code, and trace PERFORM chains.
Domain Decomposition: Breaking the monolith into C# Bounded Contexts (e.g., Billing, Inventory, Customer, Reporting).
The Strangler Fig Architecture: How Yarp (Yet Another Reverse Proxy) or Azure API Management acts as the routing layer between legacy COBOL and new .NET services.

Recommended Strategy Overview

Key Architectural Diagram (.NET Strangler Pattern)

High-Level Migration Lifecycle (proposal timeline)

Phase 1 — Inventory & Deep Analysis

COBOL Program Anatomy — What to Inventory

Key Analysis Tasks

| Task                      | Tool                       | Output                                          |
| ------------------------- | -------------------------- | ----------------------------------------------- |
| Program inventory         | Enterprise Analyzer        | List of all active `.cbl` programs              |
| Copybook mapping          | Enterprise Analyzer / Bob  | Dependency tree — maps to C# shared models      |
| PERFORM/CALL graph        | Enterprise Analyzer / Bob  | Method call hierarchy for C# refactoring        |
| Dead code detection       | Enterprise Analyzer        | Programs/paragraphs to retire (expect 10–20%)   |
| Data structure extraction | Bob                        | C# record/class candidates from WORKING-STORAGE |
| Business rule extraction  | Bob                        | Plain-English + C# XML doc comment stubs        |
| VSAM file inventory       | Enterprise Analyzer        | Entity Framework Core schema candidates         |
| Complexity scoring        | CAST Highlight / SonarQube | Priority list for migration order               |

Phase 2: Phase 2 — Modularization & Boundary Definition

Decomposing the Monolith into .NET Projects

Copybook → C# Model Mapping

### C# / .NET Specific Type Conversion Matrix

| Micro Focus COBOL Construct | .NET 8 / C# Target                      | Risk / Mitigation                                            |
| --------------------------- | --------------------------------------- | ------------------------------------------------------------ |
| `PIC 9(n)V9(m) COMP-3`      | `decimal`                               | 🔴 **High** — Never use `float` or `double` for financial data. |
| `PIC X(n)`                  | `string` (fixed-length aware)           | 🟡 **Medium** — Use String padding helper functions where necessary. |
| `COMP-1` / `COMP-2`         | `float` / `double`                      | 🟡 **Medium** — Validate precision tolerance across mathematical operations. |
| `SCREEN SECTION`            | **ASP.NET Core Controllers / Blazor**   | 🟢 **Low** — Decouple UI logic completely into REST endpoints. |
| `VSAM / Sequential Files`   | **SQL Server / PostgreSQL via EF Core** | 🟡 **Medium** — Map key-indexed records to relational schema or Document DB. |

Phase 3 — Target .NET Architecture Design

Recommended .NET Solution Structure

COBOL Batch → .NET Worker Service Pattern

VSAM → SQL Server / Azure SQL Migration

Phase 4 — AI-Assisted Translation to C

Bob’s Role in the C# Translation Pipeline

COBOL → C# Pattern Translation Reference

Per-Module Translation Workflow

Context Window Strategy

Phase 5 — Testing & Validation

Azure Deployment Architecture

Canary Deployment Strategy

Decommissioning Checklist

End-to-End Workflow with Bob

Micro Focus COBOL → C# Specifics

Extension Handling Map

### COBOL Data Type → C# Type Mapping

| COBOL Type             | Micro Focus Behavior      | C# Target                                          | Risk           |
| ---------------------- | ------------------------- | -------------------------------------------------- | -------------- |
| `PIC 9(n)`             | Unsigned integer          | `int` / `long`                                     | 🟢 Low          |
| `PIC S9(n)`            | Signed integer            | `int` / `long`                                     | 🟢 Low          |
| `PIC 9(n)V9(m) COMP-3` | Packed decimal            | `decimal` (native base-10)                         | 🔴 **Critical** |
| `PIC X(n)`             | Fixed-length alphanumeric | `string` (padded-aware)                            | 🟡 Medium       |
| `PIC A(n)`             | Alphabetic                | `string`                                           | 🟢 Low          |
| `COMP` / `COMP-4`      | Binary integer            | `int` / `long`                                     | 🟢 Low          |
| `COMP-1`               | Single float              | `float` (**never for financials**)                 | 🔴 **Critical** |
| `COMP-2`               | Double float              | `double` (**never for financials**)                | 🔴 **Critical** |
| `COMP-5`               | Native binary             | `int` / `long`                                     | 🟢 Low          |
| `88-level condition`   | Boolean flag              | `bool` property or `enum`                          | 🟢 Low          |
| `REDEFINES`            | Memory overlay            | C# `[StructLayout]` union or `discriminated union` | 🟡 Medium       |
| Group item (01 level)  | Struct/record             | `record` or `struct` in C#                         | 🟢 Low          |

###

COBOL 88-Level Conditions → C# Enum

Toolchain Summary

Risk Register

| Risk                                                     | Probability | Impact     | .NET-Specific Mitigation                                     |
| -------------------------------------------------------- | ----------- | ---------- | ------------------------------------------------------------ |
| Loss of undocumented business rules                      | 🔴 High      | 🔴 Critical | Bob extracts rules as C# XML doc comments before any translation; SME sign-off required |
| COMP-3 precision → `double` instead of `decimal`         | 🟡 Medium    | 🔴 Critical | SonarQube rule: ban `double`/`float` for financial fields; enforce `decimal` in code review |
| Micro Focus SCREEN SECTION has no direct .NET equivalent | 🟡 Medium    | 🟡 High     | Plan dedicated UI redesign sprint; Blazor or React/Carbon as replacement |
| OO-COBOL CLASS/METHOD structures complex to map          | 🟡 Medium    | 🟡 Medium   | Bob maps to C# interface + class pattern; manual review for inheritance hierarchies |
| VSAM data integrity loss during migration                | 🟢 Low       | 🔴 Critical | Full data export validation; EF Core migration scripts + record-level reconciliation |
| AI hallucination in complex procedural logic             | 🟡 Medium    | 🟡 High     | Always generate xUnit tests *before* C# translation; parallel COBOL validation required |
| Azure latency vs on-premises COBOL batch throughput      | 🟡 Medium    | 🟡 Medium   | Baseline COBOL SLAs; BenchmarkDotNet + Azure Load Testing before cutover |
| Key COBOL SME leaves during project                      | 🟡 Medium    | 🔴 Critical | Document all tribal knowledge in Phase 1; Bob assists reverse-engineering from code |
| Scope creep — feature requests during migration          | 🔴 High      | 🟡 Medium   | Freeze scope; new features only after full migration; use separate feature branch |
| NuGet supply-chain vulnerability                         | 🟢 Low       | 🟡 Medium   | Azure DevOps Dependabot + SonarQube SAST on all dependencies |

Effort & Budget Allocation

Recommended Effort Distribution

⚠️ Testing and validation require 30–35% of total effort. Under-allocating here is the leading cause of COBOL migration project failure. For financial systems, allocate toward the higher end.

### Recommended Team Composition

| Role                         | FTE  | Responsibility                                            |
| ---------------------------- | ---- | --------------------------------------------------------- |
| COBOL SME / Business Analyst | 1–2  | Business rule validation, domain expertise, UAT sign-off  |
| C# / .NET Developer (Senior) | 2–3  | Translation review, architecture, EF Core, deployment     |
| C# / .NET Developer (Mid)    | 2    | Test writing, module translation, CI/CD pipeline          |
| QA / Test Engineer           | 2    | xUnit suites, parallel validation harness, UAT            |
| DevOps / Azure Engineer      | 1    | Azure infrastructure, CI/CD, Application Insights         |
| Data Engineer                | 1    | VSAM → SQL migration, EF Core schema design               |
| Project Manager              | 1    | Coordination, risk management, stakeholder communication  |
| **Bob (AI)**                 | —    | Analysis, documentation, C# translation, xUnit generation |

---

##

## Recommendations

### ✅ Do

1. **Provide one module at a time** — 500–2,000 lines per Bob session, with relevant copybooks included
2. **Ask for documentation first**, then xUnit tests, then C# translation — this ordering produces the most reliable results
3. **Use TDD**: ask Bob to generate `[Fact]` / `[Theory]` xUnit tests *before* writing the implementation
4. **Specify the exact target stack**: `"C# 12 / .NET 8 / ASP.NET Core / Entity Framework Core 8 / SQL Server"`
5. **Ask Bob to flag Micro Focus extensions** explicitly — it will identify what needs manual attention
6. **Ask for C# `record` types for COBOL copybooks** — these are the cleanest, most idiomatic mapping
7. **Always validate with a parallel COBOL run** — never trust AI-generated C# without output equivalence testing
8. **Ask Bob to produce XML doc comments** (`/// <summary>`) — these become living documentation

### ❌ Don't

1. **Don't paste the full 60K codebase** in one session — context overload causes hallucination
2. **Don't use `double` or `float` for any financial field** — always `decimal` with explicit rounding
3. **Don't skip the parallel validation phase** — even if all xUnit tests pass
4. **Don't decommission COBOL until 30+ days of parallel validation** with zero discrepancies
5. **Don't allow AI-translated code to go to production without a senior C# review**
6. **Don't hard-code connection strings, API keys, or credentials** — use Azure Key Vault via `IConfiguration`

Platform Comparison Matrix: .NET 8 Target Ecosystem

| Architectural Layer                 | Microsoft Azure Target                                     | IBM Cloud Target                                             | Trade-offs & Recommendations                                 |
| ----------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **Serverless / Container Compute**  | **Azure Container Apps (ACA)** *(Powered by KEDA & Envoy)* | **IBM Cloud Code Engine** *(Serverless container runtime)*   | **ACA** offers native .NET integration, microservice scaling, and simple Dapr support. **Code Engine** provides zero-management serverless execution with standard Docker images. |
| **Enterprise Kubernetes Platform**  | **Azure Kubernetes Service (AKS)**                         | **Red Hat OpenShift on IBM Cloud **                    | **AKS** is ideal for pure cloud-native .NET workloads. **ROKS** is better for hybrid cloud scenarios where legacy mainframe and cloud workloads co-exist. |
| **API Gateway & Strangler Routing** | **Azure API Management (APIM)**                            | **IBM API Connect**                                          | Both easily implement the Strangler Fig pattern with path-based routing (`/api/v1/billing` → .NET, `/api/v1/legacy/*` → Legacy/Mainframe). |
| **Database & Persistence**          | **Azure SQL Database / Azure Cosmos DB**                   | **IBM Db2 on Cloud / PostgreSQL**                            | **Azure SQL** provides easy migration for enterprise relational schema. **Db2 on Cloud** preserves schema compatibility if migrating from IBM z/OS Db2. |
| **CI/CD & Developer Tooling**       | **GitHub Actions / Azure DevOps**                          | **IBM Bob / Tekton Pipelines / Red Hat OpenShift Pipelines** | **Azure DevOps** has native .NET SDK building blocks. **IBM Bob** integrates with Tekton and IBM SDLC pipelines. |

Option A: Microsoft Azure Target Architecture

Azure provides a native developer experience for .NET 8 applications. In this setup, Azure API Management handles the Strangler Fig routing between legacy COBOL endpoints and modernized .NET microservices running on Azure Container Apps.
https://miro.medium.com/v2/resize:fit:1400/format:webp/1*GW_z30CGZIcmbkj2FnvCeQ.png

Advantage of the Azure Path

Native .NET Support: Zero-friction CI/CD setup with GitHub Actions, native Visual Studio tooling, and telemetry through Azure Application Insights.

Option B: IBM Cloud Target Architecture

IBM Cloud is structured for enterprises operating in hybrid or multi-cloud environments. IBM API Connect directs traffic, while IBM Cloud Code Engine (running on ROKS) runs containerized .NET 8 microservices, maintaining tight integration with mainframe systems via IBM z/OS Connect or dedicated direct links.

Key Advantages of the IBM Cloud Path

Db2 Schema Continuity: If legacy COBOL relied on Db2 data structures, IBM Db2 on Cloud preserves column definitions and SQL statements with minimal refactoring required.
OpenShift Flexibility: Running on Red Hat OpenShift on IBM Cloud prevents cloud lock-in, allowing the containerized .NET services to run on-premises or across other cloud providers.

Which Path to Choose?

Choose Azure if your primary goal is maximizing developer productivity within a pure Microsoft ecosystem and simplifying .NET operational management.
Choose IBM Cloud if you require close hybrid integration with existing IBM infrastructure (z/OS, IBM MQ, Db2), or if your organization standardizes on Red Hat OpenShift for multi-cloud deployments.

Appendix — Sample Bob Prompts for COBOL → C# Migration

// ─── Prompt 1: Structural Analysis ─────────────────────────────────────────
"Analyze this Micro Focus COBOL program. Map all paragraphs to candidate C#
methods, extract all WORKING-STORAGE variables as C# field/property candidates,
identify all COPY statements and map copybooks to C# record types, and flag
any Micro Focus-specific extensions. Generate a Mermaid flowchart of the
PERFORM call chain."

// ─── Prompt 2: Copybook → C# Record ────────────────────────────────────────
"Convert this COBOL copybook to a C# record type for .NET 8. Use:
- 'decimal' for all PIC 9...COMP-3 fields
- 'string' for PIC X fields (note original fixed length in XML doc comment)
- 'int' or 'long' for PIC 9 COMP fields
- 'bool' properties for 88-level condition names
- C# XML doc comments (///) documenting each field's COBOL origin"

// ─── Prompt 3: Business Rule Extraction ─────────────────────────────────────
"Extract all business rules from the PROCEDURE DIVISION of this COBOL module.
For each rule, document: rule name, trigger/condition, action taken, edge
cases, and error handling. Format as C# XML doc comments ready to be placed
on the equivalent C# service class methods."

// ─── Prompt 4: xUnit Test Generation (TDD — before translation) ─────────────
"Based on the documented business rules, generate an xUnit 2 test class for
the C# equivalent of this COBOL module. Use [Fact] for single-scenario tests,
[Theory] with [InlineData] for parameterized cases. Structure each test with
Arrange / Act / Assert comments. Include boundary conditions and error paths.
Do NOT write the implementation — only the tests."

// ─── Prompt 5: C# Translation ───────────────────────────────────────────────
"Translate this COBOL module to C# targeting .NET 8 / ASP.NET Core 8.
Rules:
- Use 'decimal' (never double/float) for all numeric COMP-3 fields
- Map EVALUATE to C# switch expressions or switch statements
- Map PERFORM VARYING to for/foreach loops
- Map PERFORM paragraph-name to private methods
- Map CALL 'SUBPROG' to injected service interface calls
- Use async/await for all I/O operations
- Follow C# 12 idioms: records, pattern matching, primary constructors
- Add XML doc comments on all public members
- Avoid JOBOL — write idiomatic modern C#, not COBOL-shaped C#"

// ─── Prompt 6: EF Core Entity Design ────────────────────────────────────────
"Based on this COBOL FILE SECTION and the VSAM KSDS structure described,
generate an Entity Framework Core 8 entity class and DbContext configuration
targeting SQL Server. Include:
- Primary key mapping (from VSAM record key)
- Decimal column precision annotations for financial fields
- Fixed-length string column annotations for PIC X fields
- A migration-ready DbContext with HasColumnType annotations"

// ─── Prompt 7: Micro Focus Extension Audit ──────────────────────────────────
"Review this COBOL code and identify all Micro Focus-specific features:
SCREEN SECTION definitions, OO-COBOL constructs (CLASS/METHOD/INVOKE),
CBL_* API calls, proprietary COPY libraries, and CICS commands. For each,
provide the recommended C# / .NET 8 / Azure equivalent or flag for
mandatory manual review with an explanation of the complexity involved."

Conclusion-COBOL to .NET Migration Strategy

The successful migration of 60,000 lines of legacy Micro Focus COBOL to a modern .NET 8 / C# 12 architecture is a viable and strategic imperative for organizations looking to modernize their core systems. By targeting the Microsoft ecosystem, organizations already leveraging Visual Studio, Azure, and SQL Server can realize a natural technological convergence and gain access to a powerful, modern platform for future growth.

Avoid “Big Bang” Rewrites: The document explicitly warns against a full, single-step rewrite due to its high risk. The recommended approach is an incremental strategy using the Strangler Fig pattern, where COBOL modules are progressively replaced by .NET services through an API gateway. This approach allows the legacy system to remain active as a fallback, significantly de-risking the process.
Discipline in Testing is Paramount: The document places an overwhelming emphasis on testing, suggesting it should consume 30–35% of the total effort. This is not an area for cost-cutting. A multi-layered testing strategy is essential:
Unit Tests: Generated by Bob using xUnit, covering every service method.
Integration Tests: Using TestContainers for service-to-service validation.
Automated Parallel Validation: This is a critical step where both the legacy COBOL and new C# systems run identical inputs, and their outputs are compared field-by-field. The migration should not be considered successful until zero discrepancies are found over a set period (e.g., 30 days).
Absolute Numeric Precision: In financial and core business systems, numeric precision is non-negotiable. The document stresses that COMP-3 packed decimal fields must be mapped to C# decimal types. The use of floating-point types (double or float) for financial fields is explicitly forbidden due to potential for rounding errors and precision loss.
AI-Assisted, Not AI-Automated: While Bob (IBM AI SDLC Partner) is central to this proposition, its role is clearly defined as an accelerator and guide, not a fully autonomous migration engine. Developers must review, validate, and sign off on all AI-generated code, documentation, and tests. Bob’s power is maximized when used incrementally (e.g., translating one 500–2,000 line module at a time with relevant copybooks) and with a structured TDD workflow: ask for documentation first, then tests, then implementation.
Targeted Platform Benefits: The migration to .NET 8 / C# 12 offers immediate access to modern architectural patterns like ASP.NET Core Web APIs for services, Worker Services for batch job replacements, and a robust ORM with Entity Framework Core 8. The deployment strategy leverages IBM and/or Azure services for cloud-native scalability and managed infrastructure.

In summary, this migration proposition outlines a disciplined, tooled, and incremental path to modernization. By adhering to these key emphasis areas, organizations can transform their legacy COBOL assets into a maintainable, resilient, and performant .NET foundation.

Thanks for reading

Book Review: Build Applications with Local AI Models on a Mac

Alain Airom (Ayrom) — Thu, 23 Jul 2026 09:20:43 +0000

Feedback and synthesis on of my latest readings: “Build Applications with Local AI Models on a Mac”

Introduction

As cloud-based AI infrastructure and API subscription costs continue to rise, running Large Language Models (LLMs) locally on consumer-grade hardware has transitioned from a niche hobby to a compelling architectural shift. The primary drivers behind this movement are privacy and economy. From a privacy perspective, processing data locally guarantees that confidential text, proprietary source code, internal business records, and personally identifiable information (PII) never leave your physical device. There are no remote logging pipelines, third-party data retention policies, or potential cloud leaks to worry about. On the economic front, local execution removes pay-per-token API metering entirely. Once you own the hardware, running inference across millions of tokens carries zero incremental API cost, making local models extremely cost-effective for high-volume tasks, continuous agent loops, embedding generation, and rapid local prototyping.

To be clear, one cannot do all with local LLMs in my opinion, but it helps for some tasks…

I, myself use Ollama on a regular basis with different models for agents, embeddings, etc. I was curious to read this book and figure out whether I would learn something new or not.

Disclaimer: I have no ties, commercial relationships, or affiliations with Manning Publications (manning.com) or the author of this book, Keiji Kamigusa. This review and breakdown are purely independent.

All images are from the book’s author.

Part 1: First Steps — Entering the World of the Terminal

Chapters 1 to 6 are really basic, destinated for beginners! You can ignore big parts of them.

Chapter 1: Getting Started with Local AI

This introductory chapter establishes the conceptual framework for local AI development on Apple Silicon and Intel Macs. It introduces how local inference works on modern hardware — highlighting the unified memory architecture (UMA) of Apple’s M-series chips — and compares local runtime environments against traditional cloud APIs in terms of latency, privacy, and cost predictability.

Chapter 2: Installing and Using Homebrew

Focusing on developer tooling, this chapter guides us through setting up Homebrew, the standard package manager for macOS. It covers terminal basics, environment path setup, and how command-line utilities form the foundational stack for managing dependencies in local machine learning projects.

Chapter 3: Installing and Setting Up Ollama

Here, the book dives into Ollama, the central engine used throughout the book to serve local models. It covers installation, service startup, verifying running instances via terminal commands, and managing local model storage.

# Pulling and running a lightweight model locally via Ollama terminal CLI
# for example...
ollama run granite3.2

Part 2: Core Skills — Building Your First AI Chatbot

Chapter 4: Downloading an LLM and Your First Conversation

This chapter demonstrates basic CLI interactions with quantized open-weights models (such as Granite, Llama, Gemma, and Qwen). We learn how to pull models from the registry, run interactive shell sessions, and monitor memory usage during inference.

Chapter 5: Setting Up VS Code and Your Python Development Environment

Moving from CLI usage to application development, this chapter covers configuring Visual Studio Code, installing Python, and structuring a clean directory workspace for building custom AI tools.

Chapter 6: Creating and Managing Python Virtual Environments

To avoid package dependency conflicts, this chapter explains Python virtual environments (venv). It covers environment creation, activation, and managing dependency lists with requirements.txt.

# Creating and activating a clean Python virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install ollama streamlit

Chapter 7: Controlling LLMs via the Ollama Python API

This chapter introduces programatically driving local models using the official ollama Python client. It demonstrates synchronous text generation, chat completions, and real-time response streaming.

import ollama

# Querying a local model programmatically with streaming enabled
response = ollama.chat(
    model="gemma2:2b",
    messages=[{"role": "user", "content": "Explain vector embeddings in one sentence."}],
    stream=True,
)

for chunk in response:
    print(chunk["message"]["content"], end="", flush=True)

Chapter 8: Building a Web UI with Streamlit

Demonstrating how to wrap Python backend code into an interactive graphical web interface using Streamlit. The chapter demonstrates rapid prototyping of UI elements like text inputs, buttons, and message display blocks.

Chapter 9: Recording Audio and Transcribing Speech with MLX Whisper

Expanding beyond text input, this chapter integrates Apple Silicon-optimized speech recognition using MLX Whisper. It details audio input capture and converting spoken voice into clean text transcripts locally. (I liked this chapter 🙂 and the following one)

Chapter 10: Building a Voice-Enabled AI Chat Application

Combining speech recognition with LLM generation, this chapter walks through building a hands-free, voice-driven AI conversational agent that listens, transcribes, processes queries, and outputs responses.

Chapter 11: Managing Session State and Chat History

Personally I really appreciated this part of the book!

To handle multi-turn conversations, this chapter addresses managing state inside Streamlit applications using st.session_state. It demonstrates how to maintain chat history, trim context windows, and calculate token counters.

import streamlit as st

# Managing chat state across Streamlit reruns
if "messages" not in st.session_state:
    st.session_state.messages = []

# Displaying chat history
for message in st.session_state.messages:
    with st.chat_message(message["role"]):
        st.markdown(message["content"])

Part 3: Advanced Topics — Deeper Understanding and Customization

Chapters 12 and 13 (part 3 of the book) interested me personally the most.

Chapter 12: Comparing and Selecting LLM Models

This chapter provides a comparative framework for evaluating open-weight models (e.g., Granite4, Gemma 3, Qwen 2.5, Phi-3). It contrasts parameter counts, context window sizes, quantization impact, and inference speed benchmarks across different hardware setups.

import time
import ollama

# Benchmarking inference speed across multiple local models
models = ["gemma3:4b", "qwen2.5:3b", "phi3:mini"]
prompt = "What are three key benefits of local AI inference?"

for model_name in models:
    start_time = time.time()
    response = ollama.chat(
        model=model_name,
        messages=[{"role": "user", "content": prompt}],
    )
    elapsed = time.time() - start_time
    print(f"Model: {model_name} | Response Time: {elapsed:.2f}s")

Chapter 13: System Prompts and Parameter Tuning

Focusing on output control, this chapter details how to shape model behavior using system prompts (assigning personas or strict rules) and adjusting hyperparameters like temperature to control randomness.

import ollama

# System prompt persona assignment and parameter tuning
response = ollama.chat(
    model="gemma2:2b",
    messages=[
        {"role": "system", "content": "You are a concise expert. Answer strictly in bullet points."},
        {"role": "user", "content": "Summarize the benefits of virtual environments."},
    ],
    options={"temperature": 0.2},
)
print(response["message"]["content"])

Chapter 14: Offline LLMs and Their Benefits

This chapter focuses on air-gapped operations, demonstrating how locally hosted models function entirely without active internet connectivity — ensuring high security and complete system resilience against remote network failures.

Chapter 15: Common Errors and Troubleshooting

A practical reference chapter covering common execution issues, including missing package dependencies, port binding errors, out-of-memory (OOM) GPU allocation failures, and Ollama daemon connectivity fixes.

Chapter 16: Advancing to RAG, Web UI, and Fine-Tuning

This chapter introduces advanced application design patterns, primarily focusing on Retrieval-Augmented Generation (RAG) using vector stores like ChromaDB, agent tool integrations with LangChain, and high-level interfaces like Open WebUI.

Personally, I prefer other vector databases such as AstraDB or Milvus, but the book focuses on ChromaDB.

import chromadb
import ollama

# RAG setup: Injecting context into local LLM query
client = chromadb.Client()
collection = client.create_collection("my_knowledge")

collection.add(
    documents=["Ollama runs LLMs locally on macOS, Linux, and Windows."],
    ids=["doc1"],
)

results = collection.query(query_texts=["Where can Ollama run?"], n_results=1)
context = "\n".join(results["documents"][0])

prompt = f"Context:\n{context}\n\nQuestion: Where can Ollama run?\nAnswer:"
response = ollama.chat(
    model="gemma3:4b",
    messages=[{"role": "user", "content": prompt}],
)
print(response["message"]["content"])

Chapter 17: The Open Model Revolution of 2026

Taking a broader architectural view, this chapter explores the landscape of open-weight artificial intelligence models, discussing open ecosystem standards, model safety guardrails, and hardware developments shaping modern on-device execution.

Chapter 18: Where to Go from Here

The concluding chapter provides a roadmap for further developer exploration, suggesting paths toward custom agent orchestration frameworks, fine-tuning techniques, and deployment options beyond local development environments.

Conclusion & Personal Opinion

Build Applications with Local AI Models on a Mac provides a practical, step-by-step introduction to running LLMs on consumer hardware and integrating them into functional Python applications. By guiding the readers through terminal setup, Ollama configuration, Streamlit web UI creation, speech transcription via MLX Whisper, and foundational RAG patterns using ChromaDB and LangChain, the book serves as a clear starting guide for on-device AI integration.

Personal Opinion

Overall, this was mostly an enjoyable read . It is particularly well-suited for novices, beginners, or developers who are new to running models locally using Ollama and want a structured, practical path from terminal installation to building functional UI wrappers and voice agents. While experienced developers already familiar with agentic loops, custom embedding pipelines, and low-level quantization mechanics might find much of the initial material elementary, it remains a clean, cohesive refresher. The accompanying code repository provided with the book is well-organized, making it easy to follow along, test code snippets, and quickly adapt the examples for personal experiments.

Thanks for reading 📔

Building an AI-Native Document Platform with Doclang

Alain Airom (Ayrom) — Wed, 22 Jul 2026 08:38:15 +0000

A technical deep dive into architecting an end-to-end playground for DocLang — the AI-native markup language built for LLMs.

🚀 Introduction & Overview

As Large Language Model (LLM) applications mature, a fundamental friction point remains: legacy document formats were never designed for tokenizers.

PDF was built for precise visual print layout.
DOCX was built for human desktop editors.
HTML is bloated with display tags, costing up to 5× more tokens for structured elements like tables.

DocLang is an open document standard governed by *Linux Foundation AI & Data *(backed by IBM, NVIDIA, Red Hat, ABBYY, and HumanSignal). DocLang maps structured documents cleanly to LLM tokens while preserving precise geometry, semantic hierarchies, code blocks, and formulas in an unambiguous XML markup representation.

What is Doclang?

Excerpt from Doclang’s site.

DocLang is the AI-native markup format for unstructured content — documents, images, audio, and video alike. It is engineered from the ground up around a single principle: mapping cleanly to LLM tokens. That makes DocLang the most efficient way to read, write, and reason about real-world content with modern AI.

The world’s knowledge lives in formats — PDF, HTML, Word, LaTeX, MP3, MP4 — that were designed for rendering or playback, not for understanding. The moment you hand them to an AI system, you lose structure, semantics, layout, timing, or all of them at once. And the formats AI does speak fluently fall short too: Markdown can’t describe complex content, HTML wastes tokens, LaTeX is ambiguous, and none of them speak audio or video at all.

DocLang fixes this:

AI-native — a controlled vocabulary that aligns 1-to-1 with LLM tokenizers, keeping prompts and outputs short and predictable
Lossless — preserves structure, semantics, layout, and geometry in a single representation
Expressive — first-class support for tables, formulas, code, charts, nested lists, forms, and multimodal content with visual grounding
Beyond documents — extends naturally to audio and video, with native primitives for transcripts, speakers, timestamps, scenes, and audio-visual grounding — so an interview, a lecture recording, or a film script lives in the same representation as a PDF
Unambiguous — every tag has one job, so the same content always serializes the same way
Open — an ISO standard, developed in the open, governed by industry leaders

If you build with LLMs and VLMs on real-world content, DocLang is the substrate you’ve been missing.

Implementation

To demonstrate the full lifecycle of ingesting, converting, validating, and querying DocLang, Bob authored and wired together the DocLang Demonstration Application.

┌─────────────────────────────────────────────────────────────────┐
│                        Browser (UI)                             │
│  ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────────────┐  │
│  │ Markdown  │ │  DocLang  │ │  Upload  │ │  Ask Ollama     │  │
│  │ → DocLang │ │  Editor   │ │ Document │ │  (Q&A on docs)  │  │
│  └─────┬─────┘ └─────┬─────┘ └────┬─────┘ └────────┬────────┘  │
└────────│─────────────│────────────│───────────────────│─────────┘
         │             │            │                   │
         ▼             ▼            ▼                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Flask API (app.py)                            │
│                                                                 │
│  /api/convert/markdown  → markdown_to_doclang()                 │
│  /api/convert/doclang   → doclang_to_html()                     │
│  /api/validate          → validate_doclang()                    │
│  /api/upload/submit     → Docling job started (returns job_id)  │
│  /api/upload/status/<id>→ poll job → doclang + preview          │
│  /api/ask               → Ollama /api/generate                  │
│  /api/save              → output/{name}_{timestamp}.dclg.xml    │
│  /api/samples           → input/**/*.dclg.xml                   │
└──────────┬──────────────────────────┬───────────────────────────┘
           │                          │
           ▼                          ▼
  ┌─────────────────┐      ┌──────────────────────┐
  │  Docling Engine │      │   Ollama (local LLM) │
  │  (PDF/DOCX/HTML │      │   granite / any      │
  │  → DocLang XML) │      │   model installed    │
  └─────────────────┘      └──────────────────────┘

🏗️ System Architecture & Workflow Schemas

The application is structured as a lightweight, fast Flask API backing a multi-tab Single-Page Application (SPA) interface. It seamlessly bridges client-side interactions with heavy-duty document parsing engines and local LLMs.

High-Level System Architecture

The DocLang Demonstration Application is architected as a decoupled, multi-tier system engineered for low latency and smooth document processing. At its core, a lightweight Flask REST API coordinates requests between an interactive Single-Page Application (SPA) frontend, local file storage, and specialized downstream service workers. To keep the UI highly responsive during heavy document transformations, long-running extraction jobs are offloaded to an asynchronous thread pool worker powered by IBM’s Docling engine, while grounded natural language querying is driven directly by a local Ollama LLM instance.

Document Processing & Ingestion Pipeline

Under the hood, the application balances real-time user feedback with heavy computational tasks. The architecture is based on a fast Flask backend running on Python 3.10+, serving an intuitive multi-tab Single-Page Application. Rather than locking up the user interface when parsing massive PDFs, the application decouples frontend UI events from heavy background jobs — handing off document extraction to background threads and local AI inference to Ollama via local API calls.

🛠️ Key Implementation Highlights

Translating the DocLang specification from concept to a production-ready Web application required addressing critical real-world edge cases across multi-threading, schema conversion, and local LLM orchestration. The core backend implementation in app.py bridges low-level system hardware constraints with high-level parsing logic. Below, we break down three foundational components of the application's implementation, detailing how we tackled macOS hardware threading crashes, authored an efficient client-side Markdown converter, and connected DocLang directly to local Ollama inference.

Solving the macOS Metal / PyTorch MPS Threading Crash

When executing deep learning models (such as Docling’s layout and OCR models) inside a background worker thread on macOS, PyTorch attempts to dispatch ops through Apple Metal (MPS). In non-main threads, this throws an unrecoverable C-level abort: MTLCompiler: compileRequest ... Crashing instead.

Bob solved this cleanly in app.py by forcing PyTorch MPS fallback before any imports occur, and pinning Docling explicitly to CPU thread pools:

import os

# MUST be configured prior to importing torch or docling
os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions, AcceleratorOptions, AcceleratorDevice

def _make_converter():
    """Build a DocumentConverter pinned to CPU to ensure thread-safe execution on macOS."""
    accel = AcceleratorOptions(num_threads=4, device=AcceleratorDevice.CPU)

    opts = PdfPipelineOptions()
    opts.accelerator_options = accel

    return DocumentConverter(
        format_options={
            "pdf": PdfFormatOption(pipeline_options=opts),
        }
    )

Hand-Rolled Markdown to DocLang XML Parser

For fast client-side transformations without invoking heavy neural models, app.py features a custom Markdown-to-DocLang parser. It transforms standard Markdown elements into native DocLang tags:

def markdown_to_doclang(md_text: str) -> str:
    """Convert simplified Markdown into valid DocLang XML markup."""
    lines = md_text.strip().splitlines()
    elements: list[str] = []
    i = 0
    while i < len(lines):
        line = lines[i]
        stripped = line.strip()

        if stripped.startswith("### "):
            elements.append(f'  <heading level="3">{stripped[4:]}</heading>')
        elif stripped.startswith("## "):
            elements.append(f'  <heading level="2">{stripped[3:]}</heading>')
        elif stripped.startswith("# "):
            elements.append(f'  <heading level="1">{stripped[2:]}</heading>')
        elif stripped.startswith("```

"):
            lang = stripped[3:].strip() or "text"
            code_lines: list[str] = []
            i += 1
            while i < len(lines) and not lines[i].strip().startswith("

```"):
                code_lines.append(lines[i])
                i += 1
            code_body = "\n".join(code_lines)
            elements.append(
                f'  <code>\n    <label value="{lang}"/>\n'
                f'    <content><![CDATA[\n{code_body}\n    ]]></content>\n  </code>'
            )
        elif stripped.startswith("- "):
            list_items: list[str] = []
            while i < len(lines) and lines[i].strip().startswith("- "):
                list_items.append(f"    <item><text>{lines[i].strip()[2:]}</text></item>")
                i += 1
            elements.append("  <list>\n" + "\n".join(list_items) + "\n  </list>")
            continue
        elif stripped:
            elements.append(f"  <text>{stripped}</text>")

        i += 1

    return "<doclang>\n" + "\n".join(elements) + "\n</doclang>"

Local LLM Q&A Integration with Ollama

DocLang’s concise XML representation makes it optimal for direct inclusion in system prompts. The application routes user queries and DocLang markup directly to local Ollama models:

def ask_ollama(question: str, context_dclg: str) -> str:
    """Perform grounded Q&A over parsed DocLang XML using local Ollama instance."""
    prompt = textwrap.dedent(f"""
        You are a helpful assistant. The following is a document in DocLang format
        (an AI-native XML document standard). Answer the user's question using only
        the information present in the document.

        <document>
        {context_dclg}
        </document>

        Question: {question}
        Answer:
    """).strip()

    resp = requests.post(
        f"{OLLAMA_BASE_URL}/api/generate",
        json={"model": OLLAMA_MODEL, "prompt": prompt, "stream": False},
        timeout=60,
    )
    return resp.json().get("response", "").strip()

📊 Token Efficiency Benchmark

DocLang slashes context window consumption compared to legacy HTML representations — achieving ~64.2% token savings on standard documents containing complex tables, headings, and code samples.

🧪 Automated Testing Suite

To ensure reliability across background task queues, file IO, and API validation, Bob engineered a unit test suite using pytest in tests/test_app.py:

class TestAPIRoutes:
    def test_api_convert_markdown(self, client):
        resp = client.post("/api/convert/markdown", json={"markdown": "# Hello\n\nWorld."})
        assert resp.status_code == 200
        data = resp.get_json()
        assert "doclang" in data
        assert "html_preview" in data
        assert "tokens" in data

    def test_api_upload_submit_creates_job(self, client):
        from io import BytesIO
        data = {"file": (BytesIO(b"<html><body>Hello</body></html>"), "test.html")}
        resp = client.post("/api/upload/submit", data=data, content_type="multipart/form-data")
        assert resp.status_code == 200
        body = resp.get_json()
        assert "job_id" in body

        # Poll async status
        job_resp = client.get(f"/api/upload/status/{body['job_id']}")
        assert job_resp.status_code == 200

💡 Conclusion

The DocLang Demo Application designed by Bob provides a complete blueprint for integrating next-generation AI-native document formats into enterprise software workflows.

By pairing IBM Docling’s multi-format extraction with DocLang’s token-optimized XML schema and Ollama’s local LLM reasoning, developers can build privacy-first, lightning-fast document intelligence pipelines.

Thanks for reading ⭐

Vaulting Beyond Defaults: The Evolution of Secrets Management on Red Hat OpenShift

Alain Airom (Ayrom) — Sun, 19 Jul 2026 12:25:12 +0000

Why using Vault is better to manage your secrets?

In modern containerized infrastructures, managing sensitive data like database passwords, API tokens, and private keys is one of the most critical aspects of day-to-day operations. When moving to Kubernetes and Red Hat OpenShift, understanding the default mechanisms — and where they fall short for enterprise security — is the first step toward building a truly secure by design architecture.

💡 Note from the Field: Before we jump into the post, all code, deployment manifests, and architectural implementation logic featured throughout this guide were designed, orchestrated, and automated by Bob (IBM Bob SDLC).

🤓

The Baseline: Secrets Management in Kubernetes

In vanilla Kubernetes, the native Secret object provides a way to separate sensitive data from application code or standard configurations (ConfigMaps). However, the word "Secret" can be misleading for newcomers:

Base64 Encoding is Not Encryption: By default, Kubernetes secrets are stored as flat, base64-encoded strings within the cluster data store. Base64 is a data transformation format designed to handle binary data over text-based networks; it provides zero obfuscation or security. Anyone with access to the YAML declaration or read permissions to the API can immediately reverse the encoding (echo "bXktcGFzc3dvcmQ=" | base64 -d).
The etcd Vulnerability: In a standard Kubernetes control plane, unless specifically configured otherwise, these base64 strings are stored in plain text inside the etcd database. If an attacker gains access to the underlying master host storage or backups of etcd, the entire cluster's credentials are compromised.
Coarse-Grained Access Control: Kubernetes Roles and RoleBindings restrict access at the resource level, but managing fine-grained programmatic access to specific keys within a single namespace becomes complex and error-prone.

The Upgraded Standard: How OpenShift Secures Native Secrets

Red Hat OpenShift takes the fundamental concepts of Kubernetes and hardens them to meet enterprise compliance and security baselines out-of-the-box.

Mandatory Multi-Tenancy via Projects: OpenShift extends Kubernetes namespaces into Projects. Projects enforce strict multi-tenancy from the start, isolating network traffic, service accounts, and resource limits (ResourceQuotas) so that an application team cannot accidentally view or cross-contaminate another team's secrets.
Automated etcd Encryption at Rest: Unlike vanilla Kubernetes where encryption must be manually configured via an encryption configuration file, OpenShift enables cluster-wide etcd encryption at rest smoothly through its cluster operators. When enabled, secret resources are automatically encrypted using robust cryptographic algorithms (such as AES-256-GCM) before hit-to-disk inside etcd.
Strict Security Context Constraints (SCCs): OpenShift mitigates runtime risks by ensuring pods run under rigorous security rules. Applications cannot blindly run as root or mount forbidden host directories, preventing compromised containers from harvesting cluster tokens or local secrets files directly from the underlying node storage.

While OpenShift native secrets are significantly more robust than vanilla Kubernetes, enterprise security teams often demand zero-trust paradigms, live credential rotation without downtime, centralized audit trails, and elimination of sensitive data from Git repositories entirely. This is where external secrets managers like HashiCorp Vault come into play.

Chapter 1: The Classical Approach — OpenShift Native Secrets (Approach A)

To truly appreciate the advantages of a dynamic secrets manager like HashiCorp Vault, we must first analyze the reference architecture, implementation, and operational lifecycle of the classical, platform-native approach.

High-Level Architecture

In this architecture, the cluster relies entirely on OpenShift’s built-in control plane. Secrets are submitted via the OpenShift API, committed encrypted into etcd, and then bound to the application pod via environment variables or read-only volume mounts.

Step-by-Step Reference Implementation

Declaring the Hardened Project and RBAC Boundaries

First, we establish a clean, production-ready namespace coupled with a dedicated ServiceAccount and explicit Role bindings utilizing the principle of least privilege.

# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: demo
  labels:
    environment: production
    secrets-approach: native
---
apiVersion: v1
kind: ResourceQuota
metadata:
  name: demo-quota
  namespace: demo
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi
    pods: "20"

# 01-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: demo-sa
  namespace: demo
automountServiceAccountToken: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: secret-reader
  namespace: demo
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: demo-sa-secret-reader
  namespace: demo
subjects:
  - kind: ServiceAccount
    name: demo-sa
    namespace: demo
roleRef:
  kind: Role
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Defining the Platform Secrets

Next, we define our credentials using native Secret configurations. Notice that values are raw base64 placeholders.

# 02-secrets.yaml (Excerpt)
apiVersion: v1
kind: Secret
metadata:
  name: demo-db-secret
  namespace: demo
  annotations:
    secrets.management/rotation-interval: "90d"
    secrets.management/last-rotated: "2026-01-01"
type: Opaque
data:
  DB_USER: ZGVtb191c2Vy                         # demo_user
  DB_PASSWORD: CHANGEME_BASE64_ENCODED_PASSWORD==
  DB_HOST: cG9zdGdyZXMuZGVtby5zdmMuY2x1c3Rlci5sb2NhbA==
  DB_PORT: NTQzMg==                             # 5432
  DB_NAME: ZGVtb2Ri                             # demodb

Injecting Secrets into the Application Deployment

The application deployment can consume these secrets in two distinct formats: as environment variables mapped straight into the container’s environment via envFrom, or mounted explicitly as read-only files through standard volumes.

# 04-deployment.yaml (Configuration Excerpt)
spec:
  template:
    spec:
      serviceAccountName: demo-sa
      containers:
        - name: demo-app
          image: image-registry.openshift-image-registry.svc:5000/demo/demo-app:latest
          envFrom:
            - configMapRef:
                name: demo-config
            - secretRef:
                name: demo-db-secret
            - secretRef:
                name: demo-admin-secret
          volumeMounts:
            - name: ldap-secret-vol
              mountPath: /secrets/ldap
              readOnly: true
      volumes:
        - name: ldap-secret-vol
          secret:
            secretName: demo-ldap-secret

How the Application Consumes Native Secrets?

From an application development perspective, using environment-injected native secrets is incredibly simple. There are no specialized APIs, external packages, or external client initializations required. The application merely reads from its operating system context.

# app.py (Excerpt)
import os
from flask import Flask, jsonify

app = Flask(__name__)

class Config:
    SECRET_SOURCE = "environment variables (OpenShift native Secret → envFrom)"

    # The platform injected the value into the process environment
    # before the application process started execution.
    DB_USER     = os.environ.get("DB_USER",     "not-set")
    DB_PASSWORD = os.environ.get("DB_PASSWORD", "not-set")
    DB_HOST     = os.environ.get("DB_HOST",     "not-set")
    DB_PORT     = os.environ.get("DB_PORT",     "5432")
    DB_NAME     = os.environ.get("DB_NAME",     "not-set")

@app.route("/config")
def config():
    return jsonify({
        "approach": "A — OpenShift Native Secrets",
        "secret_source": Config.SECRET_SOURCE,
        "loaded_at": "process start (env vars set by Kubelet before exec)",
        "rotation_note": "Pod RESTART required to pick up a new secret value"
    })

The Operational Reality of Native Secrets

While this appraoch is easy to grasp, has no external system requirements, and operates out-of-the-box in air-gapped data centers, it creates massive friction under enterprise conditions:

The Rotation Problem

When security regulations require quarterly or emergency credential changes, the operations team updates the database engine’s backend password, updates the target Kubernetes Secret object, and must perform a mandatory rolling restart of the application deployments. Because environment variables are bound to the process execution stack at launch time, the containers cannot dynamically fetch the changes, risking service disruption during the rollout window.

The GitOps Paradox

In contemporary workflows, configurations are version-controlled using GitOps engines (like ArgoCD). However, storing raw OpenShift native secret manifests inside Git exposes plaintext credentials to unauthorized auditors or pipeline engineers. Teams must rely on secondary toolsets like Bitnami SealedSecrets. While kubeseal securely encrypts the manifests using asymmetric key pairs before pushing them to public repositories, it introduces an administrative burden—managing cryptographic keys, handling cluster reinstallation decryption failures, and onboarding third-party configurations.

In the next chapter, we will look at A*pproach B: HashiCorp Vault + Vault Agent Injector*, exploring how a specialized identity-driven architecture resolves these operational limitations entirely without rewriting a single line of application code.

Chapter 2: The Modern Alternative — Identity-Driven Secrets with HashiCorp Vault (Approach B)

To overcome the operational limitations of static, platform-bound credentials, modern enterprise architectures transition to an identity-driven security model using HashiCorp Vault.

In this setup, secrets no longer live inside OpenShift’s native etcd storage database, nor are they ever checked into a Git repository. Instead, OpenShift becomes a platform consumer, leveraging its internal cryptographic identities (ServiceAccounts) to request short-lived tokens from a centralized, highly auditable Vault cluster.

Deploying Vault on Red Hat OpenShift

Deploying Vault on OpenShift requires specialized configurations to accommodate strict platform rules, such as Security Context Constraints (SCCs), multi-replica high availability, and native routing. The standard deployment standard utilizes the official Helm chart customized with OpenShift-native parameters.

Vault Cluster Configuration

Below is the reference configuration blueprint using Raft integrated storage (eliminating the operational footprint of external storage backends like Consul):

# vault-values.yaml
global:
  enabled: true
  tlsDisable: false    # Forced TLS for all transit lines
  openshift: true      # Automatically tunes Helm chart to handle OpenShift compliance and SCCs

server:
  ha:
    enabled: true
    replicas: 3
    raft:
      enabled: true
      setNodeId: true
      config: |
        ui = true

        listener "tcp" {
          tls_disable     = 0
          address         = "[::]:8200"
          cluster_address = "[::]:8201"
        }

        storage "raft" {
          path    = "/vault/data"
          node_id = "HOSTNAME"

          # Auto-join configuration for Raft quorum consensus
          retry_join { leader_api_addr = "http://vault-0.vault-internal:8200" }
          retry_join { leader_api_addr = "http://vault-1.vault-internal:8200" }
          retry_join { leader_api_addr = "http://vault-2.vault-internal:8200" }
        }

Bootstrapping Identity-Based Authentication

Once the Vault instance is running on the cluster, we leverage Vault’s native Kubernetes Authentication Method. This allows applications to use their standard OpenShift ServiceAccount token as a secure, temporary proof of identity.

The configuration workflow establishes a secure cryptographic trust loop between Vault and the OpenShift Control Plane API:

Scripted Authentication Setup

The following reference script automates the creation of the auth backend, defines the system boundaries, and maps permissions directly to the target namespace service account:

#!/usr/bin/env bash
# 01-vault-k8s-auth.sh (Excerpt)
set -euo pipefail

echo "=== Configuring Vault Kubernetes Auth for Demo App ==="

# 1. Enable the Kubernetes auth engine
vault auth enable kubernetes || echo "Already enabled"

# 2. Point Vault to the host OpenShift API server for token verification
vault write auth/kubernetes/config \
    kubernetes_host="https://kubernetes.default.svc:443" \
    kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

# 3. Create a strict role matching the application's runtime platform identity
vault write auth/kubernetes/role/demo-role \
    bound_service_account_names="demo-sa" \
    bound_service_account_namespaces="demo" \
    policies="demo-policy" \
    ttl="1h" \
    max_ttl="24h"

Defining Fine-Grained ACL Rules

To adhere to the principle of least privilege, applications must never be handed a broad root token. Vault uses HashiCorp Configuration Language (HCL) policies to enforce strict path isolation. The demo-app is restricted entirely to its own data engine space:

# 00-vault-policy.hcl
# Allow the demo application read-only access to its dedicated database & infrastructure credentials
path "secret/data/demo" {
  capabilities = ["read"]
}

# Allow reading metadata details (e.g. tracking versions for rotation) without exposing values
path "secret/metadata/demo" {
  capabilities = ["list", "read"]
}

# Allow token renewal and self-inspection capabilities (crucial for automated sidecars)
path "auth/token/renew-self" {
  capabilities = ["update"]
}
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

Injecting Secrets securely via the Key-Value Engine

With policies and authentication boundaries active, parameters can be loaded straight into the Vault Secure KV Store. Because this operates entirely through the API or CLI, configurations are maintained out-of-band — safely isolating them from human eyes and source repositories.

#!/usr/bin/env bash
# 02-vault-secrets.sh (Excerpt)
source .env # Local isolated parameters, ignored by Git version control

echo "=== Committing App Secrets to Vault Secure KV Store ==="

# Write all credentials atomically into Version 2 KV backend
vault kv put secret/demo \
    db_user="${APP_DB_USER}" \
    db_password="${APP_DB_PASSWORD}" \
    db_host="${APP_DB_HOST}" \
    db_port="${APP_DB_PORT}" \
    db_name="${APP_DB_NAME}" \
    ldap_url="${APP_LDAP_URL}"

echo "✅ Master credentials stored. These are completely absent from OpenShift's etcd."

In the next sections, we will explore how the Vault Agent Injector seamlessly introduces these paths directly to the pods as ephemeral files, allowing applications to stay zero-trust compliant without writing complex API clients or modification blocks.

Chapter 3: Implementation — Decoupled Vault Injection (Approach B)

Now that HashiCorp Vault is deployed and trusting OpenShift’s identities, we need to bridge the secrets into our application. The gold standard for this without rewriting application code is the Vault Agent Injector.

The Vault Agent Injector is a Mutating Admission Webhook. It monitors incoming pod specifications for specific annotations. When it spots them, it dynamically alters the Pod deployment manifest by embedding two specific platform sidecars into your application stack:

vault-agent-init (Init Container): Runs before your application container executes. It hits Vault using the pod's ServiceAccount identity, downloads the requested secrets, formats them, and writes them to a shared, high-speed ephemeral memory storage (tmpfs) volume mounted at /vault/secrets/.
vault-agent (Runtime Sidecar Container): Runs alongside your application indefinitely. It monitors Vault for updates and automatically rewrites the temporary workspace file on the fly if a secret value is rotated.

High-Level Architecture Flow

This setup decouples the application from Vault completely. The application code only needs to interact with a standard local filesystem file, remaining entirely unaware of Vault’s underlying REST APIs or authentication loops.

Manifest Configuration: Injecting Secrets via Annotations

To apply this pattern, your OpenShift deployment manifest doesn’t configure any native Kubernetes Secret values. Instead, you define annotations that guide the webhook engine.

# 04-deployment-with-vault.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-app
  namespace: demo
  labels:
    app.kubernetes.io/name: demo-app
    secrets-approach: vault-injector
spec:
  replicas: 2
  selector:
    matchLabels:
      app: demo-app
  template:
    metadata:
      labels:
        app: demo-app
      annotations:
        # 1. Activate the injector webhook engine
        vault.hashicorp.com/agent-inject: "true"

        # 2. Specify the authentication role mapped inside Vault
        vault.hashicorp.com/role: "demo-role"

        # 3. Request secret paths and define the output filenames
        vault.hashicorp.com/agent-inject-secret-db.env: "secret/data/demo"
        vault.hashicorp.com/agent-inject-secret-ldap.env: "secret/data/demo"

        # 4. Define custom Go-Template structures to format the data cleanly for consumption
        vault.hashicorp.com/agent-inject-template-db.env: |
          {{- with secret "secret/data/demo" -}}
          export DB_USER="{{ .Data.data.db_user }}"
          export DB_PASSWORD="{{ .Data.data.db_password }}"
          export DB_HOST="{{ .Data.data.db_host }}"
          export DB_PORT="{{ .Data.data.db_port }}"
          export DB_NAME="{{ .Data.data.db_name }}"
          {{- end -}}

        vault.hashicorp.com/agent-inject-template-ldap.env: |
          {{- with secret "secret/data/demo" -}}
          export LDAP_URL="{{ .Data.data.ldap_url }}"
          {{- end -}}
    spec:
      serviceAccountName: demo-sa
      containers:
        - name: demo-app
          image: image-registry.openshift-image-registry.svc:5000/demo/demo-app:latest
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: demo-config
          # Enforce runtime constraints
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 1001
            capabilities:
              drop: ["ALL"]

Code Implementation: Reading secrets dynamically from Python

Because the sidecar drops standard configuration shell files into the ephemeral memory directory, reading them becomes a direct file parsing operation.

Below is how the application logic manages both initialization and dynamic monitoring loops to ingest updates without process restarts:

# app.py (Excerpt for Vault Approach B)
import os
import re
from pathlib import Path
from flask import Flask, jsonify

app = Flask(__name__)

# Defaults to the injector standard directory path
VAULT_SECRETS_PATH = os.environ.get("VAULT_SECRETS_PATH", "/vault/secrets")

class VaultConfig:
    SECRET_SOURCE = "Vault Agent Injector (Shared tmpfs Volume)"

    @staticmethod
    def parse_env_file(filename: str):
        """Parses a Go-templated export file into a dictionary format."""
        secrets = {}
        filepath = Path(VAULT_SECRETS_PATH) / filename

        if not filepath.exists():
            return secrets

        # Match pattern: export KEY="VALUE"
        pattern = re.compile(r'^\s*export\s+([A-Z0-9_]+)\s*=\s*"(.*)"\s*$')
        with open(filepath, "r") as f:
            for line in f:
                match = pattern.match(line)
                if match:
                    key, value = match.groups()
                    secrets[key] = value
        return secrets

    # Dynamic property mapping definitions
    @property
    def DB_PASSWORD(self):
        # Always read fresh from the filesystem to fetch hot rotations on the fly
        secrets = self.parse_env_file("db.env")
        return secrets.get("DB_PASSWORD", "not-found")

    @property
    def DB_USER(self):
        secrets = self.parse_env_file("db.env")
        return secrets.get("DB_USER", "not-found")

    @property
    def DB_HOST(self):
        secrets = self.parse_env_file("db.env")
        return secrets.get("DB_HOST", "localhost")

config_manager = VaultConfig()

@app.route("/config")
def config():
    return jsonify({
        "approach": "B — Vault Token Integration",
        "secret_source": VaultConfig.SECRET_SOURCE,
        "loaded_at": "On-demand filesystem reads (Hot-swappable dynamically)",
        "rotation_note": "Zero downtime or rollouts required during backend password shifts."
    })

@app.route("/db-status")
def db_status():
    return jsonify({
        "db_host": config_manager.DB_HOST,
        "db_user": config_manager.DB_USER,
        # Display masked password to prove it loaded successfully
        "db_password_used": f"{config_manager.DB_PASSWORD[:2]}******" if len(config_manager.DB_PASSWORD) > 2 else "short"
    })

The Lifecycle Revolution: Direct Structural Comparisons

| Security Lifecycle           | Approach A: Native OpenShift Secrets                         | Approach B: Centralized HashiCorp Vault                      |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **Storage Engine Location**  | Standard plain `etcd` Key-Value database.                    | Highly decoupled, encrypted Raft storage layer.              |
| **GitOps/CI-CD Handling**    | Requires third-party tools like `SealedSecrets` or encryption wrappers. | Manifests contain nothing but metadata annotations. Secure parameters are injected entirely out-of-band. |
| **Credential Rotation Loop** | Requires updating objects and performing a rolling deployment update. | The runtime sidecar modifies the local shared volume. Your application picks it up instantly without restarts. |
| **Audit Capabilities**       | Shared cluster-wide. Difficult to isolate individual container tracking parameters cleanly. | Fine-grained, immutable tracking policies. Records every read, renewal, and authentication event instantly. |

By implementing identity-driven secrets through HashiCorp Vault and utilizing the automated sidecar injector on Red Hat OpenShift, engineering teams achieve true zero-trust execution environments. You eliminate the leakage vectors inherent to version control repositories, decouple configurations from infrastructure databases, and enable seamless credential rotation — all without polluting your software assets with complex third-party SDK dependencies.

Conclusion: Elevating OpenShift Native Defense with Zero-Trust Automation

Red Hat OpenShift’s built-in secrets management sets an impressive enterprise baseline. By automating etcd encryption at rest out of the box and enforcing rigid boundaries through multi-tenant Projects and Security Context Constraints, it fixes the glaring security gaps found in vanilla Kubernetes.

However, enterprise governance demands more than just hardened storage; it requires dynamic agility. Transitioning to HashiCorp Vault elevates your security posture from a robust static platform to a proactive, identity-driven ecosystem. Even though OpenShift natively keeps data highly secure on disk, Vault solves the operational overhead of the application lifecycle. By eliminating the GitOps paradox of managing encrypted manifests in repositories, introducing granular, centralized audit logs for strict compliance tracking, and streaming live credential rotations to application containers without triggering disruptive rolling updates, Vault turns a complex security checklist into seamless, zero-trust automation.

| Feature / Security Lifecycle  | ☸️ Standard Kubernetes                                        | 🔴 Standard OpenShift                                         | 🔒 OpenShift + HashiCorp Vault                                |
| ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **Storage Engine & Security** | Stored in `etcd`. **Not encrypted at rest by default** (requires manual KMS provider configuration). base64 encoding only. | Stored in `etcd`. **Encrypted at rest by default** out of the box using AES-256-GCM cryptography. | Stored in highly decoupled, dedicated **Vault Raft storage**. Secrets never land in the cluster’s `etcd` layer. |
| **GitOps & Version Control**  | Plain YAML manifests contain secrets in clear text (base64). Risks repo leakage without 3rd party tools (e.g., `SealedSecrets`). | Same GitOps limitation as Kubernetes; manifests require client-side encryption before committing to git. | **Zero-secret manifests.** Deployment manifests contain only metadata annotations; actual values are handled out-of-band. |
| **Runtime Pod Delivery**      | Injected directly into the container as environment variables or mounted files via standard Kubelet API. | Injected similarly via environment variables or volume mounts, strictly governed by platform **Security Context Constraints (SCC)**. | Injected transparently into a shared, high-speed ephemeral memory storage (`tmpfs` volume) via a **Mutating Webhook Sidecar**. |
| **Credential Rotation Loop**  | Manual or custom scripting. Requires a rolling update deployment to restart pods and pick up new values. | Native rotation still requires object modification and a rolling deployment restart (`oc rollout restart`) to flush stale values. | **Dynamic & Hot-Swappable.** The `vault-agent` sidecar live-streams new values into the pod filesystem without restarting the container. |
| **Audit Capabilities**        | Basic cluster auditing. Difficult to trace exact API read requests to specific container parameters. | Strong platform-wide auditing via standard OpenShift cluster logging and cluster-level audit trails. | **Granular, cryptographic audit logs.** Tracks every authentication, lookup, token renewal, and precise key access. |
| **Least Privilege Isolation** | Scoped broadly by Namespace RBAC boundaries.                 | Scoped tightly by multi-tenant Projects and hardened Security Context Constraints (SCCs). | Scoped mathematically by fine-grained **Vault HCL Policies** mapped directly to individual `ServiceAccount` identities. |

Thanks for reading 🔏

DEV Community: Alain Airom (Ayrom)

Benchmarking Local AI: Building a llama.cpp vs. Ollama Comparison & Benchmarking App

Introduction

System Architecture & Overview

Interface & Local Tool Integration

Ollama: Frictionless Desktop & Daemon Workflows

llama.cpp: Granular Binary & Hardware Optimization

Benchmarking Inference: Streaming vs. Subprocess Parsing

Ollama Streaming Runner

llama.cpp Native Dispatcher Runner

Key Takeaways & Comparison Matrix

Conclusion

Links

Implementing A Simple MCP Hook: From Zero to Stdio-Connected Tools

Introduction

TL;DR-What is an MCP Hook? An Architectural Definition

Implementation-System Architecture & Lifecycle

Server Implementation: Schemas & Tool Handlers

Client Driver & Verification

Overall Test Script

Integration into MCP Hosts (e.g., Bob)

Conclusion: Implementing Your First MCP Hook

Links

Book Review & Technical Implementation: Kubernetes in Action, Second Edition

🚀 Introduction

🏗️ Part 1-Chapter Analysis & Breakdown

Getting Started & Core Architecture (Chapters 1–4)

Running Applications in Kubernetes (Chapters 5–7)

Application Configuration & Storage (Chapters 8–10)

Connecting & Exposing Applications (Chapters 11–13)

Managing Applications at Scale (Chapters 14–18)

Part 2-Putting the book’s knwoledge in Pactice

🛠️ Application Architecture & Deployment Flow

🏗️ Key Components & Applied Patterns

Application Layer (kiada-go)

Kubernetes Resource Mapping

Downward API & Runtime Injection (Chapter 8)

⚡ Quick Verification

📙 Conclusion for the Book

🎯 Conclusion for the Implementation: From Static Code to Executable Architecture with IBM Bob

Links

Building a Full-Stack Document Intelligence with the Docling TypeScript Ecosystem

First things first: what is Docling-TS?

Introduction

Architecture

System Architecture — Three Modes

Offline Data Flow (JSON Viewer)

Live Conversion Data Flow

Package Dependency Map

Mode Decision Tree

Project Structure

Code Deep-Dive

The Offline JSON Viewer — @docling/docling-core in Action

The Express Backend — Proxy to docling-serve

Server bootstrap

File conversion endpoint — forwarding to docling-serve

The SDK Explorer — Copy-Ready Code Examples

Integration Tests — Offline + Live Suites

Application Router

Key Dependencies

Getting Started in 3 Steps

Conclusion

Links

Kubernetes Architectural Shift: Moving Workloads from Rancher Desktop (K3s) to Managed Cluster (part 2)

Enterprise Production vs. Local Prototyping: Red Hat OpenShift (called ROKS) vs. Rancher Desktop!

Introduction and context

Comparison using a sample Deployment: ‘nginx-demo’ (illustration purpose)

External Ingress & Routing

Persistent Storage

Scaling & High Availability

Hardware Acceleration & Specialized Workloads (ROKS Exclusive)

IBM Cloud VPC Security Advantages

Layer 1 — Edge & Perimeter Protection

Layer 2 — VPC Network Perimeter

Layer 3 — Cluster Access Control

Layer 4 — Pod Network Security

Layer 5 — Workload Security

Layer 6 — Identity & Access Management

Layer 7 — Audit, Compliance & Governance

OpenShift-Specific Advantages

The Offline JSON Viewer — `@docling/docling-core` in Action