IPv6 & Docker

The latest Docker, at the time of writing, does support IPv6. But there are a number of pitfalls when people try to work around this.

Here are some experiences I got, and I put a working configuration at the end of the article:

Pitfalls

1. Do not use macvlan

macvlan is a new mode of Docker network. It tries to distribute the actual IP addresses among containers instead of virtual subnet IPs (e.g. 172.200.0.1/24).

Naturally, since we got a bunch of real and global IPv6 IP addresses, we would attempt to use macvlan to distribute them directly. Don't do it. It just does not work like that.

2. ​The default gateway generated by Docker could be wrong

For some reasons, some times (but not always) the default gateway generated by Docker could be problematic, you need to delete the default gateway (ip -6 route del default and ip -6 route add default) to make it work.

3. ​Use the ip tool

Always use the command of ip -6 for the network management. Don't bother to use ifconfig or route -6.

4. ​Use the IPv6 ONLY sites for testing

Some sites support both IPv4 and IPV6. Always use the IPv6 only sites for the diagnosis, e.g. curl -6 ipv6.myexternalip.com/raw. Currently, it's impossible to have a docker container without IPv4.

Steps to create a IPv6 Docker container

Here are the detailed steps to create an IPv6 Docker container:

1. ​Select a range of IPv6 to be used by the containers:

Say, the IP allocated by ISP is:

1234:1234:1234:1234::/64 (See previous article)

you may consider to allocate a sub-block to the Docker containers, e.g.

1234:1234:1234:1234::/80

Total IP available is (2^48)

2. Create a docker network

docker network create -d bridge --subnet=172.200.6.0/24 --ipv6 --subnet="1234:1234:1234:1234::/80" --opt "com.docker.network.bridge.name"="br-v6slave" v6slave

3. ​Put the following in the dockercompose file:

4. Start the container

docker-compose up -d
docker exec -it my_container bash

5. Update default network route

Depend on the ISP configuration, you may need to update the default network (I found it necessary for linode instances).

ip route del default via old_gate_way
ip route add default via 1234:1234:1234:1234::1 dev eth0

If it works, the following command should show your IPv6 IP inside the container:

curl -6 ipv6.myexternalip.com/raw

And you should be able to see 1234:1234:1234:1234::34

6. rotate the IP using iptables (optional)

Sometimes you may want to switch the IP for the container instances (e.g. load balance experiments). Use the following command in the host machine:

ip6tables -t nat -I POSTROUTING -p all -s 1234:1234:1234:1234::34 -j SNAT --to-source 1234:1234:1234:1234:6::34

Note that 1234:1234:1234:1234:6::34 is outside of container network scope.

Login into the container again, you should be able to see your machine IP is changed to 1234:1234:1234:1234:6::34