# Kuvel
\n## Overview
\nKuvel, A service discovery plugin for Velocity. It will automatically discover Minecraft servers and
\nregister\/unregister them within Velocity.<\/p>\n
## Features<\/p>\n
* Monitor Minecraft pods in a Kubernetes cluster and automatically register\/unregister them within
\n Velocity
\n* Create a LoadBalancer server and distribute players trying to join to the linked servers.
\n* Synchronize server names across multiple Velocity instances using Redis<\/p>\n
## Installing<\/p>\n
The Plugin can be downloaded
\nfrom Releases. Download `Kuvel.jar` and
\ninstall it into Velocity plugins directory. The config file requires initial setup as seen below.<\/p>\n
“`yml
\n# The kubernetes namespace to use for the server discovery.
\nnamespace: “”
\n# The prefix to use for the keys of the server labels or annotations.
\nlabel-key-prefix: “kuvel.azisaba.net”
\n# Server name synchronization by Redis is required in load-balanced environments using multiple Velocity instances.
\nredis:
\n group-name: “develop”
\n connection:
\n hostname: “redis”
\n port: 6379
\n # username is optional. if you have authentication enabled, you can use it here. Otherwise you can leave it blank or null.
\n username: “default”
\n # password is optional. if you have authentication enabled, you can use it here. Otherwise you can leave it blank or null.
\n password: “password”<\/p>\n
# label-selectors are used to filter Pods and ReplicaSets to be registered.
\nlabel-selectors:
\n – “kuvel.azisaba.net\/enable-server-discovery=true”
\n“`<\/p>\n
Alternatively you can use environment variables to configure Kuvel. The environment variable will override
\n the config.yml and are `KUVEL_NAMESPACE`, `KUVEL_LABEL_KEY_PREFIX`, `KUVEL_REDIS_GROUPNAME`,
\n`KUVEL_REDIS_CONNECTION_HOSTNAME`, `KUVEL_REDIS_CONNECTION_PORT`, `KUVEL_REDIS_CONNECTION_USERNAME`, and
\n`KUVEL_REDIS_CONNECTION_PASSWORD`.<\/p>\n
In order for Kuvel to monitor the server, you must request permission from Kubernetes. For Velocity pods, please allow get\/list\/watch to Pods
\nand ReplicaSets.<\/p>\n
“`yml
\napiVersion: v1
\nkind: ServiceAccount
\nmetadata:
\n name: velocity-account
\n namespace: default
\n—
\napiVersion: rbac.authorization.k8s.io\/v1
\nkind: ClusterRoleBinding
\nmetadata:
\n name: velocity-clusterrolebiding
\nroleRef:
\n apiGroup: rbac.authorization.k8s.io
\n kind: ClusterRole
\n name: view
\nsubjects:
\n– kind: ServiceAccount
\n name: velocity-account
\n namespace: default
\n“`
\n“`yml
\n# Apply ServiceAccount to the Velocity pod
\napiVersion: apps\/v1
\nkind: …
\n# …
\nspec:
\n serviceAccountName: velocity-account
\n# …
\n“`<\/p>\n
## Enable Service Discovery on the Minecraft Servers<\/p>\n
To tell Kuvel that the pod is a Minecraft server, use the Kubernetes label service.
\nThe label keys and values are specified in the config file. By default, the label key
\nis `kuvel.azisaba.net\/enable-server-discovery` and the value is `true`.<\/p>\n
The following labels are also used for some other features.<\/p>\n
| Label Name | Value |
\n|:—————————————:|:—————————————————–:|
\n| kuvel.azisaba.net\/preferred-server-name | Name of the server you wish to register with Velocity |
\n| kuvel.azisaba.net\/initial-server | true \/ false |
\n| kuvel.azisaba.net\/disable-name-suffix | true \/ false |<\/p>\n
If server names longer than 63 characters are desired, the `kuvel.azisaba.net\/preferred-server-name` annotation can be used instead of the label.
\nIf `kuvel.azisaba.net\/disable-name-suffix=true` is set on a Pod, Kuvel will register the server name exactly as `preferred-server-name` (no `-1` suffix). If multiple replicas are detected, Kuvel logs an error and skips the extra pods. This label is intended for single-replica Pods only.<\/p>\n
### Pod<\/p>\n
“`yml
\napiVersion: v1
\nkind: Pod
\nmetadata:
\n name: test-server
\n labels:
\n kuvel.azisaba.net\/enable-server-discovery: “true” # Required for Kuvel to detect Minecraft servers. Depends on your config.
\n kuvel.azisaba.net\/preferred-server-name: “test-server” # Required for Kuvel to name the server
\n # kuvel.azisaba.net\/initial-server: “true” # Uncomment this line if you want to make this server the initial server.
\n # kuvel.azisaba.net\/disable-name-suffix: “true” # Use the exact preferred name (no -1 suffix); single replica only.
\nspec:
\n containers:
\n – name: test-server
\n image: itzg\/minecraft-server:java8
\n ports:
\n – containerPort: 25565
\n“`<\/p>\n
### Deployment
\n“`yml
\napiVersion: apps\/v1
\nkind: Deployment
\nmetadata:
\n name: test-server-deployment
\nspec:
\n replicas: 2
\n selector:
\n matchLabels:
\n app: test-server-deployment
\n template:
\n metadata:
\n labels:
\n app: test-server-deployment
\n kuvel.azisaba.net\/enable-server-discovery: “true” # Required for Kuvel to detect Minecraft servers. Depends on your config.
\n kuvel.azisaba.net\/preferred-server-name: “test-server” # Required for Kuvel to name the server
\n # kuvel.azisaba.net\/initial-server: “true” # Uncomment this line if you want to make this server the initial server.
\n spec:
\n containers:
\n – name: test-server
\n image: itzg\/minecraft-server:java8
\n ports:
\n – containerPort: 25565
\n“`<\/p>\n
In both cases, the server is registered under the name `test-server`.<\/p>\n
However, if there are two or more servers with the same name, a number will be assigned after the server name. For example, if there are two pods with the server name `test-server`, one will be `test-server` and the other will be `test-server-1`.<\/p>\n
## Load Balancer<\/p>\n
On parallelizable servers such as Lobby servers, it is sometimes desirable to distribute the number of players as evenly as possible. This is where Kuvel’s LoadBalancer feature comes in handy.<\/p>\n
“`yml
\napiVersion: apps\/v1
\nkind: Deployment
\nmetadata:
\n name: lobby-deployment
\n labels:
\n kuvel.azisaba.net\/enable-server-discovery: “true”
\n kuvel.azisaba.net\/preferred-server-name: “lobby”
\n # kuvel.azisaba.net\/initial-server: “true” # Uncomment this line if you want to make this load balancer server the initial server.
\nspec:
\n replicas: 3
\n selector:
\n matchLabels:
\n app: lobby-deployment
\n template:
\n metadata:
\n labels:
\n app: lobby-deployment
\n kuvel.azisaba.net\/enable-server-discovery: “true”
\n kuvel.azisaba.net\/preferred-server-name: “lobby”
\n # kuvel.azisaba.net\/initial-server: “true” # Uncomment this line if you want to make this server the initial server.
\n spec:
\n containers:
\n – name: lobby
\n image: itzg\/minecraft-server:java8
\n ports:
\n – containerPort: 25565
\n“`<\/p>\n
By applying a Label to a Deployment, Kuvel’s LoadBalancer feature can be activated. Kuvel’s LoadBalancer has the following features.<\/p>\n
1. Distribute players who try to join the Load Balancer server randomly to the pods under ReplicaSet.
\n2. Synchronize with Kubernetes ReplicaSet and automatically register\/unregister forwarding destinations.<\/p>\n
Using this, you can implement a mechanism to randomly connect to `lobby-1`, `lobby-2`, or `lobby-3` when `\/server lobby` is invoked.<\/p>\n
## Synchronize Server Names in Multi Velocity Environments<\/p>\n
In a Kubernetes cluster, pods can be created at almost the same time, and this can cause different
\nVelocity servers to have different registration names. This can cause fatal issues in a parallel
\nVelocity environment. Kuvel provides name synchronization using Redis to avoid this
\nissue. Kuvel uses keys whose key name begins with `kuvel:`.<\/p>\n
On 1.x, this feature was optional, but from 2.0.0, this setting is enabled by default.<\/p>\n
## License
\n[GNU General Public License v3.0](LICENSE)<\/p>\n","protected":false},"excerpt":{"rendered":"
Server-discovery Velocity plugin for Minecraft servers running in a Kubernetes cluster.<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"kuvel","_minecraft_project_id":"lvEw465O","_minecraft_author":"acrylic-style","_minecraft_license":"GPL-3.0-or-later","_minecraft_downloads":504,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"kuvel.zip","_minecraft_size_bytes":119368575,"_minecraft_version_count":8,"_minecraft_updated_at":"2026-05-16T10:30:24.572593Z","_minecraft_date_created":"2024-08-19T02:22:07.432654Z","_minecraft_date_modified":"2026-04-07T10:46:04.811166Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/kuvel","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-05T05:12:44+00:00","_minecraft_import_hash":"3da672ab70ce5a7430e4c44090ba7429","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[123,92,985],"mod_loader":[986],"minecraft_version":[48,49,50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82,83,167],"class_list":["post-91318","mod","type-mod","status-publish","hentry","mod_category-technology","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-16-5","minecraft_version-1-17","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1"],"yoast_head":"\n