kubectl-portal

A kubectl plugin that launches an HTTP proxy, enabling you to make HTTP requests (or open WebSocket/TCP connections) to Services, Pods and any other host reachable from within your cluster.

$ kubectl portal
Creating proxy resources...
Resources created
Waiting for proxy to be ready...
Proxy is ready
Listening at localhost:7070

which can then be used with any e.g. HTTP client with HTTP proxy support, such as cURL with -x:

$ curl -x localhost:7070 http://my-service/my-endpoint
{"foo": "bar"}

See how usage of kubectl portal compares to kubectl proxy/port-forward in the section below.

Installation

You can install kubectl-portal via one of these methods:

Krew (recommended)

Assuming you have Krew installed, run:

kubectl krew install portal

Install from Binary

You can go to the releases page, and download the binary that corresponds to your system.

Build from Source

You'll need to run the following commands:

git clone https://github.com/federicotdn/kubectl-portal.git
cd kubectl-portal
make build

After that, copy the kubectl-portal binary somewhere in your $PATH - or run ./kubectl-portal directly.

Usage

You can run kubectl portal --help to get an overview of the command line flags available. By default, running kubectl portal will perform the following steps:

1. A Pod will be created in the currently selected cluster, which will run the HTTP proxy.
2. kubectl port-forward will be executed, forwarding a local TCP port (by default, 7070) to the proxy Pod.
3. The command will wait until the user presses Ctrl-C to interrupt the operation.
4. The proxy Pod will be deleted and the command will exit.

While kubectl-portal is running, you'll need to configure your HTTP, WebSocket or TCP client to use the HTTP proxy at http://localhost:7070. The way this is done varies between clients, but here are some examples:

HTTP

cURL

$ curl -x localhost:7070 http://my-service/my-endpoint

(note that the -x flag is not related to -X).

GNU Emacs + Verb

* Example            :verb:
:properties:
:Verb-Proxy: localhost:7070
:end:
get http://my-service/my-endpoint

WebSocket

websocat + socat

websocat -t --ws-c-uri=ws://my-service/my-ws-endpoint - ws-c:cmd:'socat - proxy:localhost:my-service:80,proxyport=7070'

Or, if the target server is using TLS (port 443):

websocat -t --ws-c-uri=wss://my-service/my-ws-endpoint - ws-c:ssl-connect:cmd:'socat - proxy:localhost:my-service:443,proxyport=7070'

(in some cases, adding --tls-domain=my-service will be necessary).

Raw TCP

netcat

netcat -X connect -x localhost:7070 my-service 80

URLs of Services and Pods

Figuring out the correct URL to use mostly depends on the DNS name of the resource we want to contact. Here's a short guide:

For a Service my-service:

• If the Service is in the currently selected namespace: http://my-service.
• If the Service is in namespace my-namespace: http://my-service.my-namespace.

For a Pod with name my-pod:

• First, find the Pod's IP using: kubectl get pod my-pod --template {{.status.podIP}}. The URL then is http://<IP>.

Change http:// to https://, ws:// or wss:// when needed.

Comparison with kubectl proxy/port-forward

There is some overlap between how kubectl portal/proxy/port-forward can be used in order to send HTTP requests. These tables aim to clear it up to some degree:

kubectl proxy	kubectl portal (this project)
Connect to Services and Pods.	Connect to Services, Pods, or hosts reachable from within the cluster (e.g. database, dashboard, etc).
URL example: http://localhost:8001/api/v1/namespaces/default/services/my-service:80/proxy/my-endpoint.	URL example: http://my-service/my-endpoint (with localhost:7070 as proxy).
Must always specify the Service/Pod namespace.	When connecting to a Service, specifying the namespace is optional.
When connecting to a Pod, must provide the Pod's name.	When connecting to a Pod, must provide the Pod's IP.
Does not allow raw TCP connectios.	Allows raw TCP connections via HTTP CONNECT.

kubectl port-forward	kubectl portal (this project)
Connect to a Pod.	Connect to Services, Pods, or hosts reachable from within the cluster (e.g. database, dashboard, etc).
URL example: http://localhost:6000/my-endpoint.	URL example: http://my-service/my-endpoint (with localhost:7070 as proxy).
Specifying the Pod's namespace is optional.	When connecting to a Service, specifying the namespace is optional.
Does not allow for connecting to a Service.	Allows connecting to a Service.
Must provide the Pod's name to run the command.	When connecting to a Pod, must provide the Pod's IP.
Needs to be executed once for each different Pod the user wants to connect to.	Only needs to be executed once for connecting to different targets.

Related Projects

• kubectl-plugin-socks5-proxy - structured like kubectl-portal, but runs a SOCKS5 proxy instead of an HTTP one.

Additional Links

Additional useful information can be found here:

• Kubernetes - DNS for Services and Pods
• Kubernetes - Proxies in Kubernetes
• Kubernetes - Access Services Running on Clusters
• MDN - Proxy servers and tunneling
• Wikipedia - HTTP tunnel

License

Distributed under the GNU General Public License, version 3.

See LICENSE for more information.