Skip to main content

Override the Default Docker Network

Details​

⚠️ Docker Bridge Network Conflict Warning

CubeCOS automatically configures a Docker bridge network during installation using the 172.17.0.0/16 subnet. This default subnet facilitates container-to-container communication within the local Docker network.

However, in some environments, this subnet may conflict with existing private network ranges, leading to:

  • Inability for containers to access external services
  • Broken communication between containers and the host
  • Overlapping routes resulting in unpredictable network behaviour

✅ Conflict Scenario

Conflicts arise when:

  1. The existing network infrastructure uses 172.17.0.0/16
  2. The CubeCOS cluster management network is assigned the same subnet

To avoid IP conflicts, override the default Docker bridge subnet configuration by assigning a custom non-overlapping subnet.

Solution​

warning

This fix must be applied before starting the installation of CubeCOS nodes.

It must be implemented before any internet connectivity is configured, as CubeCOS nodes will not have external access at this stage.

To apply the fix, use USB media to manually transfer the configuration tool or patch file to each node before installation. This ensures the Docker bridge network is correctly overridden and avoids subnet conflicts during deployment.

The Docker IP change tool uses the following new Docker subnets:

  1. Base network: 172.31.0.0/16
  2. BIP: 172.30.0.1/24

Pre-Requisite​

  1. Download the IP change tool: change-docker-ip.zip
  2. Verify the contents of the tool, the extracted zip contains the following files:
    1. change-docker-ip.sh: The function script that will modify and change the default Docker IP subnet.
    2. daemon.json: The Docker subnet configuration file.

Log into each CubeCOS node​

    unconfigured login: root
    Password:
    Last login: Thu May  1 23:02:34 on tty1
    Welcome to CUBE_2.4.3_20240905-0425_b37483f3

Identify the USB device​

    lsblk

Identify the USB device with lsblk

Mount the USB device to the filesystem​

    mount /dev/vdc1 /mnt/usb
    lsblk

Mount the USB device to the filesystem

List and confirm the change tool​

    cd /mnt/usb/
    ls

List and confirm change tool

Execute the Docker network change tool​

    ./change-docker-ip.sh

Execute the Docker network change tool

Unmount the USB​

    cd ~
    umount /mnt/usb
    lsblk

Unmount the USB

Continue with CubeCOS installation​

Once the network conflict fix is in place, continue with the cluster deployment by following the CubeCOS Installation guide.

Last updated on by Brian Su