Kubernetes Installation

Deploy Gate on Kubernetes with manifests, Kustomize, and complete network examples

Gate’s Docker images are designed for Kubernetes deployments, providing scalable and reliable proxy infrastructure for your Minecraft network.

Prerequisites

Before deploying Gate to Kubernetes, ensure you have:

Kubernetes Cluster

Running cluster (kind, minikube, k3s, k3d, GKE, EKS, AKS, etc.)

kubectl

Kubernetes CLI tool installed and configured

Kustomize

(Optional) For advanced manifest management

Lens Desktop

(Optional) Kubernetes IDE for easier management

New to Kubernetes? Try kind for local development or k3d for lightweight clusters.

Quick Start: All-in-One Example

Deploy a complete Gate proxy with two Minecraft servers in one command:

kubectl apply -f https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes/bundle.yaml

This creates:

• Gate proxy deployment
• Two Minecraft server pods (StatefulSet)
• NodePort service on port 32556
• ConfigMaps for configuration

1. Deploy the bundle

   kubectl apply -f https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes/bundle.yaml
   
2. Wait for pods to be ready

   kubectl get pods -w
   

   Wait until all pods show Running status.

3. Connect to Gate

   Connect your Minecraft client to <node-ip>:32556

   Find your node IP:

   kubectl get nodes -o wide
   
4. Test server switching

   In-game, use /server server-0 or /server server-1 to switch between servers.

   Try deleting a server pod to see Gate automatically reconnect players:

   kubectl delete pod server-0
   

View complete bundle.yaml manifest

The bundle includes everything needed for a complete Minecraft network:

apiVersion: v1
data:
  config.yml: |
    config:
      bind: 0.0.0.0:25565
      servers:
        server-0: server-0.servers:25565
        server-1: server-1.servers:25565
      try:
        - server-0
        - server-1
kind: ConfigMap
metadata:
  name: gate-config
---
apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: NodePort
  ports:
  - port: 25565
    targetPort: minecraft
    protocol: TCP
    nodePort: 32556
  selector:
    app.kubernetes.io/component: proxy
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: proxy
  template:
    metadata:
      labels:
        app.kubernetes.io/component: proxy
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate:latest
        ports:
        - containerPort: 25565
          name: minecraft
        volumeMounts:
        - name: config
          mountPath: /config.yml
          subPath: config.yml
      volumes:
      - name: config
        configMap:
          name: gate-config
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: server
spec:
  replicas: 2
  serviceName: servers
  selector:
    matchLabels:
      app.kubernetes.io/component: server
  template:
    metadata:
      labels:
        app.kubernetes.io/component: server
    spec:
      containers:
      - name: minecraft-server
        image: itzg/minecraft-server:latest
        env:
        - name: EULA
          value: "TRUE"
        - name: TYPE
          value: "PUFFERFISH"
        - name: ONLINE_MODE
          value: "FALSE"
        ports:
        - containerPort: 25565
          name: minecraft

Using Kustomize (Recommended)

Kustomize provides a structured way to manage Kubernetes manifests. Gate’s examples use Kustomize for easier customization.

1. Clone the repository

   git clone https://github.com/minekube/gate.git
   cd gate/.examples/kubernetes
   
2. Review the structure

   The example includes:

   • kustomization.yaml - Main Kustomize configuration
   • deploy.yaml - Gate deployment
   • svc.yaml - Gate service
   • config.yml - Gate configuration
   • servers/ - Minecraft server manifests
3. Customize for your needs

   Edit the files to match your environment:

   config.yml

   config:
     bind: 0.0.0.0:25565
     servers:
       lobby: lobby.minecraft.svc:25565
       survival: survival.minecraft.svc:25565
     try:
       - lobby
   
4. Preview the generated manifests

   kustomize build .
   

   This shows what will be deployed without actually deploying.

5. Deploy to Kubernetes

   kubectl apply -k .
   
6. Clean up when done

   kubectl delete -k .
   

Overlay Your Own Kustomize

Create your own Kustomize that extends Gate’s example:

kustomization.yaml

resources:
  - https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes

patchesStrategicMerge:
  - patch.yaml

namespace: minecraft

images:
  - name: ghcr.io/minekube/gate
    newTag: 0.42.2  # Pin to specific version

Create a patch file:

patch.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  replicas: 3  # Scale Gate to 3 replicas
  template:
    spec:
      containers:
      - name: gate
        resources:
          limits:
            memory: 512Mi
            cpu: 500m
          requests:
            memory: 256Mi
            cpu: 250m

