cockpit-kata/quickstart.md

Quick Start Guide — Cockpit Kata Containers

This guide walks you through installing and running Cockpit Kata Containers in both standalone mode (for development and demo) and Cockpit module mode (for production use on a real Kata host).

---

Table of Contents

1. Standalone Mode (No Kata Required)
2. Cockpit Module Mode (Production)
3. Verifying the Installation
4. Common Issues and Fixes
5. Next Steps

---

1. Standalone Mode (No Kata Required)

Use standalone mode to explore the UI, develop features, or demo the module without a Kata Containers installation. All data comes from the mock layer — no real sandboxes, images, or configuration files are needed.

Prerequisites

Requirement	Version	Check Command
Node.js	18+	node --version
npm	9+	npm --version
(or) bun	1+	bun --version

Steps

# 1. Clone the repository
git clone <repo-url> cockpit-kata-containers
cd cockpit-kata-containers

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev

The app runs at http://localhost:3000. You should see the Kata Containers module with:

• 5 mock sandboxes (3 running, 1 stopped, 1 error)
• 4 pre-imported images (1 with validation errors)
• 4 runtime configurations (kata-qemu, kata-clh, kata-fc, kata-dragonball)
• Simulated metrics for running sandboxes

What You Can Do

Feature	How to Try It
Browse sandboxes	Click "Sandboxes" in the sidebar — view the table, click a row for details
View sandbox detail	Click any sandbox name — see Overview, Metrics, Network, Console tabs
Import an image	Click "Import Image" — walk through the 4-step wizard with any .tar.gz or .img file
Export an image	Click "Export" — select a QCrows image, choose qcow2/ISO/PXE format, configure options, click Export
Inspect kernel	Click "Kernel" — view kernel config, boot params, hypervisor compatibility, and regenerate initrd
Push via PXE	Click "Import Image" → violet Radio button on any QCrows image → configure TFTP and push
Build a custom image	Click "Build Guide" — follow rootfs or initrd instructions with progress tracking
Edit configuration	Click "Configuration" — select a profile, click "Edit Config", modify TOML, save
View metrics	Click "Metrics" — see aggregate stats and per-sandbox breakdowns

Environment Variables (Optional)

Variable	Default	Description
PORT	3000	Development server port
KATA_IMAGE_DIR	/tmp/kata-uploads	Directory for uploaded images (standalone mode)

---

2. Cockpit Module Mode (Production)

Use Cockpit module mode on a host that runs Kata Containers. The module communicates with kata-runtime, crictl, kata-monitor, and the container runtime via Cockpit's bridge APIs.

Prerequisites

Requirement	Version	Install
Cockpit	286+	OS package manager
kata-runtime	2.5+	See Kata Containers docs
containerd	1.6+	OS package manager
crictl	1.25+	OS package manager
KVM support	enabled	BIOS/UEFI + kernel module
Node.js	18+	For building the module only
npm	9+	For building the module only

Verify KVM Support

# Check if KVM is available
ls -la /dev/kvm

# Check if KVM kernel module is loaded
lsmod | grep kvm

# If not loaded, load it
sudo modprobe kvm_intel   # Intel CPUs
sudo modprobe kvm_amd     # AMD CPUs

Verify Kata Installation

# Check kata-runtime version
kata-runtime --version

# Run the built-in host check
kata-runtime check

Build and Install the Module

# 1. Enter the Cockpit module directory
cd cockpit-kata/

# 2. Install build dependencies
npm install

# 3. Build the production bundle
npm run build
# Output: dist/index.js, dist/index.js.map, dist/manifest.json

# 4. Install to Cockpit's package directory
sudo cp -r dist/ /usr/share/cockpit/kata/

# 5. Verify Cockpit sees the module
cockpit-bridge --packages | grep kata
# Expected output: kata

Development Install (Symlink)

For iterative development, use a symlink instead of copying:

cd cockpit-kata/
npm install
npm run devel-install   # Creates ~/.local/share/cockpit/kata → $(pwd)

Changes are not live — you need to rebuild (npm run build) and refresh the browser. For auto-rebuild:

npm run watch            # Rebuilds on every file change

Start kata-monitor (For Metrics)

The Metrics Dashboard requires kata-monitor running as a Prometheus endpoint:

