k3d with podman remote does not need DOCKER_SOCK

[niule-eu]

What

The remote podman section in the advanced usage docs did not work for me. Changing DOCKER_HOST to export DOCKER_HOST=ssh://username@hostname/run/user/1000/podman/podman.sock did.

Why

When using k3d with a remote podman socket, it seems to be necessary to set DOCKER_HOST to a combination of DOCKER_HOST and DOCKER_SOCK

Implications

This has the potential to improve the docs. I was not able to confirm if this is an issue only relevant to my setup or to others as well.

k3d version v5.8.3
k3s version v1.31.5-k3s1 (default)

Client:        Podman Engine
Version:       5.6.2
API Version:   5.6.2
Go Version:    go1.25.1 X:nodwarf5
Git Commit:    9dd5e1ed33830612bc200d7a13db00af6ab865a4
Built:         Tue Sep 30 00:00:00 2025
Build Origin:  Fedora Project
OS/Arch:       linux/amd64

[Copilot]

Pull request overview

This PR updates the remote Podman documentation to simplify the setup by combining DOCKER_HOST and DOCKER_SOCK into a single SSH URL. The format ssh://username@hostname/socket/path aligns with Podman's native connection URI format as shown in podman system connection ls output.

Key changes:

• Consolidates DOCKER_HOST and DOCKER_SOCK environment variables into a single DOCKER_HOST SSH URL that includes the socket path
• Removes the need to separately export DOCKER_SOCK for remote Podman connections

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The removal of DOCKER_SOCK may cause issues with features that use the tools container. The DOCKER_SOCK environment variable is read by k3d's GetRuntimePath() function (in pkg/runtimes/docker/docker.go:96) and used to mount the socket into the tools container (in pkg/client/tools.go:436).

When DOCKER_SOCK is not set, it defaults to /var/run/docker.sock, which would be incorrect for rootless Podman where the socket is at /run/user/1000/podman/podman.sock. While including the socket path in the DOCKER_HOST SSH URL works for the Docker client library, k3d doesn't currently parse the socket path from SSH URLs in GetRuntimePath().

Consider either:

1. Keeping DOCKER_SOCK as a separate variable (as shown in the macOS section examples at lines 138-140 and 148-149), or
2. Updating k3d's code to extract the socket path from SSH-protocol DOCKER_HOST URLs

Note: Line 139 also has an inconsistency - it uses DOCKER_SOCKET instead of DOCKER_SOCK.

Suggested change

	export DOCKER_HOST=ssh://username@hostname/run/user/1000/podman/podman.sock
	export DOCKER_HOST=ssh://username@hostname/run/user/1000/podman/podman.sock
	export DOCKER_SOCK=/run/user/1000/podman/podman.sock