dotnet-krp 1.0.5

krp - Kubernetes Reverse Proxy

krp is a lightweight Kubernetes reverse proxy designed to provide on-demand port forwarding and seamless forwarding to internal Kubernetes resources. The tool facilitates automatic port forwards and provides dynamic routing via loopback addresses.

Features

• On-Demand Port Forwarding – Automatically runs kubectl port-forward when you need it.
• Context Aware – Adapts to changes in your current cluster context.
• Automatic Cleanup – All active port forwards is cleaned up on application exit.
• Dynamic Traffic Routing – Routes through localhost using hosts file or WinDivert
• Zero Configuration – Once running, the tool requires no further setup or user intervention.

Dependencies

• DnsClient – DNS lookups for HTTP endpoints.
• kubectl port-forward – Forwards pod ports to local ports.
• kubernetes-client/csharp – Tracks context changes and discovers endpoints.
• Spectre.Console – Enables an interactive and visually rich terminal user interface.
• windivert – Intercepts DNS requests for Kubernetes hostnames and redirects traffic to krp.
• YARP – Provides dynamic HTTP(S) routing.

How krp works

1. Endpoint registration:
   Uses static configuration or dynamic discovery for endpoints.

2. Routing configuration:
   Each endpoint will get a unique loopback address (eg. 127.0.0.x myapi.namespace).

3. Reverse proxying:
   Listens on the local machine and proxies requests to endpoint targets.

4. Port forwarding endpoints:
   Runs kubectl port-forward and forwards traffic to Kubernetes pods to local ports. Re-uses existing process if already exists, and if the pod dies the process also dies in which case a new one will spawn on-demand.

5. HTTP proxy endpoints:
   Routes to local port if up, otherwise routes to original IP.

Examples

Use case: Kubernetes endpoint

.UseEndpoint(0, 80, "namespace", "service/myapi") // 0 for dynamic local port selection

• Assume your cluster has a service exposed at myapi.namespace:80.
• The DNS will be modified to resolve myapi.namespace to 127.0.0.x (using hosts file or WinDivert).
• Traffic will be proxied to krp.
• krp will find corresponding target endpoint based on loopback address and run kubectl port-forward to forward traffic to local port.
• You can then make requests as if the service was hosted locally: curl myapi.namespace

Use case: HTTP proxy endpoint

.UseHttpEndpoint(5001, "http", "domain.com", "api/service/v2")

• Assume your API gateway is using domain.com/api/service/v2.
• The DNS will be modified to resolve domain.com to 127.0.0.x (using hosts file or WinDivert).
• Traffic will be proxied to krp.
• krp will find corresponding service based on loopback address and forwards traffic to local port 5001 if up.
• You can then make requests to the URL which will be proxied locally: curl domain.com/api/service/v2

Getting started 🚀

Prerequisites

• kubectl must be installed and authenticated against your Kubernetes cluster.
• hosts file modifications requires administrator privileges.
• windivert for Windows Packet Filter driver requires administrator privileges.

Installation

# Using local code
git clone https://github.com/eddietisma/krp.git
cd krp
dotnet run

# Using dotnet tool
dotnet tool install --global dotnet-krp
krp

# Using docker
docker compose -f https://raw.githubusercontent.com/eddietisma/krp/main/docker-compose.yml up

# Setup HTTPS
dotnet dev-certs https -ep "%USERPROFILE%\.krp\krp.pfx" -p your-cert-password --trust

Usage

Configuration

You can configure port-forwarding and routing behavior as follows:

# krp --help
Usage: krp [options]

Options:
  -v|--version                   Show version information.
  -n|--nameserver <NAMESERVERS>  DNS server, used for HTTP proxy endpoints
                                 Default value is: 8.8.8.8.
  --no-certificate-validation    Disable certificate validation
  --no-discovery                 Disable automatic Kubernetes endpoint discovery
  --no-ui                        Disable terminal UI
  -f|--forwarder <FORWARDER>     Forwarding method
                                 Allowed values are: tcp, http, hybrid.
                                 Default value is: hybrid.
  -r|--routing <ROUTING>         Routing method
                                 Allowed values are: hosts, windivert.
                                 Default value is: windivert.
  -?|-h|--help                   Show help information.

