kubefwd

For more information on using kubefwd, refer to the following resources:

• REST API Reference: For direct API access when building custom tooling.
• Getting Started: For installation instructions and basic usage patterns.
• User Guide: For detailed information on using the interactive terminal interface.

The kubefwd documentation site uses a 'Token Alignment' design strategy. It utilizes the MkDocs Material theme for core functionality (navigation, search, sidebar, version selector) but applies a custom visual layer via docs/stylesheets/extra.css to align with the txn2 visual identity.

Key design principles:

• Visual Identity: Colors, typography, and spacing are derived from the upstream txn2/www tokens.
• Implementation: Tokens are mirrored as CSS custom properties in :root within extra.css.
• Homepage: Uses a custom Material template (docs/overrides/home.html) to provide a full-bleed layout that overrides the standard header, container, and footer blocks.

kubefwd MCP uses a two-process architecture to separate privilege levels, ensuring your AI client never requires root access:

1. kubefwd (elevated privileges): Requires sudo. It manages actual port forwarding via the Kubernetes API, creates loopback IP aliases (127.x.x.x), modifies /etc/hosts, and exposes a REST API on http://localhost:8080 (configurable).
2. kubefwd mcp (standard user): Runs as an unprivileged MCP server via stdio transport. It communicates with the privileged kubefwd process via the REST API and is automatically spawned by AI clients.

kubefwd supports Headless Services (ClusterIP: None) by forwarding to all pods matching the service selector. This is critical for StatefulSets or databases where you need to address specific pods.

Addressing Pattern:

• service-name maps to the first pod.
• pod-name.service-name maps to each specific pod.

When writing content for this project, follow these strict linguistic rules:

• No dashes: Do not use em-dashes (—) or en-dashes (–). Use commas, periods, colons, parentheses, slashes, or hyphens.
• No AI vocabulary: Avoid words like seamless, leverage, comprehensive, robust, delve, unleash, elevate, or embark.
• Case usage: Use Sentence case for body text. Use lowercase for rail and label text. Title case should be rare.
• Section indices: Use the format § 01 / title (with a slash, not a dash).
• Year ranges: Use a hyphen (e.g., 2017-2026).

To use kubefwd with an MCP-compatible AI client, you must first start the kubefwd process with the API enabled. It is highly recommended to use the --tui flag to visually monitor AI-driven activity and use sudo -E to ensure your KUBECONFIG environment variable is preserved.

Important: You must set a known API key using the KUBEFWD_API_KEY environment variable. If left unset, kubefwd generates a random key that the MCP bridge cannot discover, resulting in 401 errors for all tool calls.

# Set a known key so the MCP bridge can authenticate
export KUBEFWD_API_KEY=my-known-key

# Start in idle mode with API (waits for MCP commands)
sudo -E kubefwd

# OR start with TUI to monitor AI-driven activity (Recommended)
sudo -E kubefwd --tui

# OR pre-forward a namespace and enable API
sudo -E kubefwd svc -n default --api

For automation, omit the --tui flag to run in non-interactive mode. You can manage the process in the background and use timeout/retry configurations for long-running tests.

Non-Interactive Execution

sudo -E kubefwd svc -n testing -l app=test &
KUBEFWD_PID=$!

# Run your tests
npm test

# Cleanup
kill $KUBEFWD_PID

Timeout and Resync Configuration

Use these flags to manage long-running processes:

• --timeout: Total duration (e.g., 3600)
• --retry-interval: Interval between retries (e.g., 30s)
• --resync-interval: Interval for resyncing (e.g., 10m)

Example: sudo -E kubefwd svc -n default --timeout 3600 --retry-interval 30s --resync-interval 10m

You can run kubefwd inside Docker for isolated environments. Two image variants are available:

• txn2/kubefwd (Alpine-based, smaller)
• txn2/kubefwd:ubuntu (Ubuntu-based, more tools)

Basic Usage

docker run -it --rm --privileged \
  --name kubefwd \
  -v "$HOME/.kube:/root/.kube:ro" \
  txn2/kubefwd services -n my-namespace --tui

Docker Compose Integration

version: '3.8'

services:
  kubefwd:
    image: txn2/kubefwd
    privileged: true
    volumes:
      - ~/.kube:/root/.kube:ro
    command: services -n development
    networks:
      - app-network

  my-app:
    build: .
    depends_on:
      - kubefwd
    networks:
      - app-network

networks:
  app-network:

Use the --field-selector (-f) flag to filter services by metadata fields, such as the service name.

# Forward single service by name
sudo -E kubefwd svc -n default -f metadata.name=my-service --tui

# Exclude a service
sudo -E kubefwd svc -n default -f metadata.name!=unwanted-service --tui

Use the --mapping (-m) flag to remap service ports to different local ports. This is useful if you cannot bind to low ports (like 80) or need to avoid local port conflicts.

# Map port 80 to local 8080
sudo -E kubefwd svc -n default -m 80:8080 --tui

# Multiple mappings
sudo -E kubefwd svc -n default -m 80:8080 -m 443:8443 --tui