Run the CLI in a container

The laptop CLI reads your kubeconfig and sees requests it diverts. Running it in a container places a VM or container boundary around the process and lets you control which files and networks it can access.

The published laptop image is:

ghcr.io/flaticols/outprobe:latest

This is separate from ghcr.io/flaticols/outprobe-relay:v0.0.16, which runs in the cluster.

Two connections must cross the boundary

1. CLI → local app. Inside a container, localhost is the container, not the host. Override LOCAL_TARGET with a host-access name.
2. CLI → Kubernetes API. The in-process port-forward uses ordinary outbound API traffic. It usually works directly unless the API is reachable only through a host VPN.

Apple container

Start the system and create a host-access DNS name once:

container system start
sudo container system dns create host.container.internal --localhost 203.0.113.113

Apple container mounts your macOS home into its Linux VM at the same paths. From the project directory:

container run --rm -it \
  --workdir "$PWD" \
  --env KUBECONFIG="$HOME/.kube/config" \
  --env LOCAL_TARGET=http://host.container.internal:8080 \
  ghcr.io/flaticols/outprobe:latest up

KUBECONFIG is explicit because the image runs as root and its own home is /root. LOCAL_TARGET overrides the shared config only inside the container.

The default home mount is broad

Apple container’s convenient home mount is read-write and can expose .ssh, .aws, and other files. Set the machine home mount to read-only or none and add narrow explicit volumes for tighter isolation.

Docker Desktop

Docker Desktop provides host.docker.internal and does not share your home automatically. Bind only what the CLI needs:

docker run --rm -it \
  -v "$HOME/.kube:/root/.kube:ro" \
  -v "$PWD:/work:ro" -w /work \
  -e LOCAL_TARGET=http://host.docker.internal:8080 \
  ghcr.io/flaticols/outprobe:latest up

Mounting the kubeconfig at /root/.kube lets client-go use its default location. The read-only project mount still exposes .outprobe.yaml and custom .outprobe/ manifests.

On Docker Engine for Linux, add:

--add-host=host.docker.internal:host-gateway

Cloud kubeconfig credential plugins

macOS credential plugins do not run in Linux

GKE and EKS kubeconfigs commonly use an exec plugin such as gke-gcloud-auth-plugin or aws eks get-token. A plugin installed on macOS is a macOS binary, even if its path is visible through a mount; the Linux container cannot execute it.

Use one of these approaches:

• a self-contained token- or certificate-based kubeconfig for the isolated run;
• a custom CLI image containing the Linux build of the required credential plugin;
• a credential helper reachable and executable inside the container.

Host VPNs

If the Kubernetes API is reachable only over a VPN running on the host, the container may not inherit that route. Configure the runtime’s host-access networking, run the VPN inside the VM/container, or use a kube API endpoint reachable from the container network.

Apple networking notes

Creating a --localhost DNS domain can disable iCloud Private Relay. The packet-filter rule may also disappear after a reboot, requiring the dns create command again. Consult the Apple container networking guide for current behavior.

Teardown behavior

Keep the CLI in the foreground with --rm -it. Ctrl-C reaches outprobe, which removes routing first and then the relay before the container exits. If the runtime is killed ungracefully, run outprobe down with the same kube context and namespace.