Environment variables:
  KRP_HOSTS                       Override path to hosts file

Routing methods

hosts

1. Modifies system hosts file (eg. C:\Windows\System32\drivers\etc\hosts on Windows).
2. Each endpoint gets a unique loopback IPs (e.g., 127.0.0.x).
3. Network traffic destined for these loopback IPs is intercepted and redirected to krp.

Requirements

• Requires administrator privileges to modify the hosts file.
• Requires administrator privileges when running in docker.
• Requires a mounted path and env variable KRP_HOSTS when running in docker.

windivert (default)

WinDivert is a Windows packet capture and manipulation tool used by krp to implement a transparent UDP proxy for the DNS protocol. It redirect DNS traffic for endpoint hostnames. When enabled, WinDivert allows krp to dynamically reroute traffic to loopback addresses.

1. Captures outgoing DNS requests (UDP/53) matching endpoints hostnames.
2. Crafts DNS responses to resolve these hostnames to unique loopback IPs (e.g., 127.0.0.x).
3. Network traffic destined for these loopback IPs is intercepted and redirected to krp.

Requirements

• Only supported on Windows.
• Running WinDivert requires administrator privileges to capture and inject network packets.

Forwarders available

HttpForwarder

• Supports HTTP requests (only).
• Supports domain based routing (using HTTP headers).
• Multiplexing HTTP/1.1 and HTTP/2 over cleartext using same port without TLS is not supported .
  • https://github.com/dotnet/aspnetcore/issues/13502.
• Uses SSL termination.
  • For HTTPS either disable certificate validation on client or setup certificate for each domain.

TcpForwarder

• Supports low-level TCP requests.
• Supports domain based routing (using domain-based IP per hostname in hosts file).

TcpWithHttpForwarder (default)

• Supports low-level TCP requests.
• Supports domain based routing (using domain-based IP per hostname in hosts file)
• Forwards HTTP/x request to HttpForwarder using packet inspection.
  • Inspects TCP traffic and routes HTTP requests to different server ports based on protocol (81 for HTTP/1.1 and 82 for HTTP/2) without TLS requirement.

Running in Docker

To run krp in a Docker container, follow these steps:

1. Start Docker Desktop as an administrator (required for hosts file modification).

2. Build and run the Docker container:

   docker buildx bake
   docker compose up -d
   

3. Authenticate kubectl with cluster:
   Most providers will encrypt the auth config for the specific machine. Hence mounting the config folder won't work inside the container.

   # For AKS
   docker exec -it $(docker ps --filter "name=krp" --format "{{.ID}}") az login  --use-device-code
   docker exec -it $(docker ps --filter "name=krp" --format "{{.ID}}") kubelogin convert-kubeconfig -l azurecli
   
   # For GKE
   todo..
   
   # For EKS
   todo...
   

Example docker-compose.yml

services:
  krp:
    build:
      context: .
    image: eddietisma/krp:latest
    container_name: krp
    restart: unless-stopped
    ports:
      - "80:80"
    #  - "443:443"
    environment:
    #  ASPNETCORE_Kestrel__Certificates__Default__Password: your-cert-password
    #  ASPNETCORE_Kestrel__Certificates__Default__Path: /root/.krp/krp.pfx
      AZURE_CONFIG_DIR: /root/.krp/.azure
      KRP_ENDPOINT_EXPLORER: false
      KRP_HOSTS: /mnt/hosts
    volumes:
      - ~/.kube:/root/.kube
      - ~/.krp:/root/.krp
      - /c/Windows/System32/drivers/etc/:/host_etc/ # win
      # - /etc/hosts:/mtn/hosts/ # Linux/macOS

Roadmap / Ideas

• Add integration tests.
• Auto-discovery of Kubernetes services.
• Support for low-level TCP traffic.
• Support for low-level UDP traffic.
• Support for translating internal Kubernetes IPs.
• Eliminate hosts file dependency using WinDivert/PF/iptables (or mitmproxy) for more flexible routing.
• Cross-platform support (Linux/macOS).
• User interface.
• Add GIF recordings of terminal use cases in README.