Kind cluster creation fails on final port mapping step if using a `macvlan` docker network

[saffronjam]

What happened:

We tried to create a Kind cluster using a pre-created docker network named kind of type macvlan.

Since a macvlan docker network does not support port mapping, the final step in the Kind cluster creation fails.

What you expected to happen:

To skip the final port mapping step.

fyi: Omitting the port mapping behavior in the source code and building it ourselves solves this issue for us, and is our current work around. But it would be nice to not need to do that.

How to reproduce it:

1. Create a docker network of type macvlan, must be named kind

docker network create -d macvlan --subnet=... --ip-range=... --gateway=... -o parent=... kind

2. Create a Kind cluster

3. Wait for it to fail in the end of creation:

ERROR: failed to create cluster: failed to get api server port: command "docker inspect --format '{{ with (index (index .NetworkSettings.Ports "6443/tcp") 0) }}{{ printf "%s	%s" .HostIp .HostPort }}{{ end }}' test-control-plane" failed with error: exit status 1

Environment:

• kind version: 0.30.0
• Runtime info: Docker 28.5.1
• OS: Ubuntu 24.04
• Kubernetes version: v1.34.0

[stmcginnis]

We could maybe detect the network type and skip the port mapping.

Or... I'm not sure the implications of using macvlan, so it may be better to not support it at all. @aojea do you know if using something like macvlan would work, beyond just the changes needed to not try to do port mapping?

[aojea]

what is the use case for using a macvlan network for a kind clusteR?

[saffronjam]

@aojea macvlan means giving each Kind node its own host-network IP, so no port-mapping is required to access it (or better phrased, access is managed by your firewall etc. ). It's just another device in the network.

It sort of mimics a cluster running on VMs/Bare metal

[aojea]

It sort of mimics a cluster running on VMs/Bare metal

in which sense, only difference is that you can connect the kind nodes to the physical network where the vm/server that runs kind, but I do not see why do we want to generalize this ... for power users of networking with more advanced scenarios we offer an api so they can maintain the complexity for their specific use cases https://github.com/aojea/kind-networking-plugins

[saffronjam]

in which sense, only difference is that you can connect...

It was just that "only difference" that made it work for us and made us chose Kind! Simplicity.
From a purely usability standpoint, I think it make sense to support a network type that is supported by Docker. We have not found any issues with Kind on macvlan type network at all so far, it was solely the port mapping that was an issue for us.

But I understand your point of view, we will simply maintain a fork with our patch in the worst case.

[stmcginnis]

Just adding a data point, not for or against. It does appear podman support macvlan, so at least this wouldn't be another gotcha for folks running different providers.

[aojea]

But I understand your point of view, we will simply maintain a fork with our patch in the worst case.

we can try to simplify your life, if you are able to suggest a patch that is reasonable ... but we do not want to grow the scope to support multiple networks or complex network configurations for the kind nodes, power end users like you can handle and support that ... but then people will start to get creative and will end opening bug to use because who knows what they have configured

[BenTheElder]

Hmmm ... The kind network is basically the docker default network but with embedded DNS enabled, it's supposed to be an implementation detail and there's a reason we don't document that legacy "experimental" environment variable anywhere.

I still think we should just drop this env because it's completely unnecessary for testing Kubernetes or developing Kubernetes applications but it opens up lots of possible bugs that aren't relevant to the documented use cases.

On Linux you can typically also address the nodes by IP in bridge mode from the host, and Macvlan isn't supported on Mac / windows. This seems awfully niche to add more branching logic / behavior.

kind doesn't pretend to support arbitrary docker features.