A tool for handling port-forwards to multiple services and across multiple clusters.
The setup is currently based on [cargo] until platform-specific binaries can be provided. To install the latest version (or update to it), run:
shell
cargo install k8sfwd
Please note that the application internally relies on kubectl, so it needs to be present in your path.
If kubectl is not on your path, you may specify it via the --kubectl argument or
the KUBECTL_PATH environment variable.
Depending on your configuration, you'll be greeted with something along the lines of:
``` ██╗░░██╗░█████╗░░██████╗░░░░░███████╗██╗░░░░░░░██╗██████╗ ██║░██╔╝██╔══██╗██╔════╝░██╗░██╔════╝██║░░██╗░░██║██╔══██╗ █████═╝░╚█████╔╝╚█████╗░░╚═╝░█████╗░░╚██╗████╗██╔╝██║░░██║ ██╔═██╗░██╔══██╗░╚═══██╗░██╗░██╔══╝░░░████╔═████║░██║░░██║ ██║░╚██╗╚█████╔╝██████╔╝░╚═╝░██║░░░░░░╚██╔╝░╚██╔╝░██████╔╝ ╚═╝░░╚═╝░╚════╝░╚═════╝░░░░░░╚═╝░░░░░░░╚═╝░░░╚═╝░░╚═════╝ k8s:fwd 0.2.0 - a Kubernetes multi-cluster port forwarder Using kubectl version v1.24.12-dispatcher Using config from 2 locations
Forwarding to the following targets:
target: service/foo.test-api context: (default) cluster: (default)
target: pod/foo-59b58f5d68-6t6bh.test-api context: (default) cluster: production
Spawning child processes:
```
Targets can be selected through prefix filters specified on the command-line. Only
targets (and target names) starting with the specified prefixes will be forwarded.
In the following example, services starting with foo and bar will be selected:
shell
k8sfwd foo bar
Filters can operate in combination with tags as well:
shell
k8sfwd -t test foo bar
Targets can be labeled with tags. When k8sfwd is started with one or more space-separated
--tags parameters, targets are filtered down to match the selection. If multiple values
are specified (e.g. --tags foo bar), any matching tag results in the target being selected.
If two tags are combined with a plus sign (e.g. --tags foo+bar) only targets matching both
tags are selected.
| Target tags | --tags argument | Selected |
|-------------------------|------------------------|----------|
| (none) | (none) | ✅ yes |
| (none) | --tags some | ❌ no |
| ["foo", "bar", "baz"] | (none) | ✅ yes |
| ["foo", "bar", "baz"] | --tags fubar | ❌ no |
| ["foo", "bar", "baz"] | --tags foo bar | ✅ yes |
| ["foo", "bar", "baz"] | --tags bar | ✅ yes |
| ["foo", "bar", "baz"] | --tags foo+baz | ✅ yes |
| ["foo", "bar", "baz"] | --tags foo+fubar | ❌ no |
| ["foo", "bar", "baz"] | --tags foo+baz fubar | ✅ yes |
| ["fubar"] | --tags foo+baz fubar | ✅ yes |
The configuration is provided as a YAML file.
--file argument(s), their configuration is loaded.k8sfwd will recursively look for a .k8sfwd file in
Non-target configuration (e.g., retry delays) are always loaded from the hierarchy stated above regardless
of whether a --file argument is present. However, all target configuration that is not directly specified
through a file pointed to by the --file argument is ignored.
See k8sfwd-example.yaml for an example.
version: 0.1.0
config:
# Optional: Number of seconds to wait before attempting to re-establish
# a broken connection.
retrydelaysec: 5.0
targets:
- name: Test API (Staging) # Optional, for display purposes.
target: foo # The name of the resource to forward to.
tags: # Optional, for use with --tags <tag1> <tag2>+<tag3>
- integration
type: service # Can be service, deployment or pod.
namespace: bar # The namespace of the resource.
context: null # Optional; will default to current context.
cluster: null # Optional; will default to current cluster.
ports:
- "5012:80" # Forward resource port 80 to local port 5012.
- "8080" # Forward resource port 8080 to random local port.
- name: Test API (Production)
target: foo-59b58f5d68-6t6bh
type: pod
namespace: bar
cluster: production
listen_addrs: # Select the listen addresses; defaults to localhost.
- "127.1.0.1"
ports:
- "5012:80"
```