MTU Configuration in the Gefyra CLI#

Significance of MTU in Gefyra#

The Maximum Transmission Unit (MTU) defines the largest packet size that can be transmitted over a network interface without fragmentation. In Gefyra, MTU configuration is critical for the reliability and performance of the VPN tunnel (WireGuard) and the Docker network that bridge your local development environment with a Kubernetes cluster. An incorrect MTU setting can cause network fragmentation, dropped packets, or degraded connectivity between your local containers and the cluster.

When the MTU is not explicitly specified, Gefyra allows WireGuard to auto-detect the appropriate value. This auto-detection ensures optimal performance for your specific network environment. You can also explicitly set the MTU when needed for specific network configurations or to work around connectivity issues.

Setting MTU via CLI#

Gefyra allows you to configure the MTU at all major CLI entry points. The --mtu option is available for client configuration, connection setup, and cluster installation. When not specified, WireGuard automatically detects the appropriate MTU value.

1. Client Configuration#

Set the MTU when generating a client configuration file:

gefyra clients config <CLIENT_ID> --mtu 1400

If omitted, WireGuard will auto-detect the appropriate MTU value.

2. Connection Setup#

Specify the MTU when connecting your local machine to a Gefyra cluster:

gefyra connections connect --client-config <CONFIG_FILE> --mtu 1400

If not specified, WireGuard will auto-detect the MTU value.

Custom Cargo Image#

You can also specify a custom Cargo container image during connection setup:

gefyra connections connect --client-config <CONFIG_FILE> --cargo-image your-custom-cargo-image:tag

This option is useful if you need to use a custom Cargo image for compatibility or customization purposes. If not specified, Gefyra uses the default Cargo image.

3. Cluster Installation (`up` command)#

Set the MTU during cluster installation:

gefyra up --mtu 1400

When an MTU value is explicitly provided, it is propagated to both the WireGuard interface and the Docker network used by Gefyra. When omitted, WireGuard auto-detects the MTU, and the Docker network MTU option is not set.

MTU Consistency and Automatic Checks#

When an explicit MTU value is provided, Gefyra checks that the Docker network's MTU matches the configured WireGuard MTU. If a mismatch is detected, Gefyra logs a warning and suggests removing and recreating the Docker network to ensure consistency. This helps prevent subtle connectivity issues that can arise from MTU mismatches between the VPN tunnel and the container network.

Troubleshooting MTU Issues#

MTU Mismatch Warning: If you see a warning about an MTU mismatch, follow the suggestion to remove the Docker network and let Gefyra recreate it with the correct MTU. For example:
```
docker network rm gefyra-network-default
```
Then rerun your Gefyra command.
Connectivity Problems: If you experience dropped connections, timeouts, or unreliable networking between your local containers and the cluster, try lowering the MTU value (e.g., to 1280 or 1200) and retesting.
Cloud/VPN Environments: Some cloud providers or VPNs impose lower MTU limits. If you are running Gefyra in such environments, explicitly set a lower MTU using the --mtu flag as shown above.
Logs and Diagnostics: Always review Gefyra's log output for actionable warnings or errors related to MTU. The CLI provides clear guidance when a configuration issue is detected.