From 5bb54d6918ffac3e4ccb88974dbcdeea82d5b20b Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Sat, 18 Oct 2025 21:54:50 -0500 Subject: [PATCH 1/4] Started a kubernetes troubleshooting section --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index b5c0b22..e2b21ce 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +
+Use the outline drop down to jump to a section☝️ +
+ [![GitHub issues](https://img.shields.io/github/issues/itzg/mc-router.svg)](https://github.com/itzg/mc-router/issues) [![Docker Pulls](https://img.shields.io/docker/pulls/itzg/mc-router.svg)](https://cloud.docker.com/u/itzg/repository/docker/itzg/mc-router) [![test](https://github.com/itzg/mc-router/actions/workflows/test.yml/badge.svg)](https://github.com/itzg/mc-router/actions/workflows/test.yml) @@ -366,6 +370,19 @@ spec: - name: mc ``` +### Troubleshooting + +First and foremost, enable debug logs on mc-router by setting the `DEBUG` environment variable to "true". With that, the logs will be fairly verbose with information about incoming connections, handshake processing, backend service discovery, and backend connection establishment and teardown. + +If backend service discovery doesn't seem to be happening, then double-check the service annotations, [described above](#using-kubernetes-service-auto-discovery), are applied to the backend `Service` objects and that those are selecting a Minecraft service deployment each. + +If the client reports "Connection refused" check: + +- `Service` type is configured as `NodePort` (or `LoadBalancer` if applicable) +- Use `kubectl describe service mc-router` for the next few steps + - If running on a home network, ensure the public internet router is port forwarding TCP 25565 to one of the kubernetes nodes and the reported `NodePort` value, usually in the 30000-32767 range. + - Ensure the `Endpoints` field contains at least one entry referencing the cluster IP address of the mc-router `Pod`. If not, check that the `Selector` matches the labels on the mc-router `Pod`. + ## REST API * `GET /routes` (with `Accept: application/json`) From 24cdb84973c3a596cb0a74d918e073b3d2b03c3a Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Sat, 18 Oct 2025 22:01:24 -0500 Subject: [PATCH 2/4] See if align=right works in github rendering --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 45031a5..168b6fc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -
+
Use the outline drop down to jump to a section☝️
From c837aa145d00a14f5696b82a311dd08271193e3b Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Sat, 18 Oct 2025 22:19:00 -0500 Subject: [PATCH 3/4] Added a better summary description --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 168b6fc..3025ce1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -
-Use the outline drop down to jump to a section☝️ -
- [![GitHub issues](https://img.shields.io/github/issues/itzg/mc-router.svg)](https://github.com/itzg/mc-router/issues) [![Docker Pulls](https://img.shields.io/docker/pulls/itzg/mc-router.svg)](https://cloud.docker.com/u/itzg/repository/docker/itzg/mc-router) [![test](https://github.com/itzg/mc-router/actions/workflows/test.yml/badge.svg)](https://github.com/itzg/mc-router/actions/workflows/test.yml) @@ -9,7 +5,18 @@ Use the outline drop down to jump to a section☝️ [![Discord](https://img.shields.io/discord/660567679458869252?label=discord)](https://discord.gg/JK2v3rJ9ec) [![Buy me a coffee](https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-orange.svg)](https://www.buymeacoffee.com/itzg) -Routes Minecraft client connections to backend servers based upon the requested server address. +Routes Minecraft Java Edition client connections to backend servers based upon the requested server address. This is quite helpful for home network deployments where any number of Minecraft servers can be multiplexed onto a single, public IP address and standard Minecraft port. It's best suited to work with [itzg/minecraft-server](https://github.com/itzg/docker-minecraft-server), but can be used with any Minecraft server. Stand-alone binaries are also published for Linux, Mac, and Windows if not wanting to use containers at all. + +Some other features included: + +- Dynamic auto-discovery of backend servers in Kubernetes and Docker which allows for "zero-config" mapping of your Minecraft server hostnames to backend servers protected behind mc-router. +- Minimizes unwanted intrusions by disallowing Minecraft port scanners that are not specifying a mapped server hostname. +- Rate limits incoming connections to reduce DDoS attacks. +- Can be configured to allow/deny IP addresses or ranges +- Includes a webhook integration for notifying other systems when a player connects and disconnects from a server. +- Can auto-scale (between zero and one) backend servers deployed as Kubernetes StatefulSets. +- Built-in ngrok integration where mc-router acts as an agent +- Exports/exposes metrics for various Prometheus and InfluxDB. If enabled, includes player login metrics. ## Usage From 2dc684b3fad9a5e0863642eba59566119cef7b70 Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Sat, 18 Oct 2025 22:19:59 -0500 Subject: [PATCH 4/4] Tweak wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3025ce1..22af4b1 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Discord](https://img.shields.io/discord/660567679458869252?label=discord)](https://discord.gg/JK2v3rJ9ec) [![Buy me a coffee](https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-orange.svg)](https://www.buymeacoffee.com/itzg) -Routes Minecraft Java Edition client connections to backend servers based upon the requested server address. This is quite helpful for home network deployments where any number of Minecraft servers can be multiplexed onto a single, public IP address and standard Minecraft port. It's best suited to work with [itzg/minecraft-server](https://github.com/itzg/docker-minecraft-server), but can be used with any Minecraft server. Stand-alone binaries are also published for Linux, Mac, and Windows if not wanting to use containers at all. +Routes Minecraft Java Edition client connections to backend servers based upon the requested server address. This is quite helpful for home network deployments where any number of Minecraft servers can be multiplexed onto a single, public IP address and standard Minecraft port. It works great with [itzg/minecraft-server](https://github.com/itzg/docker-minecraft-server), but can be used with any Minecraft server. Stand-alone binaries are also published for Linux, Mac, and Windows if not wanting to use containers at all. Some other features included: