Documentation

• 1: Installation
• 2: Usage
• 3: Clients

1 - Installation

Introduction

This installation covers installing the kubectl-power-forward binary to your system. You will need some kind of client to use it, like a browser or application. The later is not part of this documentation.

System requirements

kubectl-power-forward is built to run on Linux and Mac, both with amd64 and arm64 (e.g. Apple Silicon) CPUs.

Installation / Update steps

The following procedure explains how to install kubectl-power-forward as binary.

1. Go to the release page, choose your release and download the archive matching you system
2. Unpack the archive, e.g. tar -xf <PAHT_TO_ARCHIVE>
3. Place the binary from the archive to a localtion in your PATH variable, e.g. /usr/local/bin

Optional: Allow binding privileged ports

If you want to use kubectl-power-forward with ports < 1024 (e.g. 80 or 443 for easier usage with HTTP traffic), you can either use sudo mode or add the NET_BIND_SERVICE capability to the binary. You can do this with

$ sudo setcap 'cap_net_bind_service+ep' "$(which kubectl-power-forward)"

Uninstalling

Remove the binary with

$ rm $(which kubectl-power-forward)

Next steps

Read the Usage to learn how to set up forwarding.

2 - Usage

kubectl-power-forward is used with a configuration file. Per default, it searches for a file .power-forward.yaml in the current directory. Use can use the --config (short -f) flag to reference a different file.

Forwarding to Kubernetes

Forwarding to Kubernetes works with targeting a Kubernetes service. You need the following information to describe a service configuration:

• namespace - The namespace the service is deployed in.
• serviceName - The name of the service to be forwarded to.
• podPort - The port on the pod (not service!) to be forwarded to.
• localPort - The local port used to forward to Kubernetes.

You can define multiple forwards:

forwards:
  - namespace: default
    serviceName: echoserver
    podPort: 5678
    localPort: 8080
  - namespace: production
    serviceName: very-important-app
    podPort: 80
    localPort: 8081

If a connection is lost (rescheduling of a pod), kubectl-powre-forward will reconnect to a different pod immediately.

Forwarding from specific contexts

By default, kubectl-power-forward uses the user’s current context, respecting KUBECONFIG environment variable. You can optionally add a context parameter to specific a particular for one forward, while using another specific or the current context for other forwards.

forwards:
  - namespace: default # this is using the current context
    serviceName: echoserver
    podPort: 5678
    localPort: 8080
  - namespace: test
    serviceName: very-important-app
    podPort: 80
    localPort: 8081
    context: prod
  - namespace: production
    serviceName: very-important-app
    podPort: 80
    localPort: 8082
    context: prod

Adding a SOCKS proxy

You can also add a SOCKS proxy to allow using custom domains locally. You have to explicitly enable it via the proxy.socks.enabled parameter. To define a domain that should be intercepted and pointed to localhost, add a hostname to your forwards:

proxy:
  socks:
    enabled: true
    listenAddress: "0.0.0.0:1080" # default
forwards:
  - namespace: default
    serviceName: echoserver
    podPort: 5678
    localPort: 8080
    hostname: echo.example.org

Now you can access the forwarded server with the custom URL

$ curl --socks5-hostname 127.0.0.1:1080 http://echo.example.org:8080

Adding a HTTP reverse proxy

You can add a HTTP server to use custom domains with real-world ports. As you already set the hostnames with the SOCKS proxy configuration, you only have to enable the reverse proxy:

proxy:
  socks:
    enabled: true
  httpReverse:
    enabled: true
    listenAddress: "0.0.0.0:80" # default, requires NET_BIND_SERVICE capability
forwards:
  - namespace: default
    serviceName: echoserver
    podPort: 5678
    localPort: 8081
    hostname: echo.example.org

This allows you to query you workload with the given domain and port

$ curl --socks5-hostname 127.0.0.1:1080 http://echo.example.org

3 - Clients

Browser: Firefox

Follow this guide. Make sure to use Proxy DNS when using SOCKS5 v5 to be able to use custom domains.

CLI: curl

Use the --socks5-hostname option and point it to your SOCKS proxy address. Check all options with curl --help all | grep -E 'socks|proxy'.