# Start kata-monitor on the default port (8090)
sudo kata-monitor --listen-address 127.0.0.1:8090 &

# Verify it's running
curl -s http://127.0.0.1:8090/metrics | head -5

If you use a different address or port, update the CSP in cockpit-kata/manifest.json:

"content-security-policy": "default-src 'self'; connect-src 'self' http://YOUR_ADDRESS:YOUR_PORT ws:; ..."

Access Cockpit

# Start Cockpit (if not already running)
sudo systemctl enable --now cockpit.socket

# Open in browser
# https://<host-ip>:9090

Navigate to Kata Containers in the Cockpit sidebar.

---

3. Verifying the Installation

Standalone Mode

1. Open http://localhost:3000
2. You should see the sidebar with 7 navigation items
3. Click "Sandboxes" — 5 mock sandboxes should appear
4. Click "Import Image" — the wizard should load with drag-and-drop zone
5. Click "Export" — QCrows image list with qcow2/ISO/PXE format selector
6. Click "Kernel" — kernel config viewer with hypervisor compatibility matrix
7. Click "Configuration" — 4 runtime profiles should be listed
8. Open browser DevTools (F12) — check for console errors (there should be none)

Cockpit Module Mode

1. Open Cockpit at https://<host>:9090
2. Navigate to "Kata Containers" in the sidebar
3. The sandbox list should show real Kata sandboxes (if any are running)
4. Click "Configuration" — you should see the actual configuration.toml files from /usr/share/defaults/kata-containers/
5. Click "Edit Config" on a profile — modify a value, click Save, then verify the file was updated:

   cat /usr/share/defaults/kata-containers/configuration-qemu.toml
   

---

4. Common Issues and Fixes

"cockpit-bridge --packages" doesn't show kata

Cause: The module files aren't in the right directory or Cockpit hasn't refreshed its cache.

# Verify the files are there
ls -la /usr/share/cockpit/kata/
# Should show: index.js, index.js.map, manifest.json

# Restart Cockpit to pick up new packages
sudo systemctl restart cockpit

kata-runtime check fails

Cause: KVM not available, kata-runtime not installed, or wrong container runtime.

# Check KVM
ls /dev/kvm

# Check containerd CRI socket
ls /run/containerd/containerd.sock

# Check kata-runtime
which kata-runtime
kata-runtime --version

# Full diagnostic
kata-runtime check

Metrics Dashboard shows "kata-monitor not running"

Cause: kata-monitor is not started or not on port 8090.

# Start it
sudo kata-monitor --listen-address 127.0.0.1:8090 &

# Or if it's on a different port, update the CSP in manifest.json

Build fails with TypeScript errors

# Clear caches
rm -rf cockpit-kata/node_modules cockpit-kata/dist
cd cockpit-kata && npm install && npm run build

Blank page in Cockpit

Cause: CSP blocking the module's scripts or network requests.

1. Open browser DevTools → Console
2. Look for CSP violation messages
3. Update manifest.json's content-security-policy to allow the required origins

---

5. Next Steps

Once the module is running:

1. Create a RuntimeClass — Set up Kubernetes RuntimeClasses that reference your Kata configurations:

   kubectl apply -f - <<EOF
   apiVersion: node.k8s.io/v1
   kind: RuntimeClass
   metadata:
     name: kata-qemu
   handler: kata-qemu
   EOF
   

2. Launch a Kata pod — Deploy a pod using the RuntimeClass:

   kubectl run nginx-kata --image=nginx --runtimeclass=kata-qemu
   

3. Import a custom image — Use the Import Image wizard to bring in a rootfs or initrd with your application pre-installed.

4. Build your own image — Follow the Build Guide to create a custom Kata container image from scratch.

5. Configure runtime settings — Use the Configuration view to tune vCPU, memory, and boot parameters per VMM profile.

6. Export for deployment — Use the Export view to convert a QCrows image to qcow2 (QEMU VM), ISO (live USB), or PXE (network boot).

7. Install QCrows CLI tools — The automated installer deploys five CLI tools to /usr/local/bin/:

   qcrows-pack      # Create .qcrows archives
   qcrows-verify    # Verify .qcrows integrity
   qcrows-inspect   # Read .qcrows metadata
   qcrows-export    # Export to qcow2, ISO, or PXE
   qcrows-initrd-regen  # Regenerate initrd (env-aware)