CLAUDE.md · txn2/kubefwd

Sections

1. Project Overview
2. Integration and Usage Patterns
3. TUI (Terminal User Interface)
4. Git Policy
5. Verification
6. Build and Development Commands
7. Architecture
8. Important Implementation Details
9. Code Organization
10. Contribution Policy
11. Release Process
12. Testing
13. Areas for Improvement
14. Known Limitations and Active Issues
15. Common Issues and Troubleshooting

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

kubefwd is a popular command-line utility for bulk Kubernetes port forwarding, featured in "essential k8s developer tools" lists. It forwards multiple services from one or more namespaces, adding corresponding entries to `/etc/hosts` for local development.

**Key Differentiator from `kubectl port-forward`**: Each service gets its own unique loopback IP address (127.x.x.x), allowing multiple services to use the same port simultaneously (e.g., multiple databases on port 3306, or multiple web services on port 80). This mirrors how services work in the cluster, enabling truly cluster-like local development.

The tool automatically monitors service and pod lifecycle events, starting/stopping port forwards as services are created, deleted, or pods are rescheduled.

## Integration and Usage Patterns

kubefwd is commonly integrated into development workflows:

- **With Tilt**: Blog posts document using kubefwd with Tilt for automated local development setups
- **Development Environment Setup**: Teams use kubefwd to mirror production-like service topologies locally
- **Microservices Development**: Allows developers to run one service locally while accessing dependencies in the cluster via service names
- **Database Access**: Popular for forwarding multiple databases (MySQL, PostgreSQL, MongoDB) on their native ports without port conflicts

The typical workflow: `sudo -E kubefwd svc -n <namespace> --tui` runs in a dedicated terminal while developers work in their IDE, accessing cluster services as if running in-cluster.

## TUI (Terminal User Interface)

kubefwd includes an interactive TUI built with [Bubble Tea](https://github.com/charmbracelet/bubbletea), enabled with `--tui`:

```bash
sudo -E kubefwd svc -n default --tui
```

### TUI Features
- **Real-time service monitoring**: See all forwarded services with connection status
- **Traffic metrics**: Bytes in/out with sparkline graphs
- **Pod log streaming**: View container logs directly in the TUI
- **HTTP activity detection**: Monitor HTTP requests/responses flowing through forwards
- **Auto-reconnect**: Enabled by default in TUI mode, with exponential backoff (1s → 5min max)
- **Keyboard-driven**: Full keyboard navigation (j/k, Enter, Tab, /, ?, q)

### TUI Architecture

The TUI follows the Model-View-Update (MVU) pattern:

- **Event Bus** (`pkg/fwdtui/events`): Decoupled pub/sub communication between components
- **State Store** (`pkg/fwdtui/state`): Centralized, thread-safe state management for all forwards
- **Metrics Registry** (`pkg/fwdtui/metrics`): Traffic counters with atomic operations
- **Components** (`pkg/fwdtui/components`): UI models for services list, logs, detail view

### TUI Keyboard Shortcuts
- `j/k` or arrows: Navigate
- `Enter`: Open detail view
- `Tab`: Switch panels/tabs
- `/`: Filter services
- `r`: Reconnect errored services
- `b`: Toggle bandwidth columns
- `?`: Help overlay
- `q`: Quit

## Git Policy

**All commits require explicit human approval.** Do not run `git commit` unless the user explicitly asks you to commit. Always show the diff or summarize changes and wait for approval first.

## Verification

**"Testing" means `make verify`, not `go test ./...`.** Run it before handing work back; it runs every check CI runs, with the same pinned tools, and a change isn't done until it passes.

The gates (details in CONTRIBUTING.md, "Quality Gates"):

- **Formatting**: gofmt, goimports (`github.com/txn2/kubefwd` local prefix), gofumpt over the whole tree. Fix with `make fmt`.
- **Lint**: every linter in `.golangci.yml` applies to lines changed since the merge base with `origin/master` (`make lint`, CI `--new-from-rev`). Pre-existing issues elsewhere don't fail; anything touched must pass. `make lint-full` shows the backlog. A `//nolint` or `#nosec` needs a reason.
- **Complexity** (production code): gocyclo 10, gocognit 15, nestif 5, dupl 150, nakedret 30. Split functions rather than suppressing.
- **Layering**: depguard rules in `.golangci.yml`; `pkg/` never imports `cmd/`, leaf packages import nothing first-party, the forwarding core never imports `fwdapi`/`fwdmcp`.
- **Coverage**: total ≥ 80% (`make coverage-check`); changed lines ≥ 80% (`make patch-coverage`). Both block, here and in codecov. Root-only or cluster-only code is made testable by injecting the OS call (see `runCommand` and `goos` in `pkg/fwdapi/network.go`), not left uncovered.
- **Security**: `make security` runs gosec, govulncheck on both modules (gated by `scripts/govulncheck-gate.py` against `.govulncheck-allow.txt`), and osv-scanner (against `osv-scanner.toml`). Upgrade rather than accept; an accepted advisory needs a reason and expires.
- **SAST**: `make semgrep` (p/golang, whole tree) and `make semgrep-diff` (`.semgrep-diff/` rules, changed lines). CodeQL runs `security-and-quality` in CI.
- **Mutation**: `make mutate` (gremlins, 60% efficacy), weekly in CI. Too slow for every change.
- **Toolchain**: Go is pinned by the `toolchain` line in go.mod; CI's setup-go reads the same line. Tool versions are pinned in the Makefile and installed into `.tools/`.

## Build and Development Commands

### Building
```bash
# Build the project (uses goreleaser)
go build -o kubefwd ./cmd/kubefwd/kubefwd.go

# Build with version information
go build -ldflags "-X main.Version=dev" -o kubefwd ./cmd/kubefwd/kubefwd.go
```

### Testing
```bash
# Run all tests
go test ./...

# Run tests for a specific package
go test ./pkg/fwdport

# Run tests with verbose output
go test -v ./pkg/fwdport
```

### Running Locally
```bash
# Requires root/sudo for network interface management and /etc/hosts modification
sudo ./kubefwd svc -n <namespace>

# Use -E flag to preserve environment (especially KUBECONFIG)
sudo -E ./kubefwd svc -n <namespace>

# With interactive TUI (recommended for development)
sudo -E ./kubefwd svc -n <namespace> --tui
```

### Dependencies
```bash
# Download dependencies
go mod download

# Update dependencies
go mod tidy
```

### Debugging and Development

```bash
# Enable verbose logging
sudo -E ./kubefwd svc -n <namespace> -v

# Test with a single service using field selector
sudo -E ./kubefwd svc -n <namespace> -f metadata.name=<service-name>

# Test with label selector
sudo -E ./kubefwd svc -n <namespace> -l app=myapp

# Use IP reservation config for reproducible testing
sudo -E ./kubefwd svc -n <namespace> -z example.fwdconf.yml
```

The verbose flag (`-v`) enables debug-level logging (logrus.DebugLevel), which shows:
- Service registry operations
- Pod sync events
- IP allocation details
- Port forwarding lifecycle events

### Demo Environment

A comprehensive demo manifest is available for testing:

```bash
# Deploy 60 services across 2 namespaces
kubectl apply -f test/manifests/demo-microservices.yaml

# Forward all demo services with TUI
sudo -E ./kubefwd svc -n kft1,kft2 --tui

# Cleanup
kubectl delete -f test/manifests/demo-microservices.yaml
```

## Architecture