Manual Deployment

For more control, deploy Gate components individually:

1. Create ConfigMap for Gate configuration

   kubectl create configmap gate-config --from-file=config.yml
   
2. Create Gate Deployment

   gate-deployment.yaml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: gate
     labels:
       app: gate
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: gate
     template:
       metadata:
         labels:
           app: gate
       spec:
         containers:
         - name: gate
           image: ghcr.io/minekube/gate:latest
           ports:
           - containerPort: 25565
             name: minecraft
             protocol: TCP
           volumeMounts:
           - name: config
             mountPath: /config.yml
             subPath: config.yml
           resources:
             limits:
               memory: "512Mi"
               cpu: "500m"
             requests:
               memory: "256Mi"
               cpu: "250m"
         volumes:
         - name: config
           configMap:
             name: gate-config
   

   Apply it:

   kubectl apply -f gate-deployment.yaml
   
3. Create Gate Service

   gate-service.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: gate
   spec:
     type: LoadBalancer  # Use LoadBalancer for cloud, NodePort for local
     selector:
       app: gate
     ports:
     - port: 25565
       targetPort: 25565
       protocol: TCP
       name: minecraft
   

   Apply it:

   kubectl apply -f gate-service.yaml
   
4. Get the external IP

   kubectl get service gate
   

   For LoadBalancer, wait for EXTERNAL-IP to be assigned. For NodePort, use any node IP with the assigned node port.

Service Types

Choose the appropriate service type for your environment:

LoadBalancer

Best for: Cloud providers (GKE, EKS, AKS)

apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: LoadBalancer
  ports:
  - port: 25565
    targetPort: 25565
  selector:
    app: gate

Automatically provisions a cloud load balancer with external IP.

NodePort

Best for: Local clusters, bare metal

apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: NodePort
  ports:
  - port: 25565
    targetPort: 25565
    nodePort: 32556  # Optional: specify port (30000-32767)
  selector:
    app: gate

Exposes Gate on each node’s IP at the specified port.

Ingress

Best for: TCP proxying with ingress controller

Requires ingress controller with TCP support (nginx-ingress, traefik).

apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: ClusterIP
  ports:
  - port: 25565
  selector:
    app: gate
---
# Configure TCP proxy in ingress controller
# Example for nginx-ingress:
# Add to tcp-services ConfigMap:
# 25565: "default/gate:25565"

Bedrock Edition Support

For Bedrock Edition support, use the JRE variant image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  template:
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate/jre:latest  # JRE variant
        ports:
        - containerPort: 25565
          name: minecraft-java
          protocol: TCP
        - containerPort: 19132
          name: minecraft-bedrock
          protocol: UDP

Update the service to expose UDP port:

apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  ports:
  - port: 25565
    protocol: TCP
    name: java
  - port: 19132
    protocol: UDP
    name: bedrock

Monitoring and Troubleshooting

Check pod status

kubectl get pods -l app=gate
kubectl describe pod <pod-name>

View logs

kubectl logs -f deployment/gate

# For specific pod:
kubectl logs -f <pod-name>

# Previous container logs (if crashed):
kubectl logs <pod-name> --previous

Check service endpoints

kubectl get endpoints gate

Verify that endpoints are listed (pods are ready).

Test connectivity inside cluster

kubectl run -it --rm debug --image=busybox --restart=Never -- sh
# Inside the pod:
nc -zv gate 25565

ConfigMap not updating

After updating a ConfigMap, restart the deployment:

kubectl rollout restart deployment/gate

Or use ConfigMap versioning in Kustomize with configMapGenerator.

Production Best Practices

Use resource limits

Set memory and CPU limits to prevent resource exhaustion:

resources:
  limits:
    memory: 512Mi
    cpu: 500m
  requests:
    memory: 256Mi
    cpu: 250m

Enable readiness probes

Ensure traffic only goes to ready pods:

readinessProbe:
  tcpSocket:
    port: 25565
  initialDelaySeconds: 5
  periodSeconds: 10

Use multiple replicas

Run multiple Gate instances for high availability:

spec:
  replicas: 3

Pin image versions

Avoid unexpected changes with specific versions:

image: ghcr.io/minekube/gate:0.42.2

Next Steps

Configuration

Customize Gate for your network

Scaling

Scale Gate for high player counts