Network
| API version | kobblestone.io/v1alpha1 |
|---|---|
| Kind | Network |
| Scope | Namespaced |
| kubectl | kubectl get networks |
A Network runs a Velocity proxy and the Servers behind it.
Managed servers (the default) are Server resources created and kept compatible by the Network: they are rendered from serverTemplate and their entry in servers, and always trust the proxy (modern forwarding with the network’s secret, offline mode, reachable only through the proxy). An existing Server joins the network, keeping its data, by naming it in servers[].serverName.
Unmanaged entries (unmanaged: true) only add an existing Server or Network to the proxy’s configuration, without configuring it.
The proxy runs as a Deployment. The operator also manages its Service, configuration and forwarding Secret and, if configured, its Route and TCPRoute.
spec
proxyobjectConfigures the Velocity proxy.
9 fields
configstringCustom velocity.toml.
The operator always sets servers, forced-hosts, player-info-forwarding-mode (modern) and forwarding-secret-file (and online-mode if offline is true), overriding the values given here.
contentobjectConfigures plugins and the server icon of the proxy.
forwardingSecretRefobjectReference to a key of a Secret containing the forwarding secret shared with the backend servers.
If not set, a random secret is generated. Managed servers are configured with it automatically; unmanaged servers have to be configured with it manually.
Note: Only read when the network’s own Secret is created.
jvmobjectConfigures the JVM of the proxy.
1 field
memoryobjectConfigures memory settings for the JVM.
1 field
heapPercentageint32Configures the percentage of memory reserved for the heap.
Default is 75.
Note: For low-memory deployments, you might have to lower this.
- Minimum: 1
- Maximum: 99
offlinebooleanIf set to true, the proxy runs in offline mode (online-mode = false): player accounts are not verified.
Default is false.
podobjectConfigures the proxy Pods.
6 fields
affinityobjectAffinity of the proxy Pod.
3 fields
nodeAffinityobject2 fields
1 field
nodeSelectorTerms[]objectpodAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringpodAntiAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringimagestringCustom image for the proxy container.
Default is itzg/mc-proxy.
imagePullPolicystringImage pull policy of the proxy container.
nodeNamestringName of the node the proxy Pod is scheduled on.
nodeSelectormap[string]stringNode selector of the proxy Pod.
tolerations[]objectTolerations of the proxy Pod.
replicasint32Number of proxy replicas.
Default is 1.
resourcesobjectCompute resources of the proxy container.
versionstringVelocity version.
Default is LATEST.
routeobjectConfigures a Route that makes the network reachable through a Router under a hostname.
Removing it deletes the Route.
serverDeletionPolicystringWhat happens to a managed Server when it is removed from servers or the Network is deleted.
Default is Retain.
Values:
Retain: TheServerand its data are kept. It leaves the network and runs as a standalone server again (forwarding is removed, so it verifies players itself).Delete: TheServeris deleted, including its data.
- One of:
Retain,Delete
serverTemplateobjectThe software, version and EULA shared by all managed servers, and defaults for their other settings. Each managed server’s spec is merged onto it.
Required if the network has managed servers.
17 fields
accessobjectWhitelist and operators, see Server spec.access.
2 fields
opsobjectConfigures the operators of the server.
1 field
users[]stringPlayers with operator permissions, as usernames or UUIDs.
Note: The operators are synchronized: players not listed here lose their operator permissions.
whitelistobjectConfigures the whitelist. Only whitelisted players can join.
autoCommandsobjectCommands executed via RCON on certain events, see Server spec.autoCommands.
5 fields
onConnect[]stringCommands executed when a player connects.
onDisconnect[]stringCommands executed when a player disconnects.
onFirstConnect[]stringCommands executed when the first player connects to the empty server.
onLastDisconnect[]stringCommands executed when the last player disconnects.
onStartup[]stringCommands executed once the server has started.
autoSleepobjectSleeping while no players are online, see Server spec.autoSleep.
Note: Hibernate is not supported behind a proxy, because nothing wakes the server up again.
2 fields
modestringHow the server sleeps while no players are online.
Default is Pause.
Values:
None: The server never sleeps.Pause: The server pauses ticking while it is empty (requires Minecraft 1.21.2 or later).Hibernate: The server is stopped while it is empty and started again when a player connects through aRouter.LegacyPause: The server process is paused while it is empty, using the autopause feature of the image. For older versions.
- One of:
None,Pause,Hibernate,LegacyPause
timeoutSecondsint32Time in seconds without players after which the server goes to sleep.
Default is 60.
- Minimum: 1
contentobjectPlugins, mods, modpacks and other content, see Server spec.content.
9 fields
curseForgeobjectConfigures content from CurseForge.
3 fields
apiKeySecretRefobjectReference to a key of a Secret containing a CurseForge API key. Required to download from CurseForge.
files[]stringCurseForge projects or files to install, by slug, ID or URL.
modPackUrlstringURL of the CurseForge page of a modpack to install. Requires the server type AutoCurseforge.
iconUrlstringURL of an image used as the server icon.
modPackUrlstringURL of a modpack ZIP file to install.
modrinthobjectConfigures content from Modrinth.
1 field
projects[]stringModrinth projects to install, by slug or ID.
packwizUrlstringURL of a packwiz pack.toml to install.
plugins[]objectPlugins to install, for server types that support plugins (e.g. Paper).
1 field
URL of the plugin .jar file.
resourcePackobjectConfigures a resource pack that players are prompted to download.
spigotResources[]stringIDs of Spigot resources to install.
Whether you accept the Minecraft EULA for all servers of the network. The servers do not start unless this is true.
jvmobjectJVM settings, see Server spec.jvm.
2 fields
memoryobjectConfigures memory settings for the JVM.
1 field
heapPercentageint32Configures the percentage of memory reserved for the heap.
Default is 75.
Note: For low-memory servers, you might have to lower this.
- Minimum: 1
- Maximum: 99
versionstringConfigures a specific version of the JVM to be used.
Default is java25.
Note: This corresponds to the Java part of the server image tag. See Image tags.
lifecycleobjectLifecycle settings, see Server spec.lifecycle.
1 field
rolloutPolicystringSpecifies when changes to spec are rolled out to running servers.
Default is Immediate.
Values:
Immediate: Changes tospecare rolled out immediately. For example, if you updatespec.version, the server will be restarted.Manual: Changes tospecare rolled out when the serverPodis recreated, e.g. when the server is stopped and started again or thePodis deleted. Note: This does not apply to restarts of the server container after a crash.
- One of:
Immediate,Manual
networkPolicyobjectThe server’s NetworkPolicy, see Server spec.networkPolicy.
2 fields
disabledbooleanIf set to true, the server’s default NetworkPolicy will not be created.
Default is false.
extraIngressRules[]objectAdditional Ingress rules applied to the policy.
2 fields
from[]object3 fields
namespaceSelectorobjectpodSelectorobjectpodobjectConfigures the server Pod, see Server spec.pod.
9 fields
affinityobjectAffinity of the server Pod.
3 fields
nodeAffinityobject2 fields
1 field
nodeSelectorTerms[]objectpodAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringpodAntiAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringenv[]objectAdditional environment variables of the server container.
Can be used to set any option of the image that is not covered by the Server spec.
3 fields
namestringvaluestringvalueFromobjectimagestringCustom image for the server container.
Default is itzg/minecraft-server with the Java version of spec.jvm.version.
imagePullPolicystringImage pull policy of the server container.
nodeNamestringName of the node the server Pod is scheduled on.
nodeSelectormap[string]stringNode selector of the server Pod.
tolerations[]objectTolerations of the server Pod.
volumeMounts[]objectAdditional volume mounts of the server container.
8 fields
bindMountOptions[]stringmountPathstringmountPropagationstringnamestringreadOnlybooleanrecursiveReadOnlystringsubPathstringsubPathExprstringvolumes[]objectAdditional volumes of the server Pod.
31 fields
awsElasticBlockStoreobjectazureDiskobjectazureFileobjectcephfsobjectconfigMapobjectcsiobject5 fields
driverstringfsTypestringnodePublishSecretRefobject1 field
namestringreadOnlybooleanvolumeAttributesmap[string]stringdownwardAPIobject3 fields
defaultModeint32defaultUserint64ephemeralobject1 field
volumeClaimTemplateobject2 fields
metadataobjectspecobject9 fields
accessModes[]stringdataSourceobjectdataSourceRefobjectselectorobjectstorageClassNamestringvolumeModestringvolumeNamestringflexVolumeobjectflockerobjectgcePersistentDiskobjectgitRepoobjectimageobjectiscsiobject11 fields
chapAuthDiscoverybooleanchapAuthSessionbooleanfsTypestringinitiatorNamestringiqnstringiscsiInterfacestringlunint32portals[]stringreadOnlybooleantargetPortalstringnamestringpersistentVolumeClaimobjectphotonPersistentDiskobjectportworxVolumeobjectprojectedobject3 fields
defaultModeint32defaultUserint64sources[]object6 fields
clusterTrustBundleobject6 fields
labelSelectorobjectnamestringoptionalbooleanpathstringsignerNamestringuserint64configMapobjectdownwardAPIobjectpodCertificateobject8 fields
certificateChainPathstringcredentialBundlePathstringkeyPathstringkeyTypestringmaxExpirationSecondsint32signerNamestringuserint64userAnnotationsmap[string]stringsecretobjectserviceAccountTokenobjectrbdobjectscaleIOobject10 fields
fsTypestringgatewaystringprotectionDomainstringreadOnlybooleansslEnabledbooleanstorageModestringstoragePoolstringsystemstringvolumeNamestringsecretobjectstorageosobjectvsphereVolumeobjectpropertiesmap[string]stringAdditional entries for server.properties, see Server spec.properties.
rconobjectRemote console of the server, see Server spec.rcon.
3 fields
disabledbooleanIf set to true, RCON is disabled.
Default is false.
Note: Commands, CommandGroups, autoCommands and online Backups require RCON.
passwordSecretRefobjectReference to a key of a Secret containing the RCON password.
If not set, a random password is generated.
Note: Only read when the server’s own Secret is created.
portint32Port of RCON on the server’s Service. Inside the Pod, RCON always listens on 25575.
Default is 25575.
resourcesobjectCompute resources of the server container.
statestringDesired state of the server, see Server spec.state.
Default is Running.
- One of:
Stopped,Running
storageobjectPersistent volume for the server’s data, see Server spec.storage.
Warning: Without storage, the server’s world is lost whenever its Pod is recreated.
2 fields
Size of the PersistentVolumeClaim, e.g. 10Gi.
Note: Increasing the size requires a storage class that supports volume expansion.
storageClassNamestringStorage class of the PersistentVolumeClaim.
Default is the default storage class of the cluster.
Note: Only applied when the claim is created.
timeoutsobjectHealth checks, see Server spec.timeouts.
2 fields
Maximum time in seconds the server may take to start before it is restarted.
Default is 360. Must be a multiple of 5.
Type of the server software of all servers, see Server spec.type.
Only types that can trust a Velocity proxy are supported: Paper, Pufferfish, Purpur, Folia, Fabric, Quilt.
- One of:
Vanilla,Bukkit,Spigot,Fabric,Forge,Magma,Ketting,Mohist,Catserver,Spongevanilla,Limbo,Crucible,Paper,Pufferfish,Purpur,Folia,Quilt,AutoCurseforge
Minecraft version of all servers, see Server spec.version.
servers[]objectServers of the network.
The order matters: players join the first available server with try enabled, in the order of this list, unless a forced host applies. If several servers share a hostname, they are tried in this order as well.
Note: The proxy only reads its configuration on startup, so it is restarted whenever this list changes in a way that affects it: servers added, removed, renamed or reordered, or a changed hostname or try. Players connected to the proxy are disconnected. Servers that are created, deleted or restarted do not restart the proxy.
7 fields
hostnamestringHostname that sends players directly to this server (forced host).
If several servers have the same hostname, players join the first available one, in the order of servers.
Name of the server in the proxy, e.g. for /server <name>.
For managed servers, the Server resource is named <network>-<name> unless serverName is set.
- Maximum length: 63
- Pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
serverNamestringName of the managed Server resource in the network’s namespace.
Default is <network>-<name>. If a Server with this name already exists and does not belong to another network, it joins the network and keeps its data.
Only for managed servers.
- Maximum length: 63
- Pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
specobjectSettings of this managed server, merged onto serverTemplate: objects are merged field by field, all other values (including lists) replace the template’s value.
type, version and eula are shared by all servers and only set in serverTemplate.
Only for managed servers.
14 fields
accessobjectWhitelist and operators, see Server spec.access.
2 fields
opsobjectConfigures the operators of the server.
1 field
users[]stringPlayers with operator permissions, as usernames or UUIDs.
Note: The operators are synchronized: players not listed here lose their operator permissions.
whitelistobjectConfigures the whitelist. Only whitelisted players can join.
autoCommandsobjectCommands executed via RCON on certain events, see Server spec.autoCommands.
5 fields
onConnect[]stringCommands executed when a player connects.
onDisconnect[]stringCommands executed when a player disconnects.
onFirstConnect[]stringCommands executed when the first player connects to the empty server.
onLastDisconnect[]stringCommands executed when the last player disconnects.
onStartup[]stringCommands executed once the server has started.
autoSleepobjectSleeping while no players are online, see Server spec.autoSleep.
Note: Hibernate is not supported behind a proxy, because nothing wakes the server up again.
2 fields
modestringHow the server sleeps while no players are online.
Default is Pause.
Values:
None: The server never sleeps.Pause: The server pauses ticking while it is empty (requires Minecraft 1.21.2 or later).Hibernate: The server is stopped while it is empty and started again when a player connects through aRouter.LegacyPause: The server process is paused while it is empty, using the autopause feature of the image. For older versions.
- One of:
None,Pause,Hibernate,LegacyPause
timeoutSecondsint32Time in seconds without players after which the server goes to sleep.
Default is 60.
- Minimum: 1
contentobjectPlugins, mods, modpacks and other content, see Server spec.content.
9 fields
curseForgeobjectConfigures content from CurseForge.
3 fields
apiKeySecretRefobjectReference to a key of a Secret containing a CurseForge API key. Required to download from CurseForge.
files[]stringCurseForge projects or files to install, by slug, ID or URL.
modPackUrlstringURL of the CurseForge page of a modpack to install. Requires the server type AutoCurseforge.
iconUrlstringURL of an image used as the server icon.
modPackUrlstringURL of a modpack ZIP file to install.
modrinthobjectConfigures content from Modrinth.
1 field
projects[]stringModrinth projects to install, by slug or ID.
packwizUrlstringURL of a packwiz pack.toml to install.
plugins[]objectPlugins to install, for server types that support plugins (e.g. Paper).
1 field
URL of the plugin .jar file.
resourcePackobjectConfigures a resource pack that players are prompted to download.
spigotResources[]stringIDs of Spigot resources to install.
jvmobjectJVM settings, see Server spec.jvm.
2 fields
memoryobjectConfigures memory settings for the JVM.
1 field
heapPercentageint32Configures the percentage of memory reserved for the heap.
Default is 75.
Note: For low-memory servers, you might have to lower this.
- Minimum: 1
- Maximum: 99
versionstringConfigures a specific version of the JVM to be used.
Default is java25.
Note: This corresponds to the Java part of the server image tag. See Image tags.
lifecycleobjectLifecycle settings, see Server spec.lifecycle.
1 field
rolloutPolicystringSpecifies when changes to spec are rolled out to running servers.
Default is Immediate.
Values:
Immediate: Changes tospecare rolled out immediately. For example, if you updatespec.version, the server will be restarted.Manual: Changes tospecare rolled out when the serverPodis recreated, e.g. when the server is stopped and started again or thePodis deleted. Note: This does not apply to restarts of the server container after a crash.
- One of:
Immediate,Manual
networkPolicyobjectThe server’s NetworkPolicy, see Server spec.networkPolicy.
2 fields
disabledbooleanIf set to true, the server’s default NetworkPolicy will not be created.
Default is false.
extraIngressRules[]objectAdditional Ingress rules applied to the policy.
2 fields
from[]object3 fields
namespaceSelectorobjectpodSelectorobjectpodobjectConfigures the server Pod, see Server spec.pod.
9 fields
affinityobjectAffinity of the server Pod.
3 fields
nodeAffinityobject2 fields
1 field
nodeSelectorTerms[]objectpodAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringpodAntiAffinityobject2 fields
2 fields
podAffinityTermobject6 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringweightint326 fields
labelSelectorobjectmatchLabelKeys[]stringmismatchLabelKeys[]stringnamespaceSelectorobjectnamespaces[]stringtopologyKeystringenv[]objectAdditional environment variables of the server container.
Can be used to set any option of the image that is not covered by the Server spec.
3 fields
namestringvaluestringvalueFromobjectimagestringCustom image for the server container.
Default is itzg/minecraft-server with the Java version of spec.jvm.version.
imagePullPolicystringImage pull policy of the server container.
nodeNamestringName of the node the server Pod is scheduled on.
nodeSelectormap[string]stringNode selector of the server Pod.
tolerations[]objectTolerations of the server Pod.
volumeMounts[]objectAdditional volume mounts of the server container.
8 fields
bindMountOptions[]stringmountPathstringmountPropagationstringnamestringreadOnlybooleanrecursiveReadOnlystringsubPathstringsubPathExprstringvolumes[]objectAdditional volumes of the server Pod.
31 fields
awsElasticBlockStoreobjectazureDiskobjectazureFileobjectcephfsobjectconfigMapobjectcsiobject5 fields
driverstringfsTypestringnodePublishSecretRefobject1 field
namestringreadOnlybooleanvolumeAttributesmap[string]stringdownwardAPIobject3 fields
defaultModeint32defaultUserint64ephemeralobject1 field
volumeClaimTemplateobject2 fields
metadataobjectspecobject9 fields
accessModes[]stringdataSourceobjectdataSourceRefobjectselectorobjectstorageClassNamestringvolumeModestringvolumeNamestringflexVolumeobjectflockerobjectgcePersistentDiskobjectgitRepoobjectimageobjectiscsiobject11 fields
chapAuthDiscoverybooleanchapAuthSessionbooleanfsTypestringinitiatorNamestringiqnstringiscsiInterfacestringlunint32portals[]stringreadOnlybooleantargetPortalstringnamestringpersistentVolumeClaimobjectphotonPersistentDiskobjectportworxVolumeobjectprojectedobject3 fields
defaultModeint32defaultUserint64sources[]object6 fields
clusterTrustBundleobject6 fields
labelSelectorobjectnamestringoptionalbooleanpathstringsignerNamestringuserint64configMapobjectdownwardAPIobjectpodCertificateobject8 fields
certificateChainPathstringcredentialBundlePathstringkeyPathstringkeyTypestringmaxExpirationSecondsint32signerNamestringuserint64userAnnotationsmap[string]stringsecretobjectserviceAccountTokenobjectrbdobjectscaleIOobject10 fields
fsTypestringgatewaystringprotectionDomainstringreadOnlybooleansslEnabledbooleanstorageModestringstoragePoolstringsystemstringvolumeNamestringsecretobjectstorageosobjectvsphereVolumeobjectpropertiesmap[string]stringAdditional entries for server.properties, see Server spec.properties.
rconobjectRemote console of the server, see Server spec.rcon.
3 fields
disabledbooleanIf set to true, RCON is disabled.
Default is false.
Note: Commands, CommandGroups, autoCommands and online Backups require RCON.
passwordSecretRefobjectReference to a key of a Secret containing the RCON password.
If not set, a random password is generated.
Note: Only read when the server’s own Secret is created.
portint32Port of RCON on the server’s Service. Inside the Pod, RCON always listens on 25575.
Default is 25575.
resourcesobjectCompute resources of the server container.
statestringDesired state of the server, see Server spec.state.
Default is Running.
- One of:
Stopped,Running
storageobjectPersistent volume for the server’s data, see Server spec.storage.
Warning: Without storage, the server’s world is lost whenever its Pod is recreated.
2 fields
Size of the PersistentVolumeClaim, e.g. 10Gi.
Note: Increasing the size requires a storage class that supports volume expansion.
storageClassNamestringStorage class of the PersistentVolumeClaim.
Default is the default storage class of the cluster.
Note: Only applied when the claim is created.
timeoutsobjectHealth checks, see Server spec.timeouts.
2 fields
Maximum time in seconds the server may take to start before it is restarted.
Default is 360. Must be a multiple of 5.
targetRefobjectReference to the Server or Network to forward players to.
Supported kinds: Server (default), Network.
Only for unmanaged servers.
trybooleanWhether players are sent to this server when they join the network (Velocity’s try list, in the order of servers). Servers with try disabled are only reachable via /server or their hostname.
Default is true.
unmanagedbooleanIf set to true, the server is not managed by the network: the proxy only forwards players to targetRef, and the target has to be configured to trust the proxy manually.
targetRef is required, serverName and spec must not be set.
Default is false.
serviceobjectConfigures the Service of the proxy.
5 fields
annotationsmap[string]stringAnnotations added to the proxy’s Service, e.g. to configure a load balancer.
externalTrafficPolicystringExternal traffic policy of the proxy’s Service.
ipFamilyPolicystringIP family policy of the proxy’s Service.
portint32Port on the Service that exposes Minecraft.
Default is 25565.
typestringType of the proxy’s Service, e.g. ClusterIP or LoadBalancer.
Default is ClusterIP.
tcpRouteobjectConfigures an optional TCPRoute exposing the Networks Minecraft port.
Note: Using TCPRoute requires at least Gateway API v1.6.0 to be installed on your cluster.
1 field
parentRefs[]objectReferences to gateways the TCPRoute should attach to.
status
addressstringIP address of the proxy’s Service. External addresses are preferred: the IP assigned by a load balancer, then the first of externalIPs, then the cluster IP.
messagestringMessage explaining the current state of the Network, e.g. why a server cannot be managed.
proxyReadystringReady proxy replicas out of the desired ones, e.g. 1/1.
proxyReadyReplicasint32Number of proxy replicas that are ready to accept players.
proxyReplicasint32Desired number of proxy replicas (spec.proxy.replicas).
readyServersint32Number of running servers of the network.
serverCountint32Number of servers of the network.
servers[]objectState of each server of the network.
5 fields
managedbooleanWhether the server is managed by the network.
messagestringWhy the server cannot be managed, if so.
namestringName of the server in the proxy.
phasestringPhase of the Server (status.phase), or Missing if it does not exist.
serverstringName of the Server resource, or of the target of an unmanaged entry.
serversReadystringRunning servers out of all servers of the network, e.g. 2/3.
tcpRoutebooleanWhether a managed TCPRoute